@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

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

@@ -19,7 +19,12 @@ export const doc = {
     'agents, and CI). By default it installs the AGENTS.md/CLAUDE.md agent-docs, ' +
     'including guidance from configured integrations, and prints getting-started ' +
     "steps. --features and --all print only the chosen features' guidance (no " +
-    'getting-started steps); the theme feature also writes an annotated theme template.',
+    'getting-started steps); the theme feature also writes an annotated theme template. ' +
+    'Outside a project it writes the same files but prints no step that sets up a project: ' +
+    'no getting-started steps, and no step that adds a theme to an app. ' +
+        '--user writes the computer-level agent text instead (see the flag), in any folder, and touches nothing in the folder. ' +
+    'The CLI installed for the computer also keeps that text current in the background, unless --user --remove-agents turned it off; ' +
+    'package install scripts, project setup, and upgrade never write it.',
   fn: 'init',
   options: [
     {
@@ -43,6 +48,18 @@ export const doc = {
         "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left) and do nothing else. " +
         '--features, --all, --agent and --agent-docs-path are refused; a file written with --agent-docs-path keeps its block',
     },
+    {
+      flag: '--user',
+      param: 'options.user',
+      description:
+        'Write or refresh the computer-level agent text instead of setting up the folder: one skill file, ~/.agents/skills/astryx/SKILL.md, which most coding agents read, ' +
+        'linked into the skill folders of agents that read only their own (~/.claude/skills always; Kiro, Windsurf, Letta, Xcode\'s coding assistant, and ~/.config/agents/skills when that folder exists): a folder symlink with a relative target, a junction on Windows, or a copy where neither can be made. Continue, whose scanner skips links, gets a managed copy, refreshed with the file. ' +
+        "It tells agents anywhere on the computer that Astryx is there, when it is relevant, and to start with `astryx search`. " +
+        'Records the links it made in astryx/settings.json in the per-user configuration folder, so removal removes exactly those; the CLI installed for the computer refreshes the file in the background after each upgrade. ' +
+        'Works in any folder. A file without the Astryx markers, one edited since Astryx wrote it, or a symlink, is kept as it is, and so is anything at a link target that Astryx did not create. ' +
+        'Warns, and still writes, when no `astryx` command on the computer runs the Astryx CLI. ' +
+        'With --remove-agents it removes the file, the links, and the copy instead and records that the text is turned off. --features, --all, --agent and --agent-docs-path are refused',
+    },
     {
       flag: '--agent <tool>',
       param: 'options.agent',
@@ -51,7 +68,7 @@ export const doc = {
         'Target AI tool for agent docs: claude (CLAUDE.md or .claude/CLAUDE.md, else creates .claude/CLAUDE.md), cursor (.cursorrules if present, else AGENTS.md), ' +
         'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc, else AGENTS.md and .claude/CLAUDE.md). ' +
         'An unknown tool exits 1 with ERR_UNKNOWN_AGENT. ' +
-        'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence',
+                'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence.',
     },
     {
       flag: '--agent-docs-path <path...>',
@@ -66,7 +83,10 @@ export const doc = {
     {label: 'Default setup', cli: 'astryx init'},
     {label: 'All features, no prompts', cli: 'astryx init --all'},
     {label: 'Machine-readable receipt', cli: 'astryx init --json'},
+    {label: 'Agent text for the whole computer', cli: 'astryx init --user'},
+    {label: 'Remove the computer-level agent text and turn it off', cli: 'astryx init --user --remove-agents'},
   ],
+  outsideProject: 'own',
   exitCodes: [
     {
       code: 0,
@@ -74,8 +94,14 @@ export const doc = {
     },
     {
       code: 1,
-      when: 'an unknown --agent or feature, an --agent-docs-path outside the project, --remove-agents combined with install options, or --all with --features (ERR_INVALID_ARGUMENT)',
+            when: 'an unknown --agent (ERR_UNKNOWN_AGENT) or feature, an --agent-docs-path outside the project, --remove-agents combined with install options, --user combined with --features, --all, --agent or --agent-docs-path, or --all with --features (ERR_INVALID_ARGUMENT)',
     },
   ],
   related: ['doctor', 'upgrade', 'build', 'theme'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a project, init writes the agent docs (AGENTS.md) into the folder and prints no getting-started steps. `init --user` writes the agent guide for your computer, in any folder, and is never handed to a project's own CLI. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:computer-agent-guide}.",
+    },
+  ],
 };

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

@@ -113,6 +113,7 @@ export const doc = {
       cli: 'astryx integration add theme ocean --from neutral',
     },
   ],
+  outsideProject: 'refuse',
   exitCodes: [
     {code: 0, when: 'the contribution is written or the dry run succeeds'},
     {
@@ -121,4 +122,10 @@ export const doc = {
     },
   ],
   related: ['integration verify', 'doctor integration validate', 'theme add'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, integration add writes nothing and stops with `ERR_FILE_NOT_FOUND`: \"No package.json found. Run this command inside an integration package.\" 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-authoring.test.mjs

@@ -147,6 +147,52 @@ describe('integration authoring CLI', () => {
     );
   });
 
+  it("verify carries each issue's fix, file, and line in JSON and prints them in text", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'docs'],
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {docs: './docs'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'deploying.doc.mjs'),
+      "export const docs = {type: 'generic', name: 'deploying', title: 'Deploying', description: 'How to deploy.', sections: [{title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'ghost.doc.zh.mjs'),
+      "export default {title: 'ghost'};\n",
+    );
+
+    const json = parseEnvelope(
+      (await runCli(['integration', 'verify', '--json'], tmpDir)).stdout,
+    );
+    const orphans = json.data.issues.filter(issue =>
+      issue.code.endsWith('orphan_doc_overlay'),
+    );
+    expect(orphans.map(issue => issue.code).sort()).toEqual([
+      'orphan_doc_overlay',
+      'packed_orphan_doc_overlay',
+    ]);
+    for (const issue of orphans) {
+      expect(issue).toMatchObject({
+        file: 'docs/ghost.doc.zh.mjs',
+        line: 1,
+        fix: expect.stringContaining('Delete docs/ghost.doc.zh.mjs'),
+      });
+    }
+
+    const text = (await runCli(['integration', 'verify'], tmpDir)).stdout;
+    expect(text).toContain('file: docs/ghost.doc.zh.mjs:1');
+    expect(text).toContain(`fix: ${orphans[0].fix}`);
+  });
+
   it('keeps `integration pack --check` as a deprecated alias of `integration verify`', async () => {
     // The old spelling runs the same check: the same JSON, the same exit code.
     const verify = await runCli(['integration', 'verify', '--json'], tmpDir);
@@ -173,7 +219,7 @@ describe('integration authoring CLI', () => {
     expect(text.status).toBe(verifyText.status);
     expect(text.stdout).toBe(verifyText.stdout);
     expect(text.stderr).toContain('`integration pack --check` is deprecated');
-    expect(text.stderr).toContain('astryx integration verify');
+    expect(text.stderr).toContain(' integration verify`');
     // Without --check it fails, as it did, and points only at the new name:
     // suggesting `--check` would send people to the deprecated spelling.
     const bare = await runCli(['integration', 'pack'], tmpDir);
@@ -181,13 +227,13 @@ describe('integration authoring CLI', () => {
     expect(bare.stderr).toContain(
       '`integration pack` is now `integration verify`',
     );
-    expect(bare.stderr).toContain('astryx integration verify');
+    expect(bare.stderr).toContain(' integration verify`');
     expect(bare.stderr).toContain('npm pack');
     expect(bare.stderr).not.toContain('--check');
     const bareJson = await runCli(['--json', 'integration', 'pack'], tmpDir);
     expect(parseEnvelope(bareJson.stdout)).toMatchObject({
       code: 'ERR_INVALID_ARGUMENT',
-      error: expect.stringContaining('astryx integration verify'),
+      error: expect.stringContaining(' integration verify`'),
     });
     // Help lists it, marked deprecated: nothing is hidden.
     const help = await runCli(['integration', '--help'], tmpDir);

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

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx integration check`.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'integration check',
+  displayName: 'astryx integration check',
+  namespace: 'cli/commands',
+  summary:
+    "The CI check for an integration package's own build: every source check, run in continuous integration or a typecheck script, against the package in the current folder",
+  description:
+    'Takes no package argument: it runs the four `doctor integration` checks, ' +
+    '`validate`, `components`, `templates`, and `docs`, against the integration ' +
+    'package in the current folder, which is where its own build runs it. It prints ' +
+    'each result as that check ' +
+    'prints it, then a summary with the errors, warnings, and skipped work of each, ' +
+    'and exits 1 when any of the four would exit 1 on its own. With `--strict` it ' +
+    'also exits 1 on any warning and on any check, or comparison within a check, ' +
+    'that did not run, such as a package with no `astryx.integration.*` or a ' +
+    'comparison skipped because the project has no TypeScript, or prop types not ' +
+    'judged because its TypeScript is older than 4.8: it adds no check, ' +
+    'and lists each of those again as an error, after the checks, in their own ' +
+    'issue format. That is the line ' +
+    "for the package's own build, so its docs, types, and links stay in sync: run " +
+    'it as a `ci` step, or add ' +
+    '`"typecheck": "tsc --noEmit && astryx integration check --strict"` to the ' +
+    'scripts in package.json. Its exit codes and JSON are a contract for the builds ' +
+    'that run it: a new check, or a new failure code, joins only in a minor release ' +
+    'that names it in the release notes. A patch can still ship a Core component, ' +
+    'template, or CLI topic whose name conflicts with one of yours. Run ' +
+    '`integration check` on every build; run ' +
+    '`integration verify` before you publish, to check that the packed package ' +
+    'works in an app. To check an installed integration by name, run the ' +
+    '`doctor integration` subcommands with its package name. Outside a package, ' +
+    'it writes nothing, `validate` reports one `no_package` issue, and it exits 1.',
+  fn: 'integrationCheck',
+  options: [
+    {
+      flag: '--strict',
+      param: 'options.strict',
+      description:
+        'Also exit 1 on any warning and on any check that did not run. A new check or failure code joins only in a minor release, named in the release notes; until then, a malformed `cliCommand` is reported as a note (`invalid_cli_command`) that fails nothing.',
+    },
+  ],
+  examples: [
+    {
+      label:
+        'In CI, as the typecheck script: add "typecheck": "tsc --noEmit && astryx integration check --strict" to package.json',
+      cli: 'integration check --strict',
+    },
+    {
+      label: 'Errors only, while you fix the warnings a package already has',
+      cli: 'integration check',
+    },
+    {
+      label: 'Read the result as JSON',
+      cli: 'integration check --strict --json',
+    },
+    {
+      label:
+        'Before you publish: check that the packed package works in an app',
+      cli: 'integration verify',
+    },
+  ],
+  outsideProject: 'own',
+  exitCodes: [
+    {
+      code: 0,
+      when: 'no check fails on its own; with --strict, also no warning, and every check ran',
+    },
+    {
+      code: 1,
+      when: 'a check fails on its own (an error); with --strict, also any warning, or a check that did not run',
+    },
+  ],
+  related: [
+    'integration verify',
+    'doctor integration validate',
+    'doctor integration components',
+    'doctor integration templates',
+    'doctor integration docs',
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, it writes nothing, its `validate` check reports one `no_package` issue, and it 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}.",
+    },
+  ],
+};