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

package/clients/cli/commands/setup-nudge.test.mjs

@@ -16,9 +16,24 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {isAstryxInitialized} from '../../../foundation/agent-docs/agent-docs.mjs';
+import {fileURLToPath} from 'node:url';
+import {
+  isAstryxInitialized,
+  isAstryxPromptInReach,
+} from '../../../foundation/agent-docs/agent-docs.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 
+/** This source checkout: the tests run the CLI from it. */
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+
+/** Is `dir` inside a git repository? The temp folder normally is not. */
+function insideRepository(dir) {
+  for (let d = path.resolve(dir); ; d = path.dirname(d)) {
+    if (fs.existsSync(path.join(d, '.git'))) return true;
+    if (path.dirname(d) === d) return false;
+  }
+}
+
 const MARKER = '<!-- ASTRYX:START -->';
 const NUDGE = /finish setup and install the Astryx agent prompt/;
 
@@ -61,8 +76,44 @@ describe('isAstryxInitialized — centralized setup check (one place)', () => {
   });
 });
 
+// Agents read the agent docs between the repository root and the folder they
+// work in, so a monorepo initialized at its root is set up in every package.
+describe('isAstryxPromptInReach — up to the repository root', () => {
+  it('finds init\'s block at the repository root from a workspace package', () => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('AGENTS.md', MARKER);
+    write('packages/app/package.json', '{"name":"app"}');
+    expect(isAstryxPromptInReach(path.join(tmp, 'packages/app'))).toBe(true);
+  });
+
+  it('treats a worktree .git file as the repository root', () => {
+    write('.git', 'gitdir: /elsewhere\n');
+    write('CLAUDE.md', MARKER);
+    write('packages/app/package.json', '{"name":"app"}');
+    expect(isAstryxPromptInReach(path.join(tmp, 'packages/app'))).toBe(true);
+  });
+
+  it('does not look above the repository root', () => {
+    write('AGENTS.md', MARKER);
+    fs.mkdirSync(path.join(tmp, 'repo/.git'), {recursive: true});
+    write('repo/pkg/package.json', '{"name":"pkg"}');
+    expect(isAstryxPromptInReach(path.join(tmp, 'repo/pkg'))).toBe(false);
+  });
+
+  it.skipIf(insideRepository(os.tmpdir()))(
+    'checks only the folder itself outside a repository',
+    () => {
+      write('AGENTS.md', MARKER);
+      write('pkg/package.json', '{"name":"pkg"}');
+      expect(isAstryxPromptInReach(tmp)).toBe(true);
+      expect(isAstryxPromptInReach(path.join(tmp, 'pkg'))).toBe(false);
+    },
+  );
+});
+
 describe('enforcement layer 3 — per-command setup nudge', () => {
-  const asProject = () => write('package.json', '{"name":"t"}');
+  const asProject = () =>
+    write('package.json', '{"name":"t","dependencies":{"@astryxdesign/core":"*"}}');
 
   it('nudges on stderr after a command when not set up', async () => {
     asProject();
@@ -70,6 +121,41 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     expect(r.stderr).toMatch(NUDGE);
   });
 
+  it.each([
+    ['in the home folder', ''],
+    ['at the top of a settings folder in it', '.dotfiles'],
+  ])('stays quiet %s, where init writes no agent docs', async (_label, rel) => {
+    const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+    process.env.HOME = tmp;
+    process.env.USERPROFILE = tmp;
+    try {
+      write(path.join(rel, 'package.json'), '{"name":"t"}');
+      const r = await runCli(['docs', 'tokens'], path.join(tmp, rel));
+      expect(r.stderr).not.toMatch(NUDGE);
+    } finally {
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+
+  it("in a project with only Core of another release, names adding the CLI at Core's version first, as the daily hint does", async () => {
+    write(
+      'package.json',
+      '{"name":"t","dependencies":{"@astryxdesign/core":"0.0.1"}}',
+    );
+    write(
+      'node_modules/@astryxdesign/core/package.json',
+      '{"name":"@astryxdesign/core","version":"0.0.1"}',
+    );
+    write('package-lock.json', '{}');
+    const r = await runCli(['docs', 'tokens'], tmp);
+    expect(r.stderr).toContain(
+      'Next step: run `npm install @astryxdesign/cli@0.0.1`, then `npx astryx init` to finish setup and install the Astryx agent prompt.',
+    );
+  });
+
   it('is suppressed in --json (machine mode stays clean), stdout valid JSON', async () => {
     asProject();
     const r = await runCli(['--json', 'docs', 'tokens'], tmp);
@@ -89,14 +175,106 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
   });
 
+  it('is quiet outside a project (a package.json that declares no Astryx package)', async () => {
+    write('package.json', '{"name":"t"}');
+    expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
+  });
+
   it('is quiet in an integration package, which is not an app', async () => {
     asProject();
     write('astryx.integration.mjs', 'export default {};\n');
     expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
   });
 
+  it('is quiet in a nested package once init has written the docs at the project root', async () => {
+    // init run in functions/ writes at the root that declares Astryx.
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('AGENTS.md', MARKER);
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    expect(r.stderr).not.toMatch(NUDGE);
+  });
+
+  it('nudges in a nested package while the project root has no docs', async () => {
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    expect(r.stderr).toMatch(NUDGE);
+  });
+
+  // A nested package.json that is not the project's (spec AST-040 FR9): the
+  // reminder sends the person to the project's folder, never adds the CLI to
+  // the nested package.json (spec AST-081 FR2).
+  it("in a nested package whose package.json is not the project's, says to run from the project's folder", async () => {
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('package-lock.json', '{}');
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    // Only `cd` comes first, so the app has no CLI of its own yet: the
+    // command is the scoped package at the answering release, never the bare
+    // `astryx` name a package runner would fetch from the registry.
+    const {version} = JSON.parse(fs.readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
+    expect(r.stderr.trim()).toBe(
+      `Next step: run \`cd ${tmp}\`, then \`npx @astryxdesign/cli@${version} init\` to finish setup and install the Astryx agent prompt.`,
+    );
+  });
+
+  // Inside a git repository the project-root check above adds nothing to the
+  // walk up to the repository root: the same outcomes as without it.
+  it('inside a repository, is quiet in a nested package once init has written the docs at the project root', async () => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('AGENTS.md', MARKER);
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    expect(r.stderr).not.toMatch(NUDGE);
+  });
+
+  it('inside a repository, still nudges when the only docs lie above the repository root', async () => {
+    write('package.json', JSON.stringify({name: 'outer', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('AGENTS.md', MARKER);
+    fs.mkdirSync(path.join(tmp, 'repo', '.git'), {recursive: true});
+    write('repo/package.json', '{"name":"repo"}');
+    // It declares Astryx: a folder that declares nothing is outside a
+    // project, where no reminder prints (spec AST-081 FR3).
+    write(
+      'repo/functions/package.json',
+      JSON.stringify({name: 'functions', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'repo', 'functions'));
+    expect(r.stderr).toMatch(NUDGE);
+  });
+
   it('does not nudge for the installer command itself', async () => {
     asProject();
     expect((await runCli(['init'], tmp)).stderr).not.toMatch(NUDGE);
   });
+
+  it('is quiet in a workspace package when init\'s block is at the repository root', async () => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('AGENTS.md', MARKER);
+    write('packages/app/package.json', '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'packages/app'));
+    expect(r.stderr).not.toMatch(NUDGE);
+  });
+
+  it('still nudges in a workspace package with no block up to the repository root', async () => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('AGENTS.md', 'project notes, no astryx block');
+    write('packages/app/package.json', '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'packages/app'));
+    expect(r.stderr).toMatch(NUDGE);
+  });
+
+  // The tests run the CLI from this checkout, so a project inside it is the
+  // contributor flow. The same project in the temp folder nudges (above).
+  it('is quiet inside the source checkout the CLI runs from', async () => {
+    const inside = fs.mkdtempSync(path.join(REPO, '.astryx-setup-nudge-'));
+    try {
+      fs.writeFileSync(path.join(inside, 'package.json'), '{"name":"t","dependencies":{"@astryxdesign/core":"*"}}');
+      expect((await runCli(['docs', 'tokens'], inside)).stderr).not.toMatch(NUDGE);
+    } finally {
+      fs.rmSync(inside, {recursive: true, force: true});
+    }
+  });
 });

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

@@ -57,6 +57,7 @@ export const doc = {
       cli: 'astryx swizzle SideNav --package @astryxdesign/core',
     },
   ],
+  outsideProject: 'refuse',
   exitCodes: [
     {code: 0, when: 'success'},
     {
@@ -65,4 +66,10 @@ export const doc = {
     },
   ],
   related: ['component', 'discover', 'upgrade'],
+  notes: [
+    {
+      type: 'prose',
+      text: 'In global mode: outside a project, swizzle writes nothing and stops with `ERR_CORE_NOT_FOUND`: "Could not find @astryxdesign/core package. Make sure you are inside the design system monorepo or have @astryxdesign/core installed." In a project, the project\'s version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:problems}.',
+    },
+  ],
 };

package/clients/cli/commands/swizzle.mjs

@@ -91,14 +91,16 @@ export function registerSwizzle(program) {
         ),
       ];
 
-      // StyleX build requirement — swizzled StyleX source renders unstyled with
-      // no error unless the consumer's build runs a StyleX compiler.
+      // StyleX build requirement — swizzled StyleX source throws on import
+      // ("Unexpected 'stylex.create' call at runtime") unless the consumer's
+      // build runs a StyleX compiler, so the page does not render at all.
       if (usesStyleX) {
         out.push(
           text(
             [
               `${WARN} These components use StyleX and require a StyleX compiler in your build.`,
-              '  Without one they render unstyled (no error). See setup per framework:',
+              `  Without one, importing them throws "Unexpected 'stylex.create' call at runtime"`,
+              '  and the page does not render. See setup per framework:',
               `  ${run} docs styling`,
               '  Next.js note: the StyleX Babel plugin disables SWC and breaks next/font -',
               '  use an SWC-based StyleX transform instead (covered in the guide).',

package/clients/cli/commands/swizzle.routing.test.mjs

@@ -15,8 +15,16 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 
+/** The StyleX runtime that Core ships with, resolved the way Core resolves it. */
+const CORE_PACKAGE = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../../core/package.json',
+);
+
 /**
  * Build a fake @astryxdesign/core under <project>/node_modules with a single
  * swizzleable Button component (bare `Button.tsx`, no doc).
@@ -303,10 +311,19 @@ describe('swizzle — StyleX build setup note (#3373)', () => {
     const humanResult = await runCli(['swizzle', 'Styled', '-f'], project);
     expect(humanResult.code).toBe(0);
     expect(humanResult.stdout).toMatch(/StyleX compiler/i);
-    expect(humanResult.stdout).toMatch(/unstyled/i);
+    expect(humanResult.stdout).toMatch(/importing them throws "Unexpected 'stylex\.create' call at runtime"/);
+    expect(humanResult.stdout).not.toMatch(/unstyled/i);
     expect(humanResult.stdout).toMatch(/next\/font/i);
     // The fixture has no `astryx` bin installed, so the note names the scoped package.
-    expect(humanResult.stdout).toMatch(/@astryxdesign\/cli docs styling/);
+    expect(humanResult.stdout).toMatch(/@astryxdesign\/cli@\S+ docs styling/);
+  });
+
+  // The note quotes what StyleX does without a compiler; this keeps it true.
+  it('matches what the StyleX runtime does when styles are not compiled', () => {
+    const stylex = createRequire(CORE_PACKAGE)('@stylexjs/stylex');
+    expect(() => stylex.create({root: {color: 'red'}})).toThrow(
+      /Unexpected 'stylex\.create' call at runtime/,
+    );
   });
 
   it('does not print the StyleX note for components without StyleX', async () => {

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

@@ -102,6 +102,7 @@ export const doc = {
       cli: 'astryx template --cdn public/demo.html',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {
       code: 0,

package/clients/cli/commands/text-json-parity.test.mjs

@@ -341,6 +341,11 @@ const CASES = [
     args: ['doctor', 'integration', 'validate'],
     skipFieldChecks: true,
   },
+  {
+    name: 'integration check',
+    args: ['integration', 'check'],
+    skipFieldChecks: true,
+  },
   {
     name: 'doctor integration components',
     args: ['doctor', 'integration', 'components'],

package/clients/cli/commands/theme-add-lifecycle.test.mjs

@@ -20,7 +20,7 @@ beforeEach(() => {
     JSON.stringify({
       name: 'app',
       private: true,
-      dependencies: {'@acme/themes': '^1.0.0'},
+      dependencies: {'@acme/themes': '^1.0.0', '@astryxdesign/core': '*'},
     }),
   );
   const packageDir = path.join(tmpDir, 'node_modules', '@acme', 'themes');
@@ -99,7 +99,7 @@ describe('theme add cleanup lifecycle', () => {
         change: {action: 'add', slug: 'ocean', changed: true},
       },
     });
-    expect(payload.meta).toBeUndefined();
+    expect(Object.keys(payload.meta)).toEqual(['answeredBy']);
   });
 
   it('keeps --import as an accepted no-op with the same response', async () => {
@@ -151,7 +151,7 @@ describe('theme add cleanup lifecycle', () => {
     expect(result.status, result.stderr).toBe(0);
     const payload = JSON.parse(result.stdout);
     expect(payload).toMatchObject({type: 'theme.list'});
-    expect(payload.meta).toBeUndefined();
+    expect(Object.keys(payload.meta)).toEqual(['answeredBy']);
     expect(payload.data.some(theme => theme.slug === 'broken')).toBe(false);
     expect(Object.keys(payload.data[0]).sort()).toEqual([
       'description',

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

@@ -11,7 +11,7 @@ export const doc = {
   summary:
     "Add a built theme to the app. To copy a theme's source as an editable fork, run `theme eject <slug> [path] [--overwrite]`.",
   description:
-    "Records the theme in the generated app module and imports its built module and stylesheets. --import remains accepted as a compatibility no-op. To copy a theme's source as an editable fork, run `theme eject <slug> [path] [--overwrite]`. A bare command or --list delegates to themeListCopySources(), whose released JSON bytes stay unchanged while its text names the current add and eject commands; use --package when owners share a slug.",
+    "Records the theme in the generated app module and imports its built module and stylesheets. --import remains accepted as a compatibility no-op. To copy a theme's source as an editable fork, run `theme eject <slug> [path] [--overwrite]`. A bare command or --list delegates to themeListCopySources(), whose released JSON bytes stay unchanged while its text names the current add and eject commands; use --package when owners share a slug. Outside a project, a bare command or --list lists the available themes as in a new project; given a slug it writes nothing and fails, naming the app project it needs (ERR_THEME_INVALID), or with ERR_UNKNOWN_THEME when no theme has that slug.",
   fn: 'themeAdd',
   args: [{name: 'slug', param: 'slug', required: false}],
   options: [
@@ -38,6 +38,7 @@ export const doc = {
       cli: 'astryx theme add ocean --package @acme/themes',
     },
   ],
+  outsideProject: 'own',
   exitCodes: [
     {code: 0, when: 'the theme is listed or added'},
     {
@@ -46,4 +47,10 @@ export const doc = {
     },
   ],
   related: ['theme list', 'theme remove', 'theme use', 'theme eject'],
+  notes: [
+    {
+      type: 'prose',
+      text: 'In global mode: outside a project, theme add with no slug lists the themes available, as in a new project; with a slug it writes nothing and stops with `ERR_THEME_INVALID`: "No package.json found. Run this command inside an app project." In a project, the project\'s version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:problems}.',
+    },
+  ],
 };

package/clients/cli/commands/theme-build.doc.mjs

@@ -30,7 +30,7 @@ export const doc = {
     {
       flag: '--family',
       description:
-        'Build the selected extension family into one keyed CSS, JS, and declaration set. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
+        'Build the selected extension family into one keyed CSS, JS, and declaration set, written beside the family root theme file, which must be inside the working directory to build (ERR_PATH_TRAVERSAL); --check only reads, so it compares outputs anywhere. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
     },
     {
       flag: '--family-key <key>',
@@ -41,7 +41,7 @@ export const doc = {
       flag: '-o, --out <path>',
       param: 'options.out',
       description:
-        'Output CSS file path; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A relative path must stay inside the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
+        'Output CSS file path, relative or absolute; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A build writes only inside the working directory, the defaults beside the source too (ERR_PATH_TRAVERSAL); --check writes nothing, so it compares outputs anywhere and refuses only a relative path that escapes the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
     },
     {
       flag: '--icons-specifier <specifier>',
@@ -83,6 +83,7 @@ export const doc = {
       cli: 'astryx theme build ./src/themes/ocean.ts --icons-specifier ./icons.mjs',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {
       code: 0,

package/clients/cli/commands/theme-eject.doc.mjs

@@ -36,6 +36,7 @@ export const doc = {
       cli: 'astryx theme eject ocean src/themes/my-ocean --package @acme/themes',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'all source and descriptor files are written'},
     {

package/clients/cli/commands/theme-list.behavior.test.mjs

@@ -24,6 +24,12 @@ afterEach(() => {
 
 describe('astryx theme list', () => {
   it('lists bundled themes and points at import, eject, and discover', async () => {
+    // Inside a project; outside one there is no app to import into
+    // (outside-project.test.mjs).
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}',
+    );
     const {status, stdout} = await runCli(['theme', 'list'], {cwd: tmpDir});
 
     expect(status).toBe(0);

package/clients/cli/commands/theme-list.doc.mjs

@@ -33,6 +33,7 @@ export const doc = {
       cli: 'astryx theme list --package @acme/themes',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success'},
     {

package/clients/cli/commands/theme-palette-generate.doc.mjs

@@ -57,6 +57,7 @@ export const doc = {
       cli: 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts --preview themes/ocean/tokens/ocean.palette.html',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {
       code: 0,

package/clients/cli/commands/theme-remove.doc.mjs

@@ -14,9 +14,16 @@ export const doc = {
   fn: 'themeRemove',
   args: [{name: 'slug', param: 'slug', required: true}],
   examples: [{label: 'Remove an added theme', cli: 'astryx theme remove ocean'}],
+  outsideProject: 'refuse',
   exitCodes: [
     {code: 0, when: 'the module is regenerated without the theme'},
     {code: 1, when: 'the theme is not added, is the default, or state is invalid'},
   ],
   related: ['theme add', 'theme use', 'theme list'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a project, theme remove writes nothing and stops with `ERR_THEME_INVALID`: \"No package.json found. Run this command inside an app project.\" In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:problems}.",
+    },
+  ],
 };

package/clients/cli/commands/theme-targets.doc.mjs

@@ -30,6 +30,7 @@ export const doc = {
     {label: 'Search keys', cli: 'astryx theme targets thumb'},
     {label: 'For a lint or an audit script', cli: 'astryx --json theme targets'},
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success'},
     {code: 1, when: 'a filter matches no target, or core cannot be resolved'},

package/clients/cli/commands/theme-template.doc.mjs

@@ -35,6 +35,7 @@ export const doc = {
     {label: 'Write it at the project root', cli: 'astryx theme template'},
     {label: 'Somewhere else', cli: 'astryx theme template src/themes/starter.ts'},
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success, including when an existing file was left untouched'},
     {code: 1, when: 'the target path escapes the project, or the file cannot be written'},

package/clients/cli/commands/theme-use.doc.mjs

@@ -14,9 +14,16 @@ export const doc = {
   fn: 'themeUse',
   args: [{name: 'slug', param: 'slug', required: true}],
   examples: [{label: 'Choose the default theme', cli: 'astryx theme use ocean'}],
+  outsideProject: 'refuse',
   exitCodes: [
     {code: 0, when: 'the module is regenerated with the selected default'},
     {code: 1, when: 'the theme is not added or state is invalid'},
   ],
   related: ['theme add', 'theme remove', 'theme list'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a project, theme use writes nothing and stops with `ERR_THEME_INVALID`: \"No package.json found. Run this command inside an app project.\" In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:problems}.",
+    },
+  ],
 };

package/clients/cli/commands/{build-theme.mjs → theme.mjs}

@@ -34,6 +34,7 @@ import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {spawn} from 'node:child_process';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {isOutsideProject} from '../../../foundation/env/project-scope.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {
   emit,
@@ -95,7 +96,7 @@ import {doc as themePaletteGenerateFn} from '../../../api/theme/themePaletteGene
 
 /**
  * Path to this CLI's real entry (clients/cli/bin/astryx.mjs), resolved from
- * this module's location (clients/cli/commands/build-theme.mjs → ../bin/
+ * this module's location (clients/cli/commands/theme.mjs → ../bin/
  * astryx.mjs). Used to re-invoke `theme build` as a child process in watch mode.
  */
 function resolveCliBin() {
@@ -224,10 +225,13 @@ async function runThemeBuildWatch(entries, options) {
   emit(text(watchingLine));
 
   await new Promise((/** @type {(value?: void) => void} */ resolve) => {
+    let stopping = false;
     /** @param {NodeJS.Signals} signal */
     const stop = async signal => {
-      process.removeListener('SIGINT', stop);
-      process.removeListener('SIGTERM', stop);
+      // A second interrupt while stopping (a terminal's Ctrl-C and the same
+      // signal passed on by the copy that started the run) changes nothing.
+      if (stopping) return;
+      stopping = true;
       stopped = true;
       queued.clear();
       for (const d of debounces.values()) clearTimeout(d);
@@ -237,10 +241,12 @@ async function runThemeBuildWatch(entries, options) {
       rebuildChild?.kill(signal);
       await rebuildDone;
       emit(text('\nStopped watching.'));
+      process.removeListener('SIGINT', stop);
+      process.removeListener('SIGTERM', stop);
       resolve();
     };
-    process.once('SIGINT', stop);
-    process.once('SIGTERM', stop);
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
   });
 }
 
@@ -283,14 +289,24 @@ function printThemeAddList(themes) {
         return theme.description ? [head, theme.description] : head;
       }),
     ),
-    text(
-      `Import one: ${run} theme add <slug> [--package <package>]\n` +
-        `Fork source: ${run} theme eject <slug> [target-path]`,
-    ),
+    text(themeNextSteps(run)),
     more,
   );
 }
 
+/**
+ * What to do with a listed theme. Outside a project there is no app to add one
+ * to, so only the fork step is named (spec AST-081 FR3).
+ * @param {string} run the CLI invocation
+ * @returns {string}
+ */
+function themeNextSteps(run) {
+  const fork = `Fork source: ${run} theme eject <slug> [target-path]`;
+  return isOutsideProject()
+    ? fork
+    : `Import one: ${run} theme add <slug> [--package <package>]\n${fork}`;
+}
+
 /**
  * Print every field in the `theme.list` entries. Duplicate slugs stay separate
  * because each record names its owner.
@@ -325,10 +341,7 @@ function printThemeList(themes, unmigratedCopies = []) {
           default: (/** @type {boolean} */ value) => (value ? 'yes' : 'no'),
         },
       }),
-      text(
-        `Import one: ${run} theme add <slug> [--package <package>]\n` +
-          `Fork source: ${run} theme eject <slug> [target-path]`,
-      ),
+      text(themeNextSteps(run)),
       more,
     );
   }
