Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(cli): make every command report what it returned (#6172)

Joeye34ea63dc699
diff --git a/.changeset/command-result-reporting.md b/.changeset/command-result-reporting.md
new file mode 100644
index 0000000000..cf0eaddb53
--- /dev/null
+++ b/.changeset/command-result-reporting.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] Every command now reports what it returned in its debug logs, and a new command cannot skip it.
+
+A command's action returns a `CommandResult` — either `{kind: 'results', count, resultKind, ...}` or `{kind: 'none'}` for the commands whose work is an effect (build, init, upgrade, doctor). The CommandDoc converter records it centrally, so `resultCount`, `emptyResult`, `resultKind`, and `directMatch` are now populated for `component`, `docs`, `hook`, `template`, `theme list`/`add`/`targets`, `discover`, `blog`, `swizzle --list`, `upgrade --list`, `layout grammar`, and `manifest`, not just `search` and `build`. `resultKind` gains `theme`, `integration`, `migration`, `command`, and `none`; a null now means the run never reached an answer rather than "this command has nothing to say". That is a change of meaning on an existing field, so recorded runs are now `schemaVersion: 3` — a consumer that counted nulls as "commands with nothing to report" should branch on the version before mixing old rows with new ones.
+@josephfarina
diff --git a/packages/cli/authoring/debug/parse.mjs b/packages/cli/authoring/debug/parse.mjs
index 37666aae43..bdb8cc5033 100644
--- a/packages/cli/authoring/debug/parse.mjs
+++ b/packages/cli/authoring/debug/parse.mjs
@@ -43,10 +43,15 @@ const optionSourceSchema = z.enum([
const resultKindSchema = z.enum([
'component',
- 'template',
- 'doc',
'hook',
+ 'doc',
+ 'template',
+ 'theme',
+ 'integration',
+ 'migration',
+ 'command',
'mixed',
+ 'none',
]);
const invocationSourceSchema = z.enum(['human', 'ai', 'automation', 'unknown']);
@@ -118,7 +123,7 @@ const eventSchema = z
// records before the raw session id was retired, and refusing to read them
// back would make the privacy change look like data loss. What each version
// is ALLOWED to contain differs — see the refinement below.
- schemaVersion: z.union([z.literal(1), z.literal(2)]),
+ schemaVersion: z.union([z.literal(1), z.literal(2), z.literal(3)]),
id: z.string(),
startedAt: z.string(),
endedAt: z.string(),
diff --git a/packages/cli/authoring/debug/parse.test.mjs b/packages/cli/authoring/debug/parse.test.mjs
index 88effd831b..fa1d8d5fd7 100644
--- a/packages/cli/authoring/debug/parse.test.mjs
+++ b/packages/cli/authoring/debug/parse.test.mjs
@@ -89,6 +89,12 @@ function makeEvent({schemaVersion = 2, env = {}} = {}) {
}
describe('parseDebugEvent — schema versions', () => {
+ it('accepts a v3 record', () => {
+ expect(parseDebugEvent(makeEvent({schemaVersion: 3})).schemaVersion).toBe(
+ 3,
+ );
+ });
+
it('accepts a v2 record', () => {
expect(parseDebugEvent(makeEvent()).schemaVersion).toBe(2);
});
@@ -100,7 +106,7 @@ describe('parseDebugEvent — schema versions', () => {
});
it('rejects a version it has never emitted', () => {
- expect(() => parseDebugEvent(makeEvent({schemaVersion: 3}))).toThrow(
+ expect(() => parseDebugEvent(makeEvent({schemaVersion: 4}))).toThrow(
/schemaVersion/,
);
});
diff --git a/packages/cli/authoring/debug/type.ts b/packages/cli/authoring/debug/type.ts
index b468dc1457..d0d4a338bc 100644
--- a/packages/cli/authoring/debug/type.ts
+++ b/packages/cli/authoring/debug/type.ts
@@ -22,8 +22,13 @@
* - `2` — `env.agentSessionId` is always null; `env.agentSessionIdHash` is the
* join key, and the environment snapshot is scrubbed like every other
* recorded value.
+ * - `3` — every command reports its result. `output.resultKind` gained `none`
+ * (a command whose work is an effect) and a null now means the run never
+ * reached an answer, where before it meant "nothing was surfaced" — so a v1
+ * or v2 null and a v3 null are not the same fact and must not be counted
+ * together.
*/
-export type DebugSchemaVersion = 1 | 2;
+export type DebugSchemaVersion = 1 | 2 | 3;
/**
* How an invocation ended.
@@ -46,9 +51,25 @@ export type DebugOutcome =
export type DebugOptionSource =
'cli' | 'default' | 'env' | 'config' | 'implied';
-/** The kind of content represented by a command's result set. */
+/**
+ * The kind of content represented by a command's result set.
+ *
+ * `mixed` is a set spanning several kinds. `none` is the other thing entirely:
+ * the command answered with an EFFECT — it built, wrote, upgraded, validated,
+ * or diagnosed something — and has no set to count. Reading it as "found
+ * nothing" would be wrong; `emptyResult` is where that lives.
+ */
export type DebugResultKind =
- 'component' | 'template' | 'doc' | 'hook' | 'mixed';
+ | 'component'
+ | 'hook'
+ | 'doc'
+ | 'template'
+ | 'theme'
+ | 'integration'
+ | 'migration'
+ | 'command'
+ | 'mixed'
+ | 'none';
/** What initiated the CLI invocation, based only on positive evidence. */
export type DebugInvocationSource = 'human' | 'ai' | 'automation' | 'unknown';
@@ -81,14 +102,31 @@ export interface DebugEventOutput {
* floor, or presentation grouping was applied. A command that answers with a
* bounded slice still reports the size of the set it sliced, so a capped
* answer and an exactly-cap-sized one are distinguishable. Null when the
- * command has no result set.
+ * command has no result set — `resultKind` says which case that is.
*/
resultCount: number | null;
- /** Whether the command's underlying match set was empty. */
+ /** Whether the command's underlying match set was empty. Null when it has none. */
emptyResult: boolean | null;
- /** One surfaced result kind, `mixed`, or null when none was surfaced. */
+ /**
+ * What this run answered with: one result kind, `mixed`, or `none` for a
+ * command whose work is an effect rather than a lookup.
+ *
+ * `none` says nothing about SUCCESS — a command that failed on its way to an
+ * effect still reports it. Read `outcome` for that; filter to `ok` before
+ * treating a run as an effect that happened.
+ *
+ * Null means the run never reported one. On a completed run that is a bug in
+ * the CLI, not a property of the command — every command declares its result
+ * shape as its return type, and the recorder stamps it centrally. Expect null
+ * only where a run ended before its command could answer: a parse error, a
+ * rejected `--json`, `--help`, or a failure.
+ */
resultKind: DebugResultKind | null;
- /** Whether the command found a confident direct match, when it defines one. */
+ /**
+ * Whether the command resolved the exact thing that was asked for, rather
+ * than listing or suggesting. Null for the commands that define no such
+ * notion (a bare list has nothing to match).
+ */
directMatch: boolean | null;
/**
* Everything the command printed to stdout — the answer the user actually
diff --git a/packages/cli/clients/cli/bin/astryx.mjs b/packages/cli/clients/cli/bin/astryx.mjs
index 9ef24ce14a..b719de52a3 100755
--- a/packages/cli/clients/cli/bin/astryx.mjs
+++ b/packages/cli/clients/cli/bin/astryx.mjs
@@ -55,7 +55,8 @@ if (!isNodeVersionSupported(process.versions.node)) {
// Imports that transitively load `styleText` must happen AFTER the gate above,
// so they are dynamically imported here rather than at the top of the module.
-const {program, loadProjectDebugHandler} = await importSrc('index.mjs');
+const {program, loadProjectDebugHandler, handleVersionJsonPreflight} =
+ await importSrc('index.mjs');
const {isJsonMode, toErrorEnvelope} = await importSrc('../../foundation/response/json.mjs');
const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
const {setOutcome} = await importSrc('../../foundation/debug/index.mjs');
@@ -107,6 +108,10 @@ process.on('uncaughtException', handleFatal);
// `--help` — which short-circuit before any hook runs — are reported too.
await loadProjectDebugHandler();
+// `--version --json` answers and exits without Commander, so it runs here —
+// after the handler exists, or the run would go unrecorded.
+handleVersionJsonPreflight();
+
try {
await program.parseAsync(process.argv);
} catch (err) {
diff --git a/packages/cli/clients/cli/command-result-coverage.test.mjs b/packages/cli/clients/cli/command-result-coverage.test.mjs
new file mode 100644
index 0000000000..dbd8479a73
--- /dev/null
+++ b/packages/cli/clients/cli/command-result-coverage.test.mjs
@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every command that runs reports what it answered with.
+ *
+ * The contract is enforced twice, on purpose, because it has two holes and they
+ * are different shapes:
+ *
+ * 1. A command registered through `defineCommand` cannot forget: its action's
+ * RETURN TYPE is `CommandResult`, so a missing or wrong descriptor is a
+ * typecheck failure before the code ever runs. That is the real gate.
+ * 2. A command registered by hand — `program.command(...).action(...)` —
+ * bypasses the converter and therefore bypasses the type. Nothing about
+ * such a command looks wrong; it simply reports nothing, forever, and the
+ * only symptom is a column of nulls in somebody's query months later.
+ *
+ * This file is the second gate. It walks the ASSEMBLED program — the same one
+ * the binary runs — and requires every command that can execute to be on the
+ * reporting path. A new command fails here until someone makes a deliberate
+ * choice about what it answers with.
+ *
+ * @input the assembled Commander program
+ * @output a failure naming any command that would run unreported
+ * @position packages/cli/clients/cli — command coverage
+ */
+
+import {describe, it, expect} from 'vitest';
+import {program} from './index.mjs';
+import {reportsResult, reportsResultVia} from './lib/define-command.mjs';
+
+/**
+ * Commands with no action of their own: bare `astryx layout` prints its
+ * subcommand list and does nothing else, so there is no run to report on.
+ *
+ * Pinned as a SET rather than skipped silently — if a command joins this list,
+ * that is a real change to what the CLI does and it should be read, not
+ * absorbed. (`theme` is deliberately NOT here: it HAS an action — the one that
+ * rejects an unknown subcommand — so it goes through the converter like any
+ * other. Its bare form prints help and never returns from that action, which
+ * the recorder covers where help is recorded, not here.)
+ */
+const NO_ACTION_OF_THEIR_OWN = ['layout'];
+
+/**
+ * Commands that record for themselves instead of returning a descriptor.
+ *
+ * They cannot come from a CommandDoc — `manifest` introspects the live program,
+ * `postinstall` is a package-script hook — so they carry the mark by hand. The
+ * mark is a hatch, and a hatch nobody watches is a hole: this list is the
+ * watch. The root program is checked separately below.
+ */
+const RECORD_FOR_THEMSELVES = ['manifest', 'postinstall'];
+
+/**
+ * Every command in the program, depth first, with its fully qualified name.
+ * @param {import('commander').Command} parent
+ * @param {string} [prefix]
+ * @returns {Array<{name: string, command: import('commander').Command}>}
+ */
+function allCommands(parent, prefix = '') {
+ /** @type {Array<{name: string, command: import('commander').Command}>} */
+ const found = [];
+ for (const command of parent.commands) {
+ const name = prefix ? `${prefix} ${command.name()}` : command.name();
+ found.push({name, command});
+ found.push(...allCommands(command, name));
+ }
+ return found;
+}
+
+/** @param {import('commander').Command} command */
+const runs = command =>
+ typeof (/** @type {any} */ (command)._actionHandler) === 'function';
+
+describe('every command reports what it answered with', () => {
+ const commands = allCommands(program);
+
+ it('walks the real program', () => {
+ // A walk that finds nothing would pass every assertion below it. Guard the
+ // guard: this is the whole CLI, so the count is in the dozens.
+ expect(commands.length).toBeGreaterThan(20);
+ });
+
+ it('covers every command that can run', () => {
+ const unreported = commands
+ .filter(({command}) => runs(command) && !reportsResult(command))
+ .map(({name}) => name);
+ expect(unreported, unreported.length
+ ? `these commands run without reporting a result — return a CommandResult ` +
+ `from the action (see foundation/debug/command-result.mjs), or register ` +
+ `through defineCommand: ${unreported.join(', ')}`
+ : '',
+ ).toEqual([]);
+ });
+
+ it('covers the root program itself', () => {
+ // Bare `astryx` prints help; `astryx --json` prints the manifest. Both are
+ // runs, so both are reported.
+ expect(reportsResult(program)).toBe(true);
+ });
+
+ it('pins the commands allowed to record for themselves', () => {
+ // Everything else must go through the converter, where the return type is
+ // what makes the report unforgettable. Marking a hand-written command
+ // reporting nothing would otherwise pass every check in this file.
+ const manual = commands
+ .filter(({command}) => reportsResultVia(command) === 'manual')
+ .map(({name}) => name)
+ .sort();
+ const unexpected = manual.filter(
+ name => !RECORD_FOR_THEMSELVES.includes(name),
+ );
+ // Two very different causes, and the message has to name both: someone
+ // used the hatch instead of the contract, OR one of the real command
+ // MODULES failed to import and left its fallback stub in its place (the
+ // stub carries the mark, so it lands here). The second is a broken CLI,
+ // not a broken test.
+ expect(manual, unexpected.length
+ ? `unexpected commands recording for themselves: ${unexpected.join(', ')} ` +
+ `— either a hand-registered command is using markReportsResult instead ` +
+ `of returning a CommandResult, or that command's module failed to load ` +
+ `and left its fallback stub behind (run \`astryx <name>\` to see the ` +
+ `import error)`
+ : '',
+ ).toEqual([...RECORD_FOR_THEMSELVES].sort());
+ });
+
+ it('pins the commands that have no action at all', () => {
+ const actionless = commands
+ .filter(({command}) => !runs(command))
+ .map(({name}) => name)
+ .sort();
+ expect(actionless).toEqual([...NO_ACTION_OF_THEIR_OWN].sort());
+ });
+});
diff --git a/packages/cli/clients/cli/commands/blog.mjs b/packages/cli/clients/cli/commands/blog.mjs
index 310d8699eb..ee953e2365 100644
--- a/packages/cli/clients/cli/commands/blog.mjs
+++ b/packages/cli/clients/cli/commands/blog.mjs
@@ -20,6 +20,7 @@ import {emit, section, text, record, records, code} from '../formatters/index.mj
import {cliError} from '../lib/cli-error.mjs';
import {blog as blogApi} from '../../../api/blog/blog.mjs';
import {defineCommand} from '../lib/define-command.mjs';
+import {resultSet} from '../../../foundation/debug/index.mjs';
import {doc as blogCommand} from './blog.doc.mjs';
import {doc as blogFn} from '../../../api/blog/blog.doc.mjs';
@@ -37,16 +38,24 @@ export function registerBlog(program) {
result = await blogApi(slug);
} catch (e) {
const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {
+ return cliError(err.message, {
suggestions: err.suggestions || [],
code: err.code,
});
- return;
}
+ // A post is a doc: the feed lists them, a slug resolves one.
+ const answered =
+ result.type === 'blog.list'
+ ? resultSet({
+ count: result.data.posts.length,
+ resultKind: 'doc',
+ })
+ : resultSet({count: 1, resultKind: 'doc', directMatch: true});
+
if (program.opts().json) {
jsonOut(result);
- return;
+ return answered;
}
if (result.type === 'blog.list') {
@@ -56,7 +65,7 @@ export function registerBlog(program) {
section('Astryx blog', `feed: ${feedUrl}`),
text('No posts found in the feed.'),
);
- return;
+ return answered;
}
// One record per post — fields mirror the JSON post shape; empty
// fields (type/textUrl) are skipped by record().
@@ -70,6 +79,7 @@ export function registerBlog(program) {
// (code() so article typography/spacing isn't ASCII-normalized).
emit(record({feed: result.data.feedUrl}), code(result.data.text));
}
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjs
index 92b3fb0ef0..eebce7e52c 100644
--- a/packages/cli/clients/cli/commands/build-theme.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.mjs
@@ -45,6 +45,7 @@ import {
} from '../../../api/theme/palette/generate/generate.mjs';
import {themeBuild, importSpecifier} from '../../../api/theme/build/build.mjs';
import {defineCommand} from '../lib/define-command.mjs';
+import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
import {doc as themeGroup} from './theme.doc.mjs';
import {doc as themeBuildCommand} from './theme-build.doc.mjs';
import {doc as themeListCommand} from './theme-list.doc.mjs';
@@ -264,14 +265,14 @@ export function registerTheme(program) {
name,
reason: 'available subcommand',
}));
- cliError(`unknown subcommand 'theme ${unknown}'`, {
+ return cliError(`unknown subcommand 'theme ${unknown}'`, {
suggestions,
code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,
});
- return;
}
// Bare `astryx theme` — show the subcommand list. Exit 0 (help is success).
theme.help();
+ return NO_RESULT_SET;
},
});
@@ -298,13 +299,13 @@ export function registerTheme(program) {
name: command.name(),
reason: 'available subcommand',
}));
- cliError(`unknown subcommand 'theme palette ${String(extras[0])}'`, {
+ return cliError(`unknown subcommand 'theme palette ${String(extras[0])}'`, {
suggestions,
code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,
});
- return;
}
palette.help();
+ return NO_RESULT_SET;
},
});
@@ -324,14 +325,18 @@ export function registerTheme(program) {
} catch (error) {
const err =
/** @type {import('../../../api/error.mjs').AstryxError} */ (error);
- cliError(err.message, {
+ return cliError(err.message, {
suggestions: err.suggestions || [],
code: err.code,
});
- return;
}
- if (json) return jsonOut(result);
+ // Generating a palette computes and writes candidate files; the numbers
+ // that matter (families, stops, modes) are the receipt's, not a match set.
+ if (json) {
+ jsonOut(result);
+ return NO_RESULT_SET;
+ }
if (!result.data.output && !result.data.preview) {
emit(
section(
@@ -340,7 +345,7 @@ export function registerTheme(program) {
),
code(serializePaletteCandidate(result.data.candidate).trimEnd()),
);
- return;
+ return NO_RESULT_SET;
}
if (!result.data.written) {
emit(
@@ -349,7 +354,7 @@ export function registerTheme(program) {
),
text('Pass --overwrite to replace both generated candidate files.'),
);
- return;
+ return NO_RESULT_SET;
}
emit(
...(result.data.output
@@ -365,6 +370,7 @@ export function registerTheme(program) {
'Review and edit the candidate before adopting it as theme-owned palette data.',
),
);
+ return NO_RESULT_SET;
},
});
@@ -385,7 +391,7 @@ export function registerTheme(program) {
// A quoted glob reaches us unexpanded: say so rather than reporting a
// literal `themes/*.ts` as a missing file.
const looksGlobby = /[*?[\]{}]/.test(entry.file);
- cliError(`File not found: ${entry.filePath}`, {
+ return cliError(`File not found: ${entry.filePath}`, {
code: ERROR_CODES.ERR_FILE_NOT_FOUND,
suggestions: looksGlobby
? [
@@ -397,29 +403,26 @@ export function registerTheme(program) {
]
: undefined,
});
- return;
}
// --check and --watch are mutually exclusive: check is a one-shot,
// exit-coded verification; watch is a long-running rebuild loop.
if (options.check && options.watch) {
- cliError('--check cannot be combined with --watch', {
+ return cliError('--check cannot be combined with --watch', {
code: ERROR_CODES.ERR_THEME_INVALID,
});
- return;
}
// --out names one output file, so it cannot describe N themes. Without
// it each theme writes `<theme name>.css` beside its source, which is
// what a multi-theme build wants anyway.
if (options.out && entries.length > 1) {
- cliError(
+ return cliError(
`--out takes a single output path and ${entries.length} theme files were given. ` +
'Build them without --out (each theme writes <name>.css next to its source), ' +
'or run one invocation per theme.',
{code: ERROR_CODES.ERR_THEME_INVALID},
);
- return;
}
// Watch mode: run an initial build, then rebuild on every change to the
@@ -427,13 +430,12 @@ export function registerTheme(program) {
// supported in --json (machine) mode, which expects a single envelope.
if (options.watch) {
if (json) {
- cliError('--watch is not supported with --json', {
+ return cliError('--watch is not supported with --json', {
code: ERROR_CODES.ERR_THEME_INVALID,
});
- return;
}
await runThemeBuildWatch(entries, options);
- return;
+ return NO_RESULT_SET;
}
// Non-watch: delegate to the API compiler, once per theme, in argument
@@ -471,11 +473,10 @@ export function registerTheme(program) {
// Stop at the first failure, as a shell loop under `set -e` does.
// With several themes in flight the message alone rarely says which
// one broke, so name it.
- cliError(
+ return cliError(
entries.length > 1 ? `${entry.file}: ${err.message}` : err.message,
{suggestions: err.suggestions, code: err.code},
);
- return;
}
}
@@ -508,6 +509,10 @@ export function registerTheme(program) {
if (options.check && stale) {
process.exitCode = 1;
}
+
+ // Compiling a theme writes CSS; `--check` compares what is on disk. Both
+ // are effects — the receipt (and the exit code) carry the outcome.
+ return NO_RESULT_SET;
},
});
@@ -522,16 +527,23 @@ export function registerTheme(program) {
} catch (e) {
const err =
/** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {
+ return cliError(err.message, {
suggestions: err.suggestions || [],
code: err.code,
});
- return;
}
- if (json) return jsonOut(result);
+ const answered = resultSet({
+ count: result.data.length,
+ resultKind: 'theme',
+ });
+ if (json) {
+ jsonOut(result);
+ return answered;
+ }
printThemeList(result.data);
+ return answered;
},
});
@@ -562,18 +574,27 @@ export function registerTheme(program) {
} catch (e) {
const err =
/** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {
+ return cliError(err.message, {
suggestions: err.suggestions || [],
code: err.code,
});
- return;
}
- if (json) return jsonOut(result);
+ // `--list` (or no slug) browses the bundled themes; naming one copies it
+ // into the project, which is an effect with nothing to count.
+ const answered =
+ result.type === 'theme.list'
+ ? resultSet({count: result.data.length, resultKind: 'theme'})
+ : NO_RESULT_SET;
+
+ if (json) {
+ jsonOut(result);
+ return answered;
+ }
if (result.type === 'theme.list') {
printThemeList(result.data);
- return;
+ return answered;
}
// theme.add — print where files landed + how to use the theme.
@@ -596,6 +617,7 @@ export function registerTheme(program) {
`This is your copy of the ${displayName} theme — edit ${entry} to make it your own.`,
),
);
+ return answered;
},
});
@@ -618,14 +640,17 @@ export function registerTheme(program) {
} catch (e) {
const err =
/** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {
+ return cliError(err.message, {
suggestions: err.suggestions || [],
code: err.code,
});
- return;
}
- if (json) return jsonOut(result);
+ // Writes a starter theme file, or declines to overwrite one.
+ if (json) {
+ jsonOut(result);
+ return NO_RESULT_SET;
+ }
const invocation = getCliInvocation(process.cwd());
if (!result.data.written) {
@@ -633,7 +658,7 @@ export function registerTheme(program) {
text(`[skip] ${result.data.path} already exists — left as is.`),
text(`Pass --overwrite to replace it with a fresh copy.`),
);
- return;
+ return NO_RESULT_SET;
}
emit(
text(`[ok] Wrote ${result.data.path}`),
@@ -643,6 +668,7 @@ export function registerTheme(program) {
),
code(`${invocation} theme build ${result.data.path}`),
);
+ return NO_RESULT_SET;
},
});
@@ -658,14 +684,34 @@ export function registerTheme(program) {
} catch (e) {
const err =
/** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {
+ return cliError(err.message, {
suggestions: err.suggestions || [],
code: err.code,
});
- return;
}
- if (json) return jsonOut(result);
+ // A filter is a substring search with an exact-name fast path (see
+ // api/theme/targets), so the mere presence of one proves nothing: `theme
+ // targets a` matches everything. A direct match is the filter naming ONE
+ // component and getting only that component's targets back — which is
+ // exactly the exact-name branch, read off the answer.
+ const matched = new Set(
+ result.data.targets.map(target => target.component.toLowerCase()),
+ );
+ const answered = resultSet({
+ count: result.data.targets.length,
+ resultKind: 'theme',
+ // Falsy, not just null: the api treats an empty filter as no filter
+ // at all, so recording one as a match that missed would invent a
+ // failed lookup out of a run that never looked anything up.
+ directMatch: !filter
+ ? undefined
+ : matched.size === 1 && matched.has(String(filter).toLowerCase()),
+ });
+ if (json) {
+ jsonOut(result);
+ return answered;
+ }
const run = getCliInvocation();
const {targets, componentCount} = result.data;
@@ -683,6 +729,7 @@ export function registerTheme(program) {
].join('\n'),
),
);
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/build.mjs b/packages/cli/clients/cli/commands/build.mjs
index f172a106b5..7a318a7446 100644
--- a/packages/cli/clients/cli/commands/build.mjs
+++ b/packages/cli/clients/cli/commands/build.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file build command — thin wrapper with stable result telemetry.
+ * @file build command — thin wrapper with a stable result summary.
*
* astryx build → the PLAYBOOK (how to build a page)
* astryx build "<what>" → a COMPOSITION KIT (closest page template,
@@ -17,7 +17,7 @@ import {
formatCliCommand,
} from '../../../foundation/env/package-manager.mjs';
import {jsonOut} from '../../../foundation/response/json.mjs';
-import {recordResultSummary} from '../../../foundation/debug/index.mjs';
+import {resultSet, resultSetOf} from '../../../foundation/debug/index.mjs';
import {
emit,
section,
@@ -92,9 +92,16 @@ export function registerBuild(program) {
// No query → the playbook. Still routed through the API for the envelope.
if (!query || !String(query).trim()) {
const result = await buildApi(undefined, {cwd: process.cwd()});
- if (json) return jsonOut(result);
+ // The playbook is a document, not a lookup: one doc, always the same
+ // one. Counting it as a result keeps "what did this run answer with"
+ // true for the no-argument form too.
+ const playbook = resultSet({count: 1, resultKind: 'doc'});
+ if (json) {
+ jsonOut(result);
+ return playbook;
+ }
printPlaybook(run);
- return;
+ return playbook;
}
// Arg validation stays in the CLI.
@@ -118,8 +125,10 @@ export function registerBuild(program) {
} catch (e) {
const err =
/** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions, code: err.code});
- return;
+ return cliError(err.message, {
+ suggestions: err.suggestions,
+ code: err.code,
+ });
}
const {
@@ -134,20 +143,27 @@ export function registerBuild(program) {
foundation,
hint,
} = result.data;
- recordResultSummary([...pages, ...blocks, ...domain], {
+ // The kit spans domains, so its kind comes from the pieces themselves.
+ // `frame` and `foundation` are always-on and deliberately excluded: they
+ // are not what the query matched.
+ const answered = resultSetOf([...pages, ...blocks, ...domain], {
+ count: matchCount,
+ empty: !hasResults,
directMatch,
- resultCount: matchCount,
- emptyResult: !hasResults,
+ fallbackKind: options.type ?? 'mixed',
});
- if (json) return jsonOut(result);
+ if (json) {
+ jsonOut(result);
+ return answered;
+ }
if (!hasResults) {
emit(
text(`No matches for "${q}".`),
text(`Try a broader term, or browse: ${run} component --list`),
);
- return;
+ return answered;
}
// Same JSON->text projection as search, but leaner: the section header
@@ -259,6 +275,7 @@ export function registerBuild(program) {
}
emit(...out);
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/component/index.mjs b/packages/cli/clients/cli/commands/component/index.mjs
index 2bb6af84b6..cdfca5ef93 100644
--- a/packages/cli/clients/cli/commands/component/index.mjs
+++ b/packages/cli/clients/cli/commands/component/index.mjs
@@ -23,6 +23,7 @@ import {jsonOut} from '../../../../foundation/response/json.mjs';
import {emit, section, text, list, record, records, code} from '../../formatters/index.mjs';
import {cliError} from '../../lib/cli-error.mjs';
import {defineCommand} from '../../lib/define-command.mjs';
+import {resultSet} from '../../../../foundation/debug/index.mjs';
import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
import {component as componentApi} from '../../../../api/component/component.mjs';
import {findRelatedBlocks} from '../../../../api/template/template.mjs';
@@ -46,6 +47,42 @@ import {doc as componentFn} from '../../../../api/component/component.doc.mjs';
* )} ComponentResult
*/
+/**
+ * What the run answered with, read off the response the api returned.
+ *
+ * Naming a component resolves it or fails, so every detail view is a direct
+ * match of exactly one component. `--blocks` is the exception, twice over: it
+ * answers with the block templates that USE the component, so the set it
+ * reports is theirs — and a list of those has nothing to direct-match, since
+ * the thing that resolved (the component) is not the thing being counted.
+ *
+ * @param {ComponentResult} result
+ * @returns {import('../../../../foundation/debug/command-result.mjs').CommandResult}
+ */
+function summarize(result) {
+ switch (result.type) {
+ case 'component.list': {
+ const count = Object.values(result.data.components).reduce(
+ (total, items) => total + items.length,
+ 0,
+ );
+ return resultSet({count, resultKind: 'component'});
+ }
+ case 'component.detail':
+ case 'component.detail.props':
+ case 'component.detail.source':
+ case 'component.detail.showcase':
+ return resultSet({count: 1, resultKind: 'component', directMatch: true});
+ case 'component.detail.blocks': {
+ const {showcase, examples, related} = result.data;
+ return resultSet({
+ count: (showcase ? 1 : 0) + examples.length + related.length,
+ resultKind: 'template',
+ });
+ }
+ }
+}
+
/**
* @param {import('commander').Command} program
*/
@@ -67,8 +104,7 @@ export function registerComponent(program) {
const validDetails = ['full', 'compact', 'brief'];
if (!validDetails.includes(detail)) {
- cliError(`Invalid --detail value "${detail}". Valid levels: ${validDetails.join(', ')}`, {code: ERROR_CODES.ERR_INVALID_DETAIL});
- return;
+ return cliError(`Invalid --detail value "${detail}". Valid levels: ${validDetails.join(', ')}`, {code: ERROR_CODES.ERR_INVALID_DETAIL});
}
// Non-blocking nudge: if any configured integration has validation
@@ -98,11 +134,14 @@ export function registerComponent(program) {
}));
} catch (e) {
const err = /** @type {import('../../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions, code: err.code});
- return;
+ return cliError(err.message, {suggestions: err.suggestions, code: err.code});
}
- if (json) return jsonOut(result);
+ const answered = summarize(result);
+ if (json) {
+ jsonOut(result);
+ return answered;
+ }
// ── Text output ────────────────────────────────────────────
// The api layer already resolved against core (result exists), so core is
@@ -253,6 +292,7 @@ export function registerComponent(program) {
break;
}
}
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/debug-result-summary.test.mjs b/packages/cli/clients/cli/commands/debug-result-summary.test.mjs
index b2d2255ef4..5ffe768b09 100644
--- a/packages/cli/clients/cli/commands/debug-result-summary.test.mjs
+++ b/packages/cli/clients/cli/commands/debug-result-summary.test.mjs
@@ -1,10 +1,16 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file CLI coverage for the structured result summary on DebugEvent.
+ * @file What real command runs report as their result — end to end.
*
- * @input real search and build command responses
- * @output result counts, kinds, empty-state, and direct-match telemetry
+ * These drive the actual CLI and read the event that came out of it, so they
+ * cover the whole path: a command's returned descriptor, the converter that
+ * stamps it, and the recorder that seals it. The per-command contract itself is
+ * a typecheck (see lib/define-command.mjs); this is the proof the numbers that
+ * arrive are the right ones.
+ *
+ * @input real command runs against this repo
+ * @output the result counts, kinds, empty states, and direct matches recorded
* @position packages/cli/clients/cli/commands — debug result integration
*/
@@ -52,7 +58,9 @@ describe('DebugEvent result summary', () => {
expect(event.output).toMatchObject({
resultCount: 0,
emptyResult: true,
- resultKind: null,
+ // An open search really did span every domain, and saying so beats a
+ // null that cannot be told apart from a command that never reported.
+ resultKind: 'mixed',
directMatch: null,
});
},
@@ -100,7 +108,7 @@ describe('DebugEvent result summary', () => {
const domains = new Set(results.map(result => result.domain));
const resultKind =
domains.size === 0
- ? null
+ ? 'mixed'
: domains.size === 1
? domains.values().next().value
: 'mixed';
@@ -127,11 +135,96 @@ describe('DebugEvent result summary', () => {
expect(run.stdout).toContain('Build kit for');
expect(event.output).toMatchObject({
emptyResult: false,
- resultKind: null,
+ // Every raw match was filtered out of the printed kit, so the kind
+ // falls back to what was asked for — `--type doc`.
+ resultKind: 'doc',
directMatch: false,
});
expect(event.output.resultCount).toBeGreaterThan(0);
},
SLOW,
);
+
+ it(
+ 'reports a lookup that resolved exactly one thing',
+ async () => {
+ const {event} = await runWithDebug(['docs', 'tokens']);
+ expect(event.outcome).toBe('ok');
+ expect(event.output).toMatchObject({
+ resultCount: 1,
+ emptyResult: false,
+ resultKind: 'doc',
+ directMatch: true,
+ });
+ },
+ SLOW,
+ );
+
+ it(
+ 'reports a list as the size of the list',
+ async () => {
+ const {run, event} = await runWithDebug(['--json', 'template', '--list']);
+ const response = JSON.parse(run.stdout);
+ expect(response.data.length).toBeGreaterThan(0);
+ expect(event.output).toMatchObject({
+ resultCount: response.data.length,
+ emptyResult: false,
+ resultKind: 'template',
+ directMatch: null,
+ });
+ },
+ SLOW,
+ );
+
+ it(
+ 'says so explicitly when a command has no result set',
+ async () => {
+ // `layout check` returns a verdict on one expression: nothing was looked
+ // up, and the run says that rather than leaving four ambiguous nulls.
+ const {event} = await runWithDebug(['layout', 'check', 'VStack>Text']);
+ expect(event.output).toMatchObject({
+ resultKind: 'none',
+ resultCount: null,
+ emptyResult: null,
+ directMatch: null,
+ });
+ },
+ SLOW,
+ );
+
+ it(
+ 'only claims a direct match when the filter resolved one component',
+ async () => {
+ // The trap: a filter is a substring search, so its mere presence proves
+ // nothing — `theme targets a` matches every target there is. Claiming a
+ // direct match there would make every fuzzy run a false positive in the
+ // one query these fields exist to answer.
+ const loose = await runWithDebug(['theme', 'targets', 'But']);
+ expect(loose.event.output).toMatchObject({
+ resultKind: 'theme',
+ directMatch: false,
+ });
+ expect(loose.event.output.resultCount).toBeGreaterThan(0);
+
+ const exact = await runWithDebug(['theme', 'targets', 'Button']);
+ expect(exact.event.output).toMatchObject({
+ resultKind: 'theme',
+ directMatch: true,
+ });
+
+ const unfiltered = await runWithDebug(['theme', 'targets']);
+ expect(unfiltered.event.output.directMatch).toBe(null);
+ },
+ SLOW,
+ );
+
+ it(
+ 'reports help as a run with no result set',
+ async () => {
+ const {event} = await runWithDebug(['--help']);
+ expect(event.output.helpDisplayed).toBe(true);
+ expect(event.output.resultKind).toBe('none');
+ },
+ SLOW,
+ );
});
diff --git a/packages/cli/clients/cli/commands/discover.mjs b/packages/cli/clients/cli/commands/discover.mjs
index 0df78ccf4f..b15797c53a 100644
--- a/packages/cli/clients/cli/commands/discover.mjs
+++ b/packages/cli/clients/cli/commands/discover.mjs
@@ -19,12 +19,47 @@ import {Project} from '../../../foundation/config/project.mjs';
import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
import {defineCommand} from '../lib/define-command.mjs';
+import {resultSet} from '../../../foundation/debug/index.mjs';
import {doc as discoverCommand} from './discover.doc.mjs';
import {doc as discoverFn} from '../../../api/discover/discover.doc.mjs';
// Max components to list inline per package before summarizing with "+N more".
const MAX_COMPONENTS_SHOWN = 10;
+/**
+ * What the run answered with. `discover` browses the integration packages a
+ * project has configured, so the top two views count PACKAGES; naming a
+ * component inside one answers with that component instead.
+ *
+ * @param {import('../../../api/discover/discover.type.mjs').DiscoverListResponse
+ * | import('../../../api/discover/discover.type.mjs').DiscoverDetailResponse
+ * | import('../../../api/discover/discover.type.mjs').DiscoverDetailDocResponse
+ * | import('../../../api/discover/discover.type.mjs').DiscoverSearchResponse} result
+ * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
+ */
+function summarize(result) {
+ switch (result.type) {
+ case 'discover.list':
+ return resultSet({
+ count: result.data.length,
+ resultKind: 'integration',
+ });
+ case 'discover.detail':
+ return resultSet({
+ count: 1,
+ resultKind: 'integration',
+ directMatch: true,
+ });
+ case 'discover.detail.doc':
+ return resultSet({count: 1, resultKind: 'component', directMatch: true});
+ case 'discover.search':
+ return resultSet({
+ count: result.data.matches.length,
+ resultKind: 'component',
+ });
+ }
+}
+
/**
* @param {import('commander').Command} program
*/
@@ -58,15 +93,16 @@ export function registerDiscover(program) {
result = await discoverApi(query, {components: options.components, lang, zh});
} catch (e) {
const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions, code: err.code});
- return;
+ return cliError(err.message, {suggestions: err.suggestions, code: err.code});
}
+ const answered = summarize(result);
if (json) {
// Forward optional meta (e.g. configured flag for discover.list) as a
// sibling of data via jsonOut, so the envelope still carries
// apiVersion and goes through the single sanctioned emit path.
- return jsonOut(result);
+ jsonOut(result);
+ return answered;
}
switch (result.type) {
@@ -146,6 +182,7 @@ export function registerDiscover(program) {
break;
}
}
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/docs.mjs b/packages/cli/clients/cli/commands/docs.mjs
index 488ce8b66a..3cfdc4c23c 100644
--- a/packages/cli/clients/cli/commands/docs.mjs
+++ b/packages/cli/clients/cli/commands/docs.mjs
@@ -17,6 +17,7 @@ import {jsonOut} from '../../../foundation/response/json.mjs';
import {emit, section, records, text, code} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {defineCommand} from '../lib/define-command.mjs';
+import {resultSet} from '../../../foundation/debug/index.mjs';
import {docs as docsApi} from '../../../api/docs/docs.mjs';
import {doc as docsCommand} from './docs.doc.mjs';
import {doc as docsFn} from '../../../api/docs/docs.doc.mjs';
@@ -130,6 +131,22 @@ function formatReferenceFull(docs, detail) {
return `${header}\n\n${sections.join(sep)}`;
}
+/**
+ * What the run answered with. A named topic (or one of its sections) resolves
+ * or throws, so it is always a direct match of one doc; the bare form lists
+ * every topic there is.
+ *
+ * @param {import('../../../api/docs/docs.type.mjs').DocsListResponse
+ * | import('../../../api/docs/docs.type.mjs').DocsDetailResponse
+ * | import('../../../api/docs/docs.type.mjs').DocsDetailSectionResponse} result
+ * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
+ */
+function summarize(result) {
+ return result.type === 'docs.list'
+ ? resultSet({count: result.data.length, resultKind: 'doc'})
+ : resultSet({count: 1, resultKind: 'doc', directMatch: true});
+}
+
// ─── Command ─────────────────────────────────────────────────────────────────
/**
@@ -153,11 +170,17 @@ export function registerDocs(program) {
// docs API throws structured errors with {name, reason} suggestions —
// pass them through untouched so the CLI envelope matches the API.
const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
- return;
+ return cliError(err.message, {
+ suggestions: err.suggestions || [],
+ code: err.code,
+ });
}
- if (json) return jsonOut(result);
+ const answered = summarize(result);
+ if (json) {
+ jsonOut(result);
+ return answered;
+ }
switch (result.type) {
case 'docs.list': {
@@ -186,6 +209,7 @@ export function registerDocs(program) {
break;
}
}
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/doctor.mjs b/packages/cli/clients/cli/commands/doctor.mjs
index 2d444ce61b..58aa839812 100644
--- a/packages/cli/clients/cli/commands/doctor.mjs
+++ b/packages/cli/clients/cli/commands/doctor.mjs
@@ -16,6 +16,7 @@ import {emit, section, records, text} from '../formatters/index.mjs';
import {defineCommand} from '../lib/define-command.mjs';
import {doc as doctorCommand} from './doctor.doc.mjs';
import {doc as doctorFn} from '../../../api/doctor/doctor.doc.mjs';
+import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
/** Status -> ASCII token (plain, matching the rest of the CLI). */
const STATUS = {
@@ -83,6 +84,11 @@ export function registerDoctor(program) {
if (hasFailure) {
process.exitCode = 1;
}
+
+ // A diagnosis, not a lookup. The checks are a verdict on the project —
+ // counting them would say "doctor found 14 things", which is not what
+ // anyone means by a result. Read the summary counts from the report.
+ return NO_RESULT_SET;
},
}).addHelpText(
'after',
diff --git a/packages/cli/clients/cli/commands/hook/index.mjs b/packages/cli/clients/cli/commands/hook/index.mjs
index a9c82ce0f1..0a951c59ac 100644
--- a/packages/cli/clients/cli/commands/hook/index.mjs
+++ b/packages/cli/clients/cli/commands/hook/index.mjs
@@ -17,6 +17,7 @@ import {jsonOut} from '../../../../foundation/response/json.mjs';
import {emit, section, text, list, records, code} from '../../formatters/index.mjs';
import {cliError} from '../../lib/cli-error.mjs';
import {defineCommand} from '../../lib/define-command.mjs';
+import {resultSet} from '../../../../foundation/debug/index.mjs';
import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
import {hook as hookApi} from '../../../../api/hook/hook.mjs';
import {findRelatedBlocks} from '../../../../api/template/template.mjs';
@@ -35,6 +36,24 @@ import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
* )} HookResult
*/
+/**
+ * What the run answered with. The list view groups hooks by category, so the
+ * count is every hook across the groups — names or docs, depending on detail.
+ *
+ * @param {HookResult} result
+ * @returns {import('../../../../foundation/debug/command-result.mjs').CommandResult}
+ */
+function summarize(result) {
+ if (result.type === 'hook.list') {
+ const count = Object.values(result.data.components).reduce(
+ (total, items) => total + items.length,
+ 0,
+ );
+ return resultSet({count, resultKind: 'hook'});
+ }
+ return resultSet({count: 1, resultKind: 'hook', directMatch: true});
+}
+
/** @param {import('commander').Command} program */
export function registerHook(program) {
defineCommand(program, hookCommand, {
@@ -57,8 +76,7 @@ export function registerHook(program) {
const validDetails = ['full', 'compact', 'brief'];
if (!validDetails.includes(detail)) {
- cliError(`Invalid --detail value "${detail}". Valid levels: ${validDetails.join(', ')}`, {code: ERROR_CODES.ERR_INVALID_DETAIL});
- return;
+ return cliError(`Invalid --detail value "${detail}". Valid levels: ${validDetails.join(', ')}`, {code: ERROR_CODES.ERR_INVALID_DETAIL});
}
/** @type {HookResult} */
@@ -74,11 +92,14 @@ export function registerHook(program) {
}));
} catch (e) {
const err = /** @type {import('../../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions, code: err.code});
- return;
+ return cliError(err.message, {suggestions: err.suggestions, code: err.code});
}
- if (json) return jsonOut(result);
+ const answered = summarize(result);
+ if (json) {
+ jsonOut(result);
+ return answered;
+ }
// ── Text output ────────────────────────────────────────────
switch (result.type) {
@@ -175,6 +196,7 @@ export function registerHook(program) {
break;
}
}
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/init.mjs b/packages/cli/clients/cli/commands/init.mjs
index 6cc92d4693..b6c5f18034 100644
--- a/packages/cli/clients/cli/commands/init.mjs
+++ b/packages/cli/clients/cli/commands/init.mjs
@@ -19,6 +19,7 @@ import {logger} from '../../../api/logger.mjs';
import {jsonOut} from '../../../foundation/response/json.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {defineCommand} from '../lib/define-command.mjs';
+import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
import {doc as initCommand} from './init.doc.mjs';
import {doc as initFn} from '../../../api/init/init.doc.mjs';
@@ -45,8 +46,11 @@ export function registerInit(program) {
if (json) jsonOut(receipt);
} catch (err) {
const e = /** @type {import('../../../api/error.mjs').AstryxError} */ (err);
- cliError(e.message, {suggestions: e.suggestions, code: e.code});
+ return cliError(e.message, {suggestions: e.suggestions, code: e.code});
}
+ // Setup writes files; there is nothing to look up. The receipt says what
+ // landed.
+ return NO_RESULT_SET;
},
});
}
diff --git a/packages/cli/clients/cli/commands/layout.mjs b/packages/cli/clients/cli/commands/layout.mjs
index 83ab6638fd..777d689f4b 100644
--- a/packages/cli/clients/cli/commands/layout.mjs
+++ b/packages/cli/clients/cli/commands/layout.mjs
@@ -31,6 +31,7 @@ import {doc as layoutGrammarCommand} from './layout-grammar.doc.mjs';
import {doc as layoutExpandFn} from '../../../api/layout/layoutExpand.doc.mjs';
import {doc as layoutCheckFn} from '../../../api/layout/layoutCheck.doc.mjs';
import {doc as layoutGrammarFn} from '../../../api/layout/layoutGrammar.doc.mjs';
+import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
/**
* The api layer's @returns for these functions widen the `type` discriminator
@@ -119,11 +120,10 @@ export function registerLayout(program) {
const json = program.opts().json || false;
const source = await readExpression(expression, options);
if (!source || source.trim() === '') {
- cliError(
+ return cliError(
'No layout expression given — pass it as an argument, via --file, or on stdin',
{code: ERROR_CODES.ERR_MISSING_ARGUMENT},
);
- return;
}
/** @type {LayoutExpandResponse} */
let result;
@@ -137,10 +137,14 @@ export function registerLayout(program) {
}));
} catch (e) {
const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
- return;
+ return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+ }
+ // Expanding turns an expression into TSX — a transformation, not a
+ // lookup. What it produced is in the output; there is no set to count.
+ if (json) {
+ jsonOut(result);
+ return NO_RESULT_SET;
}
- if (json) return jsonOut(result);
/** @type {import('../formatters/index.mjs').Block[]} */
const out = [];
@@ -166,6 +170,7 @@ export function registerLayout(program) {
out.push(code(result.data.code));
}
emit(...out);
+ return NO_RESULT_SET;
},
});
@@ -175,11 +180,10 @@ export function registerLayout(program) {
const json = program.opts().json || false;
const source = await readExpression(expression, options);
if (!source || source.trim() === '') {
- cliError(
+ return cliError(
'No layout expression given — pass it as an argument, via --file, or on stdin',
{code: ERROR_CODES.ERR_MISSING_ARGUMENT},
);
- return;
}
/** @type {LayoutCheckResponse} */
let result;
@@ -191,8 +195,7 @@ export function registerLayout(program) {
}));
} catch (e) {
const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
- return;
+ return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
}
// Exit code is the contract and must NOT depend on --json vs human: an
// invalid (but parseable) layout exits 1 in BOTH modes so `layout check`
@@ -200,7 +203,12 @@ export function registerLayout(program) {
// before the JSON return (parity with doctor / validate-integration).
if (!result.data.valid) process.exitCode = 1;
- if (json) return jsonOut(result);
+ // A verdict on one expression: valid or not, with the errors that made
+ // it so. Nothing was looked up.
+ if (json) {
+ jsonOut(result);
+ return NO_RESULT_SET;
+ }
const {valid, form, errors, warnings, compact, outline} = result.data;
if (!valid) {
@@ -214,7 +222,7 @@ export function registerLayout(program) {
text(`[fail] Invalid (${errors.length} error${errors.length === 1 ? '' : 's'}):`),
list(items),
);
- return;
+ return NO_RESULT_SET;
}
/** @type {import('../formatters/index.mjs').Block[]} */
@@ -225,6 +233,7 @@ export function registerLayout(program) {
// The canonical compact/outline surfaces are preformatted — emit verbatim.
out.push(section('compact'), code(compact), section('outline'), code(outline));
emit(...out);
+ return NO_RESULT_SET;
},
});
@@ -238,12 +247,17 @@ export function registerLayout(program) {
result = /** @type {LayoutGrammarResponse} */ (await layoutGrammar({cwd: process.cwd()}));
} catch (e) {
const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
- return;
+ return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+ }
+ // One document, the same one every time: the grammar cheatsheet.
+ const answered = resultSet({count: 1, resultKind: 'doc'});
+ if (json) {
+ jsonOut(result);
+ return answered;
}
- if (json) return jsonOut(result);
// The cheatsheet is a preformatted document — emit verbatim.
emit(code(result.data.text));
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/search.mjs b/packages/cli/clients/cli/commands/search.mjs
index eab0c2c738..2eef0e586e 100644
--- a/packages/cli/clients/cli/commands/search.mjs
+++ b/packages/cli/clients/cli/commands/search.mjs
@@ -25,7 +25,7 @@ import {
formatCliCommand,
} from '../../../foundation/env/package-manager.mjs';
import {jsonOut} from '../../../foundation/response/json.mjs';
-import {recordResultSummary} from '../../../foundation/debug/index.mjs';
+import {resultSetOf} from '../../../foundation/debug/index.mjs';
import {emit, section, text, records} from '../formatters/index.mjs';
import {cliError} from '../lib/cli-error.mjs';
import {defineCommand} from '../lib/define-command.mjs';
@@ -74,19 +74,28 @@ export function registerSearch(program) {
} catch (e) {
const err =
/** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions, code: err.code});
- return;
+ return cliError(err.message, {
+ suggestions: err.suggestions,
+ code: err.code,
+ });
}
- // The recorded count is the number of MATCHES, not the number that
- // survived `--limit`. Recording `results.length` would file the cap as
+ // The reported count is the number of MATCHES, not the number that
+ // survived `--limit`. Reporting `results.length` would file the cap as
// the answer, so "20 matches" and "200 matches, showing 20" would be the
// same row in every usage query. The delivered payload stays bounded.
- recordResultSummary(result.data.results, {
- resultCount: result.data.matchCount,
- emptyResult: result.data.matchCount === 0,
+ const answered = resultSetOf(result.data.results, {
+ count: result.data.matchCount,
+ empty: result.data.matchCount === 0,
+ // Nothing matched, so the results cannot say what was searched for —
+ // the `--type` filter can, and an open search really did span them all.
+ fallbackKind: options.type ?? 'mixed',
});
- if (json) return jsonOut(result);
+
+ if (json) {
+ jsonOut(result);
+ return answered;
+ }
// ── Text output ──────────────────────────────────────────────
const run = getCliInvocation();
@@ -98,7 +107,7 @@ export function registerSearch(program) {
text(`No results for "${q}".`),
text(`Try a broader term, or browse: ${run} component --list`),
);
- return;
+ return answered;
}
// The text view is just a projection of the JSON: one record per result,
@@ -128,6 +137,7 @@ export function registerSearch(program) {
),
records(results, {fields, format: {command: formatCliCommand}}),
);
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/swizzle.mjs b/packages/cli/clients/cli/commands/swizzle.mjs
index bfcfa52d9f..b4ba0bc519 100644
--- a/packages/cli/clients/cli/commands/swizzle.mjs
+++ b/packages/cli/clients/cli/commands/swizzle.mjs
@@ -18,6 +18,7 @@ import {swizzle as swizzleApi} from '../../../api/swizzle/swizzle.mjs';
import {defineCommand} from '../lib/define-command.mjs';
import {doc as swizzleCommand} from './swizzle.doc.mjs';
import {doc as swizzleFn} from '../../../api/swizzle/swizzle.doc.mjs';
+import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
/**
* @param {import('commander').Command} program
@@ -41,11 +42,20 @@ export function registerSwizzle(program) {
});
} catch (e) {
const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions, code: err.code});
- return;
+ return cliError(err.message, {suggestions: err.suggestions, code: err.code});
}
- if (json) return jsonOut(result);
+ // `--list` answers with the components you could eject; ejecting one is
+ // a copy into the project, which is an effect with nothing to count.
+ const answered =
+ result.type === 'swizzle.list'
+ ? resultSet({count: result.data.length, resultKind: 'component'})
+ : NO_RESULT_SET;
+
+ if (json) {
+ jsonOut(result);
+ return answered;
+ }
if (result.type === 'swizzle.list') {
const components = result.data;
@@ -60,7 +70,7 @@ export function registerSwizzle(program) {
].join('\n'),
),
);
- return;
+ return answered;
}
const {package: ownerPackage, outputDir, filesCopied, usesStyleX, feedback} =
@@ -107,6 +117,7 @@ export function registerSwizzle(program) {
}
emit(...out);
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/template.mjs b/packages/cli/clients/cli/commands/template.mjs
index 8687ec4280..9b4eb4e7c1 100644
--- a/packages/cli/clients/cli/commands/template.mjs
+++ b/packages/cli/clients/cli/commands/template.mjs
@@ -15,6 +15,7 @@ import {Project} from '../../../foundation/config/project.mjs';
import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
import {defineCommand} from '../lib/define-command.mjs';
+import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
import {doc as templateCommand} from './template.doc.mjs';
import {doc as templateFn} from '../../../api/template/template.doc.mjs';
@@ -46,6 +47,27 @@ export {discoverTemplates, listTemplates} from '../../../api/template/template.m
* )} TemplateResponse
*/
+/**
+ * What the run answered with. Listing and printing a template are lookups;
+ * scaffolding one into a project (or writing the CDN starter) is a file
+ * written, which is an effect with nothing to count.
+ *
+ * @param {TemplateResponse} result
+ * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
+ */
+function summarize(result) {
+ switch (result.type) {
+ case 'template.list':
+ return resultSet({count: result.data.length, resultKind: 'template'});
+ case 'template.show':
+ case 'template.skeleton':
+ return resultSet({count: 1, resultKind: 'template', directMatch: true});
+ case 'template.copy':
+ case 'template.cdn':
+ return NO_RESULT_SET;
+ }
+}
+
/**
* @param {import('commander').Command} program
*/
@@ -93,8 +115,7 @@ export function registerTemplate(program) {
const msg =
`Refusing to overwrite existing file ${rel}. ` +
`Re-run with --overwrite (or -f) to replace it.`;
- cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
- return;
+ return cliError(msg, {code: ERROR_CODES.ERR_FILE_EXISTS});
}
}
@@ -117,11 +138,14 @@ export function registerTemplate(program) {
// template API throws structured errors with {name, reason} suggestions —
// pass them through untouched so the CLI envelope matches the API.
const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
- cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
- return;
+ return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
}
- if (json) return jsonOut(result);
+ const answered = summarize(result);
+ if (json) {
+ jsonOut(result);
+ return answered;
+ }
switch (result.type) {
case 'template.list': {
@@ -201,6 +225,7 @@ export function registerTemplate(program) {
break;
}
}
+ return answered;
},
});
}
diff --git a/packages/cli/clients/cli/commands/upgrade.mjs b/packages/cli/clients/cli/commands/upgrade.mjs
index 63004330e2..782af1b224 100644
--- a/packages/cli/clients/cli/commands/upgrade.mjs
+++ b/packages/cli/clients/cli/commands/upgrade.mjs
@@ -19,6 +19,7 @@ import {defineCommand} from '../lib/define-command.mjs';
import {upgrade as upgradeApi} from '../../../api/upgrade/upgrade.mjs';
import {doc as upgradeCommand} from './upgrade.doc.mjs';
import {doc as upgradeFn} from '../../../api/upgrade/upgrade.doc.mjs';
+import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
/**
* @param {import('commander').Command} program
@@ -47,12 +48,19 @@ export function registerUpgrade(program) {
if (e instanceof AstryxError) {
if (json) jsonError(e.message, undefined, e.code);
else process.exitCode = 1;
- return;
+ return NO_RESULT_SET;
}
throw e;
}
if (json) jsonOut(result);
+
+ // `--list` is the one lookup here: which migrations exist for the
+ // range. Everything else migrates the project — an effect, reported by
+ // the receipt rather than counted.
+ return result.type === 'upgrade.list'
+ ? resultSet({count: result.data.length, resultKind: 'migration'})
+ : NO_RESULT_SET;
},
});
diff --git a/packages/cli/clients/cli/commands/validate-integration.mjs b/packages/cli/clients/cli/commands/validate-integration.mjs
index af2cde7320..0e9aab5bf6 100644
--- a/packages/cli/clients/cli/commands/validate-integration.mjs
+++ b/packages/cli/clients/cli/commands/validate-integration.mjs
@@ -23,6 +23,7 @@ import {
} from '../../../api/integration/validate-integration.mjs';
import {doc as validateIntegrationCommand} from './validate-integration.doc.mjs';
import {doc as validateIntegrationFn} from '../../../api/integration/validateIntegration.doc.mjs';
+import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
/**
* Render a validation result for humans.
@@ -81,6 +82,11 @@ export function registerValidateIntegration(program) {
if (errors > 0) {
process.exitCode = 1;
}
+
+ // A verdict on one integration, like doctor: issues are findings, not
+ // results, and an empty list is the GOOD outcome rather than an empty
+ // answer.
+ return NO_RESULT_SET;
},
}).addHelpText(
'after',
diff --git a/packages/cli/clients/cli/index.mjs b/packages/cli/clients/cli/index.mjs
index 3f5f3b1316..c9e18e93fd 100644
--- a/packages/cli/clients/cli/index.mjs
+++ b/packages/cli/clients/cli/index.mjs
@@ -25,6 +25,7 @@ import {emit, section, text, records} from './formatters/index.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
import {installJsonShim} from './lib/json-shim.mjs';
+import {markReportsResult} from './lib/define-command.mjs';
import {isAstryxInitialized} from '../../foundation/agent-docs/agent-docs.mjs';
import * as debug from '../../foundation/debug/index.mjs';
@@ -39,17 +40,29 @@ const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package
// probe is deferred to delivery. See foundation/debug.
debug.begin({cliVersion: pkg.version});
-// Intercept `xds --version --json` (or `-V --json`) before Commander processes
-// the version flag and exits. Commander's built-in version handler prints the
-// raw version string and calls process.exit, bypassing our hooks — so the
-// only correct place to JSON-ify it is here. (Bin-time only: guarded on argv,
-// so importing this module in tests is a no-op.)
-const _argv = process.argv.slice(2);
-if (
- (_argv.includes('--version') || _argv.includes('-V')) &&
- _argv.includes('--json')
-) {
+/**
+ * Intercept `astryx --version --json` (or `-V --json`) before Commander
+ * processes the version flag and exits. Commander's built-in version handler
+ * prints the raw version string and calls process.exit, bypassing our hooks —
+ * so the only correct place to JSON-ify it is ahead of the parse.
+ *
+ * The bin calls this AFTER the project's debug handler is loaded, not at import
+ * time: this path exits the process itself, so running it any earlier meant the
+ * one invocation that took it was the only invocation nothing was ever recorded
+ * for. Guarded on argv, so it is a no-op for every other run and for tests that
+ * import this module.
+ *
+ * @param {string[]} [argv] arguments after the binary.
+ * @returns {void}
+ */
+export function handleVersionJsonPreflight(argv = process.argv.slice(2)) {
+ if (!(argv.includes('--version') || argv.includes('-V'))) return;
+ if (!argv.includes('--json')) return;
process.__xdsJsonHandled = true;
+ // Printing the version is not a lookup — the same answer every time — so it
+ // reports the same shape Commander's own `--version` path does.
+ debug.recordCommandResult(debug.NO_RESULT_SET);
+ debug.setOutcome('ok', {exitCode: 0});
console.log(JSON.stringify({apiVersion: API_VERSION, type: 'version', data: {version: pkg.version}}, null, 2));
process.exit(0);
}
@@ -366,6 +379,11 @@ export async function createProgram() {
}
// `xds` (no subcommand) — print help, or emit a JSON envelope when --json.
+ // Either way the run reports what it answered with, as every command
+ // does: the manifest is a list of commands, help is an effect. The rest
+ // of the CLI gets there through its action's return type — see
+ // lib/define-command.mjs; the four commands registered by hand in this
+ // file are the exceptions that report for themselves.
if (program.opts().json) {
// Emit the full capability manifest so an agent can drive the entire
// CLI from one call — no need to scrape `--help` text. We derive this
@@ -396,10 +414,18 @@ export async function createProgram() {
manifest,
},
}, null, 2));
+ debug.recordCommandResult(
+ debug.resultSet({
+ count: manifest.commands.length,
+ resultKind: 'command',
+ }),
+ );
return;
}
+ debug.recordCommandResult(debug.NO_RESULT_SET);
program.help();
});
+ markReportsResult(program);
/**
* Pre-action hook: gate --json BEFORE any command body runs.
@@ -528,14 +554,18 @@ export async function createProgram() {
mod[cmd.register](program);
} catch (e) {
// Command fails to load but CLI still works
- program
+ const stub = program
.command(cmd.name)
.description(`(failed to load: ${/** @type {any} */ (e).message})`)
.action(() => {
+ // Nothing loaded, so nothing was answered — say that rather than
+ // leaving the run's result unreported.
+ debug.recordCommandResult(debug.NO_RESULT_SET);
console.error(`Command "${cmd.name}" failed to load:`);
console.error(/** @type {any} */ (e).message);
process.exit(1);
});
+ markReportsResult(stub);
}
}
@@ -546,7 +576,7 @@ export async function createProgram() {
// Intentionally CLI-special — no `api/manifest`. It introspects the live
// Commander `program`, so extracting it to `api/` would create the `api → cli`
// cycle from #4302. `buildManifest(program)` lives in lib/; see its header.
- program
+ const manifestCommand = program
.command('manifest')
.description('Print the full CLI capability manifest (use with --json)')
.action(() => {
@@ -554,6 +584,13 @@ export async function createProgram() {
jsonSupported: JSON_SUPPORTED,
version: pkg.version,
});
+ // The manifest IS a result set: one entry per command the CLI ships.
+ debug.recordCommandResult(
+ debug.resultSet({
+ count: manifest.commands.length,
+ resultKind: 'command',
+ }),
+ );
if (program.opts().json) {
process.__xdsJsonHandled = true;
console.log(JSON.stringify({apiVersion: API_VERSION, type: 'manifest', data: manifest}, null, 2));
@@ -575,11 +612,14 @@ export async function createProgram() {
text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
);
});
+ markReportsResult(manifestCommand);
// Hidden command used by package.json postinstall scripts
- program
+ const postinstallCommand = program
.command('postinstall', {hidden: true})
.action(() => {
+ // Prints the welcome box. Nothing is looked up.
+ debug.recordCommandResult(debug.NO_RESULT_SET);
const r = getCliInvocation();
const pad = (/** @type {string} */ s, /** @type {number} */ len) => s + ' '.repeat(Math.max(0, len - s.length));
const W = 49; // inner width of the box
@@ -604,6 +644,7 @@ ${line('')}
╰${'─'.repeat(W + 2)}╯
`);
});
+ markReportsResult(postinstallCommand);
// Install the JSON shim AFTER all commands are registered so we can
// patch outputHelp on every command (root + subcommands). The shim
diff --git a/packages/cli/clients/cli/lib/define-command.mjs b/packages/cli/clients/cli/lib/define-command.mjs
index 83f5bb1e79..38394dfe7a 100644
--- a/packages/cli/clients/cli/lib/define-command.mjs
+++ b/packages/cli/clients/cli/lib/define-command.mjs
@@ -11,17 +11,83 @@
* generic — each command still supplies its own action (the thin wrapper that
* calls the api function and renders).
*
- * @input a CommandDoc (+ optional FunctionDoc) + an action
+ * It is also where a run's RESULT is recorded. Every command that ships passes
+ * through here, so an action returns a {@link CommandResult} and this converter
+ * stamps it onto the run's debug event — one place, for all of them. That is
+ * deliberate: reporting used to be a call each command made on its way out, and
+ * a command that forgot simply reported nothing. Now the return type asks the
+ * question at authoring time and the converter answers it at runtime, so a new
+ * command is logged correctly without doing anything at all.
+ *
+ * @input a CommandDoc (+ optional FunctionDoc) + an action returning a result
* @output a configured commander Command added to the given parent
* @position packages/cli/clients/cli/lib — CLI command converter
*/
+import {recordCommandResult} from '../../../foundation/debug/index.mjs';
+
+/**
+ * Marks a Commander command that reports what it answered with, and says HOW:
+ * `converter` for the contract path below (the action's return type), `manual`
+ * for the few hand-registered commands that record for themselves.
+ *
+ * Read by the coverage test that walks the assembled program, so a command
+ * registered by hand — bypassing the contract — is caught in CI rather than
+ * discovered as a column of nulls months later. The two values are what let
+ * that test PIN the hand-registered set instead of trusting the mark.
+ */
+export const REPORTS_RESULT = Symbol.for('astryx.command.reportsResult');
+
+/**
+ * Does this command report what it answered with?
+ * @param {import('commander').Command} cmd
+ * @returns {boolean}
+ */
+export function reportsResult(cmd) {
+ return reportsResultVia(cmd) !== null;
+}
+
+/**
+ * How this command reports, or null if it does not.
+ * @param {import('commander').Command} cmd
+ * @returns {'converter' | 'manual' | null}
+ */
+export function reportsResultVia(cmd) {
+ const via = /** @type {any} */ (cmd)?.[REPORTS_RESULT];
+ return via === 'converter' || via === 'manual' ? via : null;
+}
+
+/**
+ * Mark a hand-registered command as reporting its result.
+ *
+ * For the handful of commands that cannot come from a CommandDoc — the root
+ * program, `manifest` (it introspects the live program, so it cannot be
+ * declared by one), `postinstall`, and the stub left behind when a command
+ * module fails to load. They call {@link recordCommandResult} themselves; this
+ * says so, and the coverage test pins the set of commands allowed to, so the
+ * mark cannot become a quiet way around the contract.
+ *
+ * @param {import('commander').Command} cmd
+ * @returns {import('commander').Command} the same command, for chaining.
+ */
+export function markReportsResult(cmd) {
+ Object.defineProperty(cmd, REPORTS_RESULT, {
+ value: 'manual',
+ configurable: true,
+ });
+ return cmd;
+}
+
/**
* Build a Commander command from a CommandDoc and attach it to `parent`.
*
* @param {import('commander').Command} parent - program or a group command.
* @param {import('@astryxdesign/cli/authoring').CommandDoc} doc
- * @param {{fn?: import('@astryxdesign/cli/authoring').FunctionDoc, action?: (...args: any[]) => unknown}} [impl]
+ * @param {{
+ * fn?: import('@astryxdesign/cli/authoring').FunctionDoc,
+ * action?: (...args: any[]) => import('../../../foundation/debug/command-result.mjs').CommandResult
+ * | Promise<import('../../../foundation/debug/command-result.mjs').CommandResult>,
+ * }} [impl]
* @returns {import('commander').Command} the created command.
*/
export function defineCommand(parent, doc, {fn, action} = {}) {
@@ -67,6 +133,19 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
// help carries no per-command examples epilog. Keeping both out preserves the
// exact `--help`/manifest surface as registrations migrate to this converter.
- if (action) cmd.action(/** @type {(...args: any[]) => void | Promise<void>} */ (action));
+ if (action) {
+ // The recording seam. An action's job ends at "here is what I answered
+ // with"; getting that onto the event is this converter's job, and doing it
+ // here means every command is covered by construction — including the ones
+ // written next month.
+ cmd.action(async (/** @type {any[]} */ ...args) => {
+ const result = await action(...args);
+ recordCommandResult(result);
+ });
+ Object.defineProperty(cmd, REPORTS_RESULT, {
+ value: 'converter',
+ configurable: true,
+ });
+ }
return cmd;
}
diff --git a/packages/cli/foundation/debug/command-result.mjs b/packages/cli/foundation/debug/command-result.mjs
new file mode 100644
index 0000000000..37acf762f0
--- /dev/null
+++ b/packages/cli/foundation/debug/command-result.mjs
@@ -0,0 +1,140 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file What a command answered with — the one shape every command returns.
+ *
+ * ## Why a return type and not a call
+ *
+ * Reporting a result used to be something a command opted INTO: it called
+ * `recordResultSummary(...)` on its way out, or it didn't, and nothing noticed
+ * the difference. Two commands did; the rest reported nothing, and a run log
+ * full of nulls cannot tell "this command has no results" from "this command
+ * forgot". A new command inherited the silence by default.
+ *
+ * So the descriptor is the command's RETURN VALUE. `defineCommand` types every
+ * action as returning a {@link CommandResult}, which makes the compiler ask the
+ * question: a new command does not typecheck until each of its exits says what
+ * it answered with. The converter records it centrally — one place stamps the
+ * run log — so no command has to remember anything at all.
+ *
+ * ## Why a union rather than optional fields
+ *
+ * `none` is a declaration, not an absence. `astryx theme build` has nothing to
+ * count, and writing that down is a visible choice a reviewer can question;
+ * leaving a field off is not. Only `results` carries a count, so a command
+ * cannot half-report — and a null `resultKind` on a completed run now means
+ * exactly one thing: nobody reported, which is a bug rather than a shrug.
+ *
+ * @input a command action's return value
+ * @output a result descriptor the recorder stamps onto the run's event
+ * @position packages/cli/foundation/debug — the command-to-recorder contract
+ */
+
+/**
+ * The kinds a result SET can carry — every {@link DebugResultKind} except
+ * `none`, which is the other branch of the union and never labels a set.
+ *
+ * @typedef {Exclude<import('../../authoring/debug/type').DebugResultKind, 'none'>} ResultSetKind
+ */
+
+/**
+ * A command that answered by looking something up.
+ *
+ * @typedef {object} CommandResultSet
+ * @property {'results'} kind
+ * @property {number} count How many results MATCHED, counted before `--limit`,
+ * score floors, or presentation grouping. Not the size of the slice that was
+ * printed: recording the cap would make "matched 20" and "matched 200, showed
+ * 20" the same row in every query anyone writes.
+ * @property {ResultSetKind} resultKind What the results are. Derive it from the
+ * results themselves (see {@link resultSetOf}) when a command spans domains.
+ * @property {boolean} [empty] Whether the underlying match set was empty.
+ * Defaults to `count === 0`; pass it only when the command's own notion of
+ * "found nothing" differs from a zero count.
+ * @property {boolean} [directMatch] Whether the command resolved the exact
+ * thing that was asked for, rather than listing or suggesting. Omit it for a
+ * command that defines no such notion — a bare list has nothing to match.
+ */
+
+/**
+ * A command whose work is an effect: it builds, writes, upgrades, validates, or
+ * diagnoses. There is no set to count, and saying so is the point.
+ *
+ * @typedef {object} CommandNoResultSet
+ * @property {'none'} kind
+ */
+
+/**
+ * What every command action returns.
+ * @typedef {CommandResultSet | CommandNoResultSet} CommandResult
+ */
+
+/**
+ * The declaration for a command that answers with an effect rather than a
+ * result set. Frozen and shared — it carries no per-run state.
+ *
+ * @type {CommandNoResultSet}
+ */
+export const NO_RESULT_SET = Object.freeze({kind: 'none'});
+
+/**
+ * Declare a result set.
+ *
+ * @param {object} summary
+ * @param {number} summary.count Matches before any limit — see {@link CommandResultSet}.
+ * @param {ResultSetKind} summary.resultKind
+ * @param {boolean} [summary.empty]
+ * @param {boolean} [summary.directMatch]
+ * @returns {CommandResultSet}
+ */
+export function resultSet({count, resultKind, empty, directMatch}) {
+ /** @type {CommandResultSet} */
+ const set = {kind: 'results', count, resultKind};
+ if (typeof empty === 'boolean') set.empty = empty;
+ if (typeof directMatch === 'boolean') set.directMatch = directMatch;
+ return set;
+}
+
+/** The result kinds a surfaced item may tag itself with, via its `domain`. */
+const ITEM_KINDS = new Set(['component', 'template', 'doc', 'hook']);
+
+/**
+ * Declare a result set whose kind comes from the results themselves — for the
+ * commands that answer across domains (`search`, `build`).
+ *
+ * The items are only trusted to name the kind when they ARE the whole match
+ * set. A bounded slice is not the answer: `search button --limit 1` surfaces
+ * one component out of 240 mixed matches, and reading the kind off that slice
+ * would file the same query under a different kind at every `--limit` — the
+ * same lie about a cap that `count` refuses to tell.
+ *
+ * So a partial or empty answer falls back to what the run was looking FOR: the
+ * `--type` filter when one was given, `mixed` when the search was open. "Asked
+ * for components, found none" is a fact worth keeping, and "asked across
+ * everything, showed the top 20" is honestly mixed.
+ *
+ * @param {ReadonlyArray<{domain?: unknown}>} items The surfaced results.
+ * @param {object} summary
+ * @param {number} summary.count The total matched, before any cap.
+ * @param {ResultSetKind} summary.fallbackKind What the run was looking for —
+ * used whenever the items cannot speak for the whole set.
+ * @param {boolean} [summary.empty]
+ * @param {boolean} [summary.directMatch]
+ * @returns {CommandResultSet}
+ */
+export function resultSetOf(items, {count, fallbackKind, empty, directMatch}) {
+ const surfaced = Array.isArray(items) ? items : [];
+ const kinds = new Set(
+ surfaced
+ .map(item => item?.domain)
+ .filter(kind => typeof kind === 'string' && ITEM_KINDS.has(kind)),
+ );
+ const whole = surfaced.length >= count;
+ const resultKind =
+ !whole || kinds.size === 0
+ ? fallbackKind
+ : kinds.size === 1
+ ? /** @type {ResultSetKind} */ (kinds.values().next().value)
+ : 'mixed';
+ return resultSet({count, resultKind, empty, directMatch});
+}
diff --git a/packages/cli/foundation/debug/telemetry-fields.test.mjs b/packages/cli/foundation/debug/debug-fields.test.mjs
similarity index 77%
rename from packages/cli/foundation/debug/telemetry-fields.test.mjs
rename to packages/cli/foundation/debug/debug-fields.test.mjs
index 83862548fc..ddd550fc74 100644
--- a/packages/cli/foundation/debug/telemetry-fields.test.mjs
+++ b/packages/cli/foundation/debug/debug-fields.test.mjs
@@ -3,7 +3,7 @@
/**
* @file Contract coverage for DebugEvent result and agent-session fields.
*
- * @position packages/cli/foundation/debug — telemetry contract coverage
+ * @position packages/cli/foundation/debug — recorded-event contract coverage
*/
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
@@ -11,10 +11,11 @@ import {createHash} from 'node:crypto';
import {
begin,
finish,
- recordResultSummary,
+ recordCommandResult,
resetRecorder,
setEventHandler,
} from './recorder.mjs';
+import {NO_RESULT_SET, resultSetOf} from './command-result.mjs';
import {captureEnv} from './event.mjs';
import {parseDebugEvent} from '../../authoring/debug/parse.mjs';
@@ -191,11 +192,14 @@ describe('DebugEvent additive fields', () => {
it('records count, empty, kind, and direct-match facts', () => {
const event = collectEvent(() => {
- recordResultSummary([{domain: 'template'}, {domain: 'component'}], {
- directMatch: true,
- resultCount: 9,
- emptyResult: false,
- });
+ recordCommandResult(
+ resultSetOf([{domain: 'template'}, {domain: 'component'}], {
+ count: 9,
+ empty: false,
+ directMatch: true,
+ fallbackKind: 'mixed',
+ }),
+ );
});
expect(event.output).toMatchObject({
resultCount: 9,
@@ -206,15 +210,53 @@ describe('DebugEvent additive fields', () => {
});
it('records a successful empty result set', () => {
- const event = collectEvent(() => recordResultSummary([]));
+ const event = collectEvent(() =>
+ recordCommandResult(
+ resultSetOf([], {count: 0, fallbackKind: 'component'}),
+ ),
+ );
expect(event.outcome).toBe('ok');
expect(event.output).toMatchObject({
resultCount: 0,
emptyResult: true,
- resultKind: null,
+ // Nothing matched, so the kind comes from what was looked FOR. A null
+ // here would be indistinguishable from a command that never reported.
+ resultKind: 'component',
+ directMatch: null,
+ });
+ });
+
+ it('records a command that declares it has no result set', () => {
+ const event = collectEvent(() => recordCommandResult(NO_RESULT_SET));
+ expect(event.output).toMatchObject({
+ resultKind: 'none',
+ resultCount: null,
+ emptyResult: null,
directMatch: null,
});
});
+
+ it('derives one kind, mixed, or the fallback from the results themselves', () => {
+ const of = (/** @type {any[]} */ items, /** @type {any} */ fallback) =>
+ resultSetOf(items, {count: items.length, fallbackKind: fallback})
+ .resultKind;
+ expect(of([{domain: 'component'}, {domain: 'component'}], 'mixed')).toBe(
+ 'component',
+ );
+ expect(of([{domain: 'component'}, {domain: 'doc'}], 'mixed')).toBe('mixed');
+ // Nothing to read a kind from — an empty answer, or items that tag
+ // themselves with something this scale does not carry.
+ expect(of([], 'component')).toBe('component');
+ expect(of([{domain: 'sandwich'}], 'mixed')).toBe('mixed');
+ });
+
+ it('leaves resultKind null when a run reports nothing at all', () => {
+ // The whole point of `none`: a run that reported NOTHING still looks
+ // different from one that declared it has nothing, and that difference is
+ // what makes a missed command visible instead of invisible.
+ const event = collectEvent(() => {});
+ expect(event.output.resultKind).toBe(null);
+ });
});
describe('environment attribution', () => {
diff --git a/packages/cli/foundation/debug/event.mjs b/packages/cli/foundation/debug/event.mjs
index caa1780ea6..a20419edcf 100644
--- a/packages/cli/foundation/debug/event.mjs
+++ b/packages/cli/foundation/debug/event.mjs
@@ -30,9 +30,16 @@ import {isCliOneOff, detectPackageManager} from '../env/package-manager.mjs';
* without a single compile error, which is exactly what the version exists to
* prevent.
*
+ * v3 made every command report its result, which changed what an ABSENT one
+ * means: `output.resultKind` is null only when the run never reached an
+ * answer, and a command with no result set now says `none`. The values did not
+ * move, but the null did — a consumer counting nulls as "commands with nothing
+ * to report" would silently start counting failures instead, and no widened
+ * union catches a branch on null.
+ *
* @type {import('../../authoring/debug/type').DebugSchemaVersion}
*/
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3;
/**
* The recorded shape is PUBLISHED — a project sets `debug` in `astryx.config`
diff --git a/packages/cli/foundation/debug/index.mjs b/packages/cli/foundation/debug/index.mjs
index cb5fc4f304..7c10f441e4 100644
--- a/packages/cli/foundation/debug/index.mjs
+++ b/packages/cli/foundation/debug/index.mjs
@@ -12,7 +12,7 @@
*
* begin() once, before Commander parses
* setCommand/setArgs/… as facts become known
- * recordResultSummary() when a command returns a result set
+ * recordCommandResult() what the command answered with, from its return
* setOutcome() from every terminal path (error, fatal, gate)
* finish() automatic, via the exit listener begin() installs
*
@@ -33,7 +33,7 @@ export {
setOptions,
setGlobalOptions,
setProject,
- recordResultSummary,
+ recordCommandResult,
setEventHandler,
setIntegrationEventHandlers,
noteConfigGateSkipped,
@@ -43,6 +43,12 @@ export {
resetRecorder,
} from './recorder.mjs';
+export {
+ NO_RESULT_SET,
+ resultSet,
+ resultSetOf,
+} from './command-result.mjs';
+
export {
SCHEMA_VERSION,
createEvent,
diff --git a/packages/cli/foundation/debug/privacy-contract.test.mjs b/packages/cli/foundation/debug/privacy-contract.test.mjs
index 5d2bf31c66..aed09e8a84 100644
--- a/packages/cli/foundation/debug/privacy-contract.test.mjs
+++ b/packages/cli/foundation/debug/privacy-contract.test.mjs
@@ -178,10 +178,10 @@ describe('`redacted` says what actually happened', () => {
});
describe('the schema version marks the change', () => {
- it('delivers v2 records that validate against the published schema', () => {
+ it('delivers v3 records that validate against the published schema', () => {
const event = collectEvent();
- expect(event.schemaVersion).toBe(2);
- expect(SCHEMA_VERSION).toBe(2);
+ expect(event.schemaVersion).toBe(3);
+ expect(SCHEMA_VERSION).toBe(3);
expect(() => parseDebugEvent(event)).not.toThrow();
});
});
diff --git a/packages/cli/foundation/debug/recorder.mjs b/packages/cli/foundation/debug/recorder.mjs
index d7923cd515..741b0a6e83 100644
--- a/packages/cli/foundation/debug/recorder.mjs
+++ b/packages/cli/foundation/debug/recorder.mjs
@@ -412,54 +412,75 @@ export function setProject(facts) {
});
}
-/** Values `resultKind` may carry — mirrors DebugResultKind. */
-const RESULT_KINDS = new Set(['component', 'template', 'doc', 'hook']);
+/**
+ * The kinds a result SET may carry — every {@link DebugResultKind} except
+ * `none`, which is the other branch of the union and never labels a set.
+ *
+ * A Record rather than a Set so the TYPE forces completeness: add a kind to the
+ * published union and this object stops compiling until it is listed here too.
+ * The vocabulary necessarily exists twice at runtime — here, and as the sealed
+ * parser's schema in authoring/debug/parse.mjs — and neither copy can be
+ * half-extended: that one is pinned to the same union by the drift-lock beside
+ * it. Without this, adding a kind everywhere it looks obvious would leave this
+ * guard silently nulling it, which is the exact failure this whole change is
+ * about.
+ *
+ * @type {Record<Exclude<import('../../authoring/debug/type').DebugResultKind, 'none'>, true>}
+ */
+const RESULT_SET_KINDS = {
+ component: true,
+ hook: true,
+ doc: true,
+ template: true,
+ theme: true,
+ integration: true,
+ migration: true,
+ command: true,
+ mixed: true,
+};
/**
- * Record a stable summary of a command's result set and presentation.
+ * Stamp what the command answered with.
*
- * `results` is only read for `resultKind`, so passing the bounded, surfaced
- * slice is correct. `resultCount` is NOT that slice's length: pass the total
- * the command matched before its limit and score floors, because a count that
- * silently reports the cap makes "matched exactly 20" and "matched 200, showed
- * 20" the same row. It falls back to `results.length` only for a command whose
- * surfaced set IS the whole match set.
+ * The ONE place these fields are written. A command declares its result as its
+ * return value — see foundation/debug/command-result.mjs — and the CommandDoc
+ * converter hands it here; nothing else reports, so nothing else can drift or
+ * forget. An unrecognized descriptor is ignored rather than half-recorded: a
+ * partial row is worse than an obviously missing one.
*
- * @param {Array<{domain?: unknown}>} results Surfaced results used for kind.
- * @param {{directMatch?: boolean, resultCount?: number, emptyResult?: boolean}} [options]
+ * @param {import('./command-result.mjs').CommandResult} result
*/
-export function recordResultSummary(
- results,
- {directMatch, resultCount, emptyResult} = {},
-) {
+export function recordCommandResult(result) {
guard(() => {
- if (!_event || !Array.isArray(results)) return;
+ if (!_event || !result || typeof result !== 'object') return;
- const kinds = new Set(
- results
- .map(result => result?.domain)
- .filter(kind => typeof kind === 'string' && RESULT_KINDS.has(kind)),
- );
- const count =
- typeof resultCount === 'number' &&
- Number.isInteger(resultCount) &&
- resultCount >= 0
- ? resultCount
- : results.length;
+ // An effect, not a lookup. `none` is the whole record: leaving the counts
+ // null is deliberate, and the kind is what says so.
+ if (result.kind === 'none') {
+ _event.output.resultKind = 'none';
+ return;
+ }
+ if (result.kind !== 'results') return;
+
+ // A count that is not a count records NOTHING. Falling back to 0 would
+ // publish "this run found nothing" — a confident, wrong answer — where the
+ // truth is that the descriptor was malformed.
+ const count = result.count;
+ if (!Number.isInteger(count) || count < 0) return;
_event.output.resultCount = count;
_event.output.emptyResult =
- typeof emptyResult === 'boolean' ? emptyResult : count === 0;
- _event.output.resultKind =
- kinds.size === 0
- ? null
- : kinds.size === 1
- ? /** @type {import('../../authoring/debug/type').DebugResultKind} */ (
- kinds.values().next().value
- )
- : 'mixed';
- if (typeof directMatch === 'boolean') {
- _event.output.directMatch = directMatch;
+ typeof result.empty === 'boolean' ? result.empty : count === 0;
+ _event.output.resultKind = Object.hasOwn(
+ RESULT_SET_KINDS,
+ result.resultKind,
+ )
+ ? /** @type {import('../../authoring/debug/type').DebugResultKind} */ (
+ result.resultKind
+ )
+ : null;
+ if (typeof result.directMatch === 'boolean') {
+ _event.output.directMatch = result.directMatch;
}
});
}
@@ -478,7 +499,13 @@ export function recordEnvelope(type) {
/** Note that the run ended by printing help rather than doing work. */
export function recordHelp() {
guard(() => {
- if (_event) _event.output.helpDisplayed = true;
+ if (!_event) return;
+ _event.output.helpDisplayed = true;
+ // Printing help is not a lookup, so it has no result set — and saying so
+ // keeps a null `resultKind` meaning the one thing it should: nobody
+ // reported. Only if the command has not already answered: help can follow
+ // real output, and that answer is the better record of the two.
+ if (_event.output.resultKind === null) _event.output.resultKind = 'none';
});
}