@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/clients/cli/commands/integration-pack.doc.mjs

@@ -8,7 +8,7 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Deprecated: the old name of `integration verify`',
   description:
-    '`astryx integration pack --check` is the name this check had before {@link command:integration verify}. It still runs the same check, with the same output, JSON, and exit codes, and prints a note that names `integration verify`. It will be removed in a later release.',
+    '`astryx integration pack --check` is the name this check had before {@link command:integration verify}. It still runs the same check, with the same output, JSON, and exit codes, and prints a note that names `integration verify`. It will be removed in a later release. Outside a package it writes nothing and reports one failed check, no_package, naming the integration package it needs (exit 1).',
   fn: 'integrationPackCheck',
   options: [
     {
@@ -19,6 +19,7 @@ export const doc = {
   examples: [
     {label: 'The old spelling', cli: 'astryx integration pack --check'},
   ],
+  outsideProject: 'own',
   exitCodes: [
     {code: 0, when: 'the packed package exposes the same valid contributions'},
     {
@@ -27,4 +28,10 @@ export const doc = {
     },
   ],
   related: ['integration verify'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, `integration pack --check` writes nothing, reports one failed check, `no_package`, and exits 1. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+  ],
 };

package/clients/cli/commands/integration-verify.doc.mjs

@@ -8,15 +8,22 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Check the package the way npm will publish it, before you publish',
   description:
-    'Packs the package with npm, unpacks the tarball into a temporary app without installing its dependencies, and checks that the app sees the same components, templates, themes, docs, and codemods as the package, that every public import resolves, and that the package declares a CLI new enough to read it. It publishes nothing and leaves no tarball behind. It runs the package\'s own pack lifecycle scripts, as `npm pack` does.',
+    'Packs the package with npm, unpacks the tarball into a temporary app without installing its dependencies, and checks that the app sees the same components, templates, themes, docs, and codemods as the package, that every public import resolves, and that the package declares a CLI new enough to read it. It publishes nothing and leaves no tarball behind. It runs the package\'s own pack lifecycle scripts, as `npm pack` does. Outside a package it writes nothing and reports one failed check, no_package, naming the integration package it needs (exit 1).',
   fn: 'integrationPackCheck',
   examples: [
     {label: 'Check before publishing', cli: 'astryx integration verify'},
     {label: 'Machine-readable result', cli: 'astryx integration verify --json'},
   ],
+  outsideProject: 'own',
   exitCodes: [
     {code: 0, when: 'the packed package exposes the same valid contributions'},
     {code: 1, when: 'the tarball is incomplete or invalid'},
   ],
   related: ['integration add', 'doctor integration validate'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, it writes nothing, reports one failed check, `no_package`, and exits 1. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+  ],
 };

package/clients/cli/commands/integration.doc.mjs

@@ -8,13 +8,17 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Author and verify an Astryx integration package',
   description:
-    'Add contributions to your package, then check the packed package the way an app receives it. The guides start at {@link namespace:integrations}.',
-  subcommands: ['add', 'verify', 'pack'],
+    'Add contributions to your package, check them on every build with `integration check --strict`, then check the packed package the way an app receives it. The guides start at {@link namespace:authoring}.',
+  subcommands: ['add', 'check', 'verify', 'pack'],
   examples: [
     {
       label: 'Add a component',
       cli: 'astryx integration add component AcmeWidget',
     },
+    {
+      label: 'Check the package in CI, as part of its build',
+      cli: 'astryx integration check --strict',
+    },
     {
       label: 'Check the package before publishing',
       cli: 'astryx integration verify',

package/clients/cli/commands/integration.mjs

@@ -3,19 +3,24 @@
 /** @file CLI bindings for integration authoring and package verification. */
 
 import {integrationAdd} from '../../../api/integration/add-contribution.mjs';
+import {integrationCheck} from '../../../api/integration/check/check.mjs';
 import {integrationPackCheck} from '../../../api/integration/pack-check.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
-import {emit, list, section, text} from '../formatters/index.mjs';
+import {emit, list, records, section, text} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as integrationGroup} from './integration.doc.mjs';
 import {doc as integrationAddCommand} from './integration-add.doc.mjs';
+import {doc as integrationCheckCommand} from './integration-check.doc.mjs';
 import {doc as integrationVerifyCommand} from './integration-verify.doc.mjs';
 import {doc as integrationPackCommand} from './integration-pack.doc.mjs';
 import {doc as integrationAddFn} from '../../../api/integration/integrationAdd.doc.mjs';
+import {doc as integrationCheckFn} from '../../../api/integration/integrationCheck.doc.mjs';
+import {printIntegrationCheckResponse} from './doctor.mjs';
 import {doc as integrationPackCheckFn} from '../../../api/integration/integrationPackCheck.doc.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
 
 /**
  * @param {import('commander').Command} command
@@ -75,10 +80,16 @@ async function verifyPackage(program) {
     if (issues.length > 0) {
       blocks.push(
         list(
-          issues.map(
-            issue =>
-              `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,
-          ),
+          issues.map(issue => [
+            `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,
+            // Every field the JSON issue carries.
+            ...(issue.file != null
+              ? [
+                  `file: ${issue.file}${issue.line != null ? `:${issue.line}` : ''}`,
+                ]
+              : []),
+            ...(issue.fix != null ? [`fix: ${issue.fix}`] : []),
+          ]),
         ),
       );
     }
@@ -88,6 +99,101 @@ async function verifyPackage(program) {
   return NO_RESULT_SET;
 }
 
+/**
+ * Run `integration check` and print each check as its own subcommand prints
+ * it, then one summary: each check's errors, warnings and skipped work, and
+ * what decided the exit code.
+ * @param {import('commander').Command} program
+ * @param {{strict?: boolean}} options
+ */
+async function checkPackage(program, options) {
+  const result = await integrationCheck({strict: options.strict === true});
+  if (program.opts().json) {
+    jsonOut(result);
+  } else {
+    const {data} = result;
+    const noPackage = data.checks[0]?.response.data.issues.some(
+      issue => issue.code === 'no_package',
+    );
+    if (noPackage) {
+      emit(
+        text(
+          'Nothing was checked: no package.json found. Run this command inside a package directory.',
+        ),
+      );
+    } else if (!data.validated) {
+      emit(
+        text(
+          'Nothing was checked: no astryx.integration.* found next to package.json. ' +
+            "Run this command in an integration package's folder.",
+        ),
+      );
+    } else {
+      data.checks.forEach((check, index) => {
+        // A blank line keeps each check's output apart from the next.
+        if (index > 0) emit(text(''));
+        printIntegrationCheckResponse(check.response);
+      });
+    }
+    const plural = (/** @type {number} */ n, /** @type {string} */ word) =>
+      `${n} ${word}${n === 1 ? '' : 's'}`;
+    const counts =
+      `${plural(data.errors, 'error')}, ${plural(data.warnings, 'warning')}, ` +
+      `${data.skipped.length} skipped`;
+    const notCompared =
+      data.unchecked > 0
+        ? ` ${plural(data.unchecked, 'item')} could not be compared; the checks above list them.`
+        : '';
+    const closing = noPackage
+      ? `[fail] ${counts}. No package.json was found here, so nothing was checked.`
+      : data.checks.some(check => check.failed)
+        ? `[fail] ${counts}. Address the items marked [fail] above.`
+        : data.failed
+          ? `[fail] ${counts}. --strict fails on every warning and on skipped work; fix them, or drop --strict to fail only on errors.`
+          : data.warnings > 0 || data.skipped.length > 0
+            ? `[ok] ${counts}. No check failed; review the warnings and skipped work above (--strict fails on them).${notCompared}`
+            : notCompared
+              ? `[ok] ${counts}. No check failed.${notCompared}`
+              : `[ok] ${counts}. Every check passed.`;
+    const identity = noPackage
+      ? '(no package.json)'
+      : data.version != null
+        ? `${data.name}@${data.version}`
+        : data.name;
+    emit(
+      // --strict lists each warning and each skipped check again, as the
+      // error it now is: by check, code and place only, since the check's own
+      // output above already printed its message and fix once.
+      ...(data.failures.length > 0
+        ? [
+            section('Failing under --strict'),
+            records(data.failures, {
+              fields: [
+                'severity',
+                'check',
+                'code',
+                'component',
+                'prop',
+                'file',
+                'line',
+              ],
+              format: {severity: () => '[fail]'},
+            }),
+          ]
+        : []),
+      section(
+        `Integration check: ${identity ?? '(local package)'}${data.strict ? ' (strict)' : ''}`,
+      ),
+      records(data.checks, {
+        fields: ['check', 'failed', 'errors', 'warnings', 'skipped'],
+      }),
+      text(closing),
+    );
+  }
+  if (result.data.failed) process.exitCode = 1;
+  return NO_RESULT_SET;
+}
+
 /** @param {import('commander').Command} program */
 export function registerIntegration(program) {
   /** @type {import('commander').Command} */
@@ -159,6 +265,12 @@ export function registerIntegration(program) {
   });
   addCmd.allowExcessArguments(false);
 
+  // It takes no package name, so a name passed by mistake is an error, not a
+  // silent check of the current folder.
+  defineCommand(integration, integrationCheckCommand, {
+    fn: integrationCheckFn,
+    action: async options => checkPackage(program, options),
+  }).allowExcessArguments(false);
   defineCommand(integration, integrationVerifyCommand, {
     fn: integrationPackCheckFn,
     action: async () => verifyPackage(program),
@@ -172,14 +284,14 @@ export function registerIntegration(program) {
       if (!options.check) {
         // One way forward: the new name. `npm pack` is what builds a tarball.
         return cliError(
-          '`integration pack` is now `integration verify`: run `astryx integration verify` to check the package the way npm will publish it. To build the tarball, run `npm pack`.',
+          `\`integration pack\` is now \`integration verify\`: run \`${formatCliCommand('integration verify')}\` to check the package the way npm will publish it. To build the tarball, run \`npm pack\`.`,
           {code: ERROR_CODES.ERR_INVALID_ARGUMENT},
         );
       }
       // stderr, and only in text: JSON callers get the same envelope as verify.
       if (!program.opts().json) {
         console.error(
-          'Note: `integration pack --check` is deprecated. Run `astryx integration verify`: it runs the same check.',
+          `Note: \`integration pack --check\` is deprecated. Run \`${formatCliCommand('integration verify')}\`: it runs the same check.`,
         );
       }
       return verifyPackage(program);

package/clients/cli/commands/json-contract.test.mjs

@@ -143,7 +143,12 @@ describe('--json contract: supported commands emit valid envelopes', () => {
     const parsed = parseJson(stdout);
     expect(parsed.type).toBe('discover.list');
     expect(parsed.data).toEqual([]);
-    expect(parsed.meta).toEqual({configured: false});
+    expect(parsed.meta.configured).toBe(false);
+    // The official list the CLI carries is always a source.
+    expect(parsed.meta.sources).toEqual([
+      expect.objectContaining({name: 'Astryx', status: 'fresh'}),
+    ]);
+    expect(parsed.meta.answeredBy).toEqual(expect.any(Object));
   });
 
   it('astryx template --json emits a typed envelope', async () => {
@@ -162,7 +167,11 @@ describe('--json contract: supported commands emit valid envelopes', () => {
   });
 
   it('astryx doctor --json emits a doctor envelope with checks + summary', async () => {
-    // Run in a bare tmp dir → @astryxdesign/core won't resolve → a FAIL → exit 1.
+    // A project that declares @astryxdesign/core but installs none → a FAIL → exit 1.
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}',
+    );
     const {status, stdout} = await runCli(['doctor', '--json'], {cwd: tmpDir});
     expect(status).toBe(1);
     const parsed = parseJson(stdout);

package/clients/cli/commands/manifest.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   name: 'manifest',
   displayName: 'astryx manifest',
   namespace: 'cli/commands',
-  summary: 'Print the full CLI capability manifest (use with --json).',
+  summary: 'Print the full CLI capability manifest (use with --json)',
   description:
     'Emits the complete CLI surface: every command with its arguments, options, ' +
     'subcommands, and JSON response types, as a single typed envelope for agents and ' +
@@ -22,6 +22,7 @@ export const doc = {
     {label: 'Full manifest', cli: 'astryx manifest --json'},
     {label: 'The same manifest, under data.manifest (type "help")', cli: 'astryx --json'},
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success'},
     {code: 1, when: 'the manifest cannot be generated'},

package/clients/cli/commands/manifest.mjs

@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file manifest command — `astryx manifest`, the CLI capability manifest.
+ *
+ * A single, self-describing view of the whole CLI so agents can discover every
+ * command, argument, flag, and response type without scraping `--help`.
+ * `astryx manifest --json` is the dedicated surface; the bare `astryx --json`
+ * embeds the same payload under data.manifest for convenience.
+ *
+ * Intentionally CLI-special — no `api/manifest`. It introspects the live
+ * Commander `program`, so extracting it to `api/` would create an `api → cli`
+ * cycle. `buildManifest(program)` lives in lib/; see its header. Register it
+ * after every other command: the manifest lists commands in registration order.
+ *
+ * The command surface comes from the colocated CommandDoc via `defineCommand`.
+ */
+
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, records} from '../formatters/index.mjs';
+import {buildManifest} from '../lib/manifest.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {resultSet} from '../../../foundation/debug/index.mjs';
+import {doc as manifestCommand} from './manifest.doc.mjs';
+
+/**
+ * @param {import('commander').Command} program the root program
+ * @param {{jsonSupported: Set<string>, version: string}} context the commands
+ *   that accept --json, and the CLI's version
+ */
+export function registerManifest(program, {jsonSupported, version}) {
+  defineCommand(program, manifestCommand, {
+    action: () => {
+      const manifest = buildManifest(program, {jsonSupported, version});
+      // The manifest IS a result set: one entry per command the CLI ships.
+      const answered = resultSet({
+        count: manifest.commands.length,
+        resultKind: 'command',
+      });
+      if (program.opts().json) {
+        jsonOut({type: 'manifest', data: manifest});
+        return answered;
+      }
+      // Human-readable summary as greppable records (agents should use --json).
+      // One record per command: name, whether it supports --json, and the
+      // description. Field names are the manifest entry's own keys.
+      emit(
+        section(
+          `${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`,
+        ),
+        records(
+          manifest.commands.map(c => ({
+            name: c.name,
+            json: c.json ? 'yes' : '',
+            description: c.description || '',
+          })),
+          {fields: ['name', 'json', 'description']},
+        ),
+        text(
+          `Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`,
+        ),
+      );
+      return answered;
+    },
+  });
+}