@@ -397,7 +410,7 @@ function printThemeApp(result) {
   emit(
     text('Wire the generated module once in the app root:'),
     code(
-      "import {Theme} from '@astryxdesign/core';\n" +
+      "import {Theme} from '@astryxdesign/core/theme';\n" +
         `import {themes, defaultThemeSlug} from './${stem}';\n\n` +
         '<Theme theme={themes[defaultThemeSlug]}>\n  <App />\n</Theme>',
     ),

package/clients/cli/commands/upgrade.config-ordering.test.mjs

@@ -30,6 +30,7 @@ import {Command} from 'commander';
 import {registerUpgrade} from './upgrade.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
 import {generateCompressedIndex} from '../../../foundation/agent-docs/agent-docs.mjs';
+import {CLI_VERSION} from '../../../test-utils/release-fixtures.mjs';
 
 let tmpDir;
 let originalCwd;
@@ -189,7 +190,7 @@ describe('upgrade — core codemods run before config load', () => {
     expect(out).toMatch(/fails strict validation/i);
     // The fixture has no `astryx` bin installed, so the command names the scoped package.
     expect(out).toContain(
-      '@astryxdesign/cli upgrade --from 0.1.2 --codemod migrate-layout-components-to-experimental --apply',
+      `@astryxdesign/cli@${CLI_VERSION} upgrade --from 0.1.2 --codemod migrate-layout-components-to-experimental --apply`,
     );
     expect(exitCode).not.toBe(1);
   });