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.mdnew file mode 100644index 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.+@josephfarinadiff --git a/packages/cli/authoring/debug/parse.mjs b/packages/cli/authoring/debug/parse.mjsindex 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.mjsindex 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.tsindex 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 actuallydiff --git a/packages/cli/clients/cli/bin/astryx.mjs b/packages/cli/clients/cli/bin/astryx.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjimport {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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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 shimdiff --git a/packages/cli/clients/cli/lib/define-command.mjs b/packages/cli/clients/cli/lib/define-command.mjsindex 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.mjsnew file mode 100644index 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.mjssimilarity index 77%rename from packages/cli/foundation/debug/telemetry-fields.test.mjsrename to packages/cli/foundation/debug/debug-fields.test.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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';});}