@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

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

@@ -16,10 +16,24 @@ export const doc = {
   summary: 'Initialize the design system in your project',
   description:
     'Non-interactive project setup (no prompts, so it behaves the same for humans, ' +
-    '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. ' +
+    'agents, and CI). By default it writes the agent-docs block, including guidance ' +
+    'from configured integrations, to AGENTS.md and to the Claude Code file the project ' +
+    'has (CLAUDE.md, else .claude/CLAUDE.md; when CLAUDE.md exists, a block in ' +
+    '.claude/CLAUDE.md is removed, unless the project ignores CLAUDE.md, in which case a .claude/CLAUDE.md the ' +
+    'project commits keeps a copy), and a one-line import of AGENTS.md to GEMINI.md ' +
+    'unless GEMINI.md already imports it. It then prints getting-started steps. Agent ' +
+    'docs go to the project root: the nearest folder at or above this one whose ' +
+    'package.json declares an @astryxdesign package, else the nearest with any ' +
+    'package.json, else this folder. The search stops at a repository root and never ' +
+    'counts the home folder. In the home folder, or in a settings folder in it ' +
+    'such as ~/.gemini outside a project, no agent docs are written. Every folder of the ' +
+    'home folder whose name starts with a dot is a settings folder, and such a folder ' +
+    'itself never counts as a project, even with a package.json; a project inside one, ' +
+    'such as an agent worktree with its own package.json, works. The managed block is ' +
+    'written whatever ignore rules or generated markers say; the text around it is never changed. ' +
+    '--features and --all print only ' +
+    "the chosen features' " +
+    'guidance (no 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. ' +
@@ -44,8 +58,10 @@ export const doc = {
       flag: '--remove-agents',
       param: 'options.removeAgents',
       description:
-        'Remove the managed block from AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, .cursorrules, .hermes.md and HERMES.md ' +
-        "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left) and do nothing else. " +
+        'Remove the managed block from AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md and HERMES.md, ' +
+        'at the project root (where init writes them) and in this folder ' +
+        "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left, and GEMINI.md when nothing is left) and do nothing else. " +
+        'Below the project root, a project-root agent file whose block resolves outside the project is left as it is, with a note. ' +
         '--features, --all, --agent and --agent-docs-path are refused; a file written with --agent-docs-path keeps its block',
     },
     {
@@ -66,7 +82,9 @@ export const doc = {
       choices: ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'],
       description:
         '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). ' +
+        'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc except GEMINI.md, which keeps its ' +
+        'one-line import of AGENTS.md, else AGENTS.md and .claude/CLAUDE.md). With claude and all, when CLAUDE.md gets the block, .claude/CLAUDE.md gets none and ' +
+        'a block already there is removed, unless the project ignores CLAUDE.md: then a .claude/CLAUDE.md the project commits gets a copy too, with claude and all alike. ' +
         '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.',
     },
@@ -76,6 +94,7 @@ export const doc = {
       description:
         'Explicit file path(s) for agent docs, inside the project; takes precedence over --agent. ' +
         'If any path is outside the project, no agent docs are written and the command exits 1. ' +
+        'A path in the home folder itself, or in a settings folder in it outside a project (such as ~/.claude or ~/.claude/hooks), is refused with a note (exit 0), and nothing is written. ' +
         'Used only when agent docs are installed',
     },
   ],
@@ -90,11 +109,11 @@ export const doc = {
   exitCodes: [
     {
       code: 0,
-      when: 'success, including agent docs that could not be written for a reason other than a path escape (reported as docsError)',
+      when: "success, including agent docs left unwritten in five soft cases, each reported as docsError with one note: running in the home folder, or in a settings folder in it outside a project; a GEMINI.md that resolves outside the project; when init runs below the project root, a project-root agent file that resolves outside the project; the project's Claude Code file (root CLAUDE.md, or .claude/CLAUDE.md when there is no root one) when it resolves outside the project and is a block-less import of an existing AGENTS.md, which 0.7.1 left alone; and a .claude/CLAUDE.md that resolves outside the project and that 0.7.1 did not write: beside a CLAUDE.md the project ignores, the one --agent claude adds or a block-less import of an existing AGENTS.md; with --agent claude beside a CLAUDE.md, one whose block it would remove",
     },
     {
       code: 1,
-            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)',
+      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); or, when init runs at the project root, an agent file 0.7.1 also wrote there that resolves outside the project (ERR_PATH_TRAVERSAL, docsError path-safety, nothing written)',
     },
   ],
   related: ['doctor', 'upgrade', 'build', 'theme'],

package/clients/cli/commands/init.flag-help.test.mjs

@@ -67,6 +67,7 @@ describe('astryx init flag interactions', () => {
       expect(help).toContain(file);
     }
     expect(help).toMatch(/--agent-docs-path are refused/);
+    expect(help).toMatch(/at the project root \(where init writes them\) and in this folder/);
 
     await initJson(['--agent-docs-path', 'docs/AI.md']);
     await initJson([]);

package/clients/cli/commands/init.mjs

@@ -3,8 +3,8 @@
 /**
  * @file init command — thin wrapper around the init API.
  *
- * `astryx init` is non-interactive by default: it installs the AGENTS.md/
- * CLAUDE.md cheat sheet with NO prompts, so it behaves identically for humans,
+ * `astryx init` is non-interactive by default: it installs the agent-docs
+ * cheat sheet with NO prompts, so it behaves identically for humans,
  * AI agents, CI, and piped I/O — it never hangs or errors on a missing TTY.
  * Non-interactive feature install: `astryx init --features agents,theme,template`
  * Re-runnable: safe to run multiple times, idempotent.

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

@@ -439,3 +439,51 @@ describe('a stray doc pointer', () => {
     expect(strict.stdout).toContain('stray_doc_pointer');
   });
 });
+describe('a command written with a runner', () => {
+  it('is a note in doctor integration validate, and integration check --strict still passes', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default {docs: './docs'};\n`,
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'));
+    const doc = {
+      type: 'generic',
+      name: 'acme-setup',
+      title: 'Fixture',
+      description: 'Fixture topic.',
+      sections: [
+        {
+          title: 'Overview',
+          content: [{type: 'code', lang: 'bash', code: 'npx astryx doctor'}],
+        },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      `export default ${JSON.stringify(doc)};\n`,
+    );
+
+    const doctor = await runCli(['doctor', 'integration', 'validate'], tmpDir);
+    expect(doctor.status).toBe(0);
+    expect(doctor.stdout).toContain(
+      'note (runner_command): docs/acme-setup.doc.mjs:',
+    );
+    expect(doctor.stdout).toContain('Write `astryx doctor`');
+
+    const strict = await runCli(
+      ['--json', 'integration', 'check', '--strict'],
+      tmpDir,
+    );
+    expect(strict.status).toBe(0);
+    const validate = JSON.parse(strict.stdout).data.checks.find(
+      (/** @type {any} */ each) => each.check === 'validate',
+    ).response.data;
+    expect(validate.notes.map((/** @type {any} */ note) => note.code)).toEqual([
+      'runner_command',
+    ]);
+  });
+});

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

@@ -8,7 +8,7 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Author and verify an Astryx integration package',
   description:
-    '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:integrations}.',
+    '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: [
     {

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 ' +

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;
+    },
+  });
+}

package/clients/cli/commands/outside-project.test.mjs

@@ -541,7 +541,8 @@ describe('init outside a project (own)', () => {
       const dir = tmpDir('init');
       const json = await answer(['--json', 'init'], dir);
       expect(json.status).toBe(0);
-      expect(json.written).toEqual(['AGENTS.md']);
+      // GEMINI.md gets its one-line import of AGENTS.md (spec cli-surface INV31).
+      expect(json.written).toEqual(['AGENTS.md', 'GEMINI.md']);
       expect(json.envelope.data.nextSteps).toBe(false);
       const text = await runCli(['init'], tmpDir('init-text'));
       expect(text.stdout).not.toContain('Next steps');

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

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx postinstall`. A hidden, CLI-only hook with no
+ * wrapped API function (so no `fn`): it prints the welcome box.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'postinstall',
+  displayName: 'astryx postinstall',
+  namespace: 'cli/commands',
+  summary: 'Print the welcome message shown after install',
+  description:
+    'Prints a short welcome box that names the first commands to run. It is hidden ' +
+    'from help and the manifest, looks nothing up, and does not support --json.',
+  examples: [{label: 'Print the welcome box', cli: 'astryx postinstall'}],
+  outsideProject: 'same',
+  exitCodes: [{code: 0, when: 'success'}],
+  related: ['init'],
+};

package/clients/cli/commands/postinstall.mjs

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file postinstall command — the hidden `astryx postinstall` hook.
+ *
+ * Prints the welcome box (lib/welcome-box.mjs). Hidden from help and the
+ * manifest; it looks nothing up and does not support --json.
+ *
+ * The command surface comes from the colocated CommandDoc via `defineCommand`.
+ */
+
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {emit, code} from '../formatters/index.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {welcomeBox} from '../lib/welcome-box.mjs';
+import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
+import {doc as postinstallCommand} from './postinstall.doc.mjs';
+
+/**
+ * @param {import('commander').Command} program
+ */
+export function registerPostinstall(program) {
+  defineCommand(program, postinstallCommand, {
+    hidden: true,
+    action: () => {
+      emit(code(welcomeBox(getCliInvocation())));
+      // Prints the welcome box. Nothing is looked up.
+      return NO_RESULT_SET;
+    },
+  });
+}

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

@@ -121,6 +121,25 @@ 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',
@@ -167,6 +186,48 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     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);
+  });
+
+  // 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);

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

@@ -96,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() {

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

@@ -21,6 +21,7 @@ export const doc = {
     'agent-docs block when Core or configured integration guidance changes. ' +
     'Dry-run by default. --apply writes codemod and receipt changes, runs hooks, then refreshes agent docs. ' +
     'Anything a post-codemod hook prints goes to stderr, so stdout carries only the result. ' +
+    'Run from a folder inside a project, it upgrades that project and names files in the result relative to the folder you ran it in. ' +
     'ShadCN-copied compositions are checked automatically during a normal upgrade, or alone with --registry. ' +
     'Outside a project, --list lists the codemods this release ships and --registry finds no copied compositions to update; ' +
     'a migration writes nothing and fails with ERR_VERSION_DETECT, because no installed Core names its target.',
@@ -69,8 +70,9 @@ export const doc = {
     {
       flag: '--path <dir>',
       param: 'options.path',
-      description: 'Source directory to scan',
-      default: './src',
+      description:
+        "Source directory to scan, relative to where you run the command, however you spell it. Without --path, the project's src folder, from any folder in the project",
+      default: './src at the project root',
     },
     {
       flag: '--install-deps',

package/clients/cli/commands/upgrade.mjs

@@ -31,8 +31,9 @@ export function registerUpgrade(program) {
     action:
       /**
        * @param {import('../../../api/upgrade/upgrade.mjs').UpgradeOptions} options
+       * @param {import('commander').Command} command
        */
-      async options => {
+      async (options, command) => {
         const json = program.opts().json || false;
         const isList = Boolean(options.list);
         // Silence the logger for --list so the handler renders from the
@@ -42,8 +43,14 @@ export function registerUpgrade(program) {
 
         /** @type {import('../../../api/upgrade/upgrade.type.mjs').UpgradeListResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRegistryResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeStatusResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRunResponse} */
         let result;
+        // `--path` shows its default in help, but a path nobody typed is the
+        // project's src, not one read from this folder: leave it unset.
+        const apiOptions =
+          command.getOptionValueSource('path') === 'default'
+            ? {...options, path: undefined}
+            : options;
         try {
-          result = await upgradeApi(options, {cwd: process.cwd()});
+          result = await upgradeApi(apiOptions, {cwd: process.cwd()});
         } catch (e) {
           // Re-enable the logger so the error is visible in text mode.
           // For --list the logger was silent; for other modes the API

package/clients/cli/commands/upgrade.subfolder-path.test.mjs

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx upgrade` from a folder inside a project: a `--path` you type
+ * is read from that folder, however you spell it, and without `--path` the
+ * upgrade scans the project's own src. The option's default must not read as
+ * a typed `./src`. The `--json` result names files relative to the folder the
+ * command ran in.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+/** Core 0.7.0 renamed this prop; its codemod renames it on Typeahead. */
+const OLD_PROP_SOURCE =
+  "import {Typeahead} from '@astryxdesign/core';\n" +
+  'export const App = () => <Typeahead label="Fruit" emptySearchResultsText="None" />;\n';
+
+let root;
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  const file = path.join(root, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, body);
+}
+
+/** @param {string} rel */
+const renamed = rel =>
+  fs
+    .readFileSync(path.join(root, rel), 'utf-8')
+    .includes('emptySearchText="None"');
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-subfolder-'));
+  write(
+    'package.json',
+    JSON.stringify({
+      name: 'app',
+      private: true,
+      dependencies: {'@astryxdesign/core': '0.7.0'},
+    }),
+  );
+  write(
+    'node_modules/@astryxdesign/core/package.json',
+    JSON.stringify({name: '@astryxdesign/core', version: '0.7.0'}),
+  );
+  write('src/App.tsx', OLD_PROP_SOURCE);
+  // A folder inside the project with source of its own and no package.json.
+  write('frontend/src/App.tsx', OLD_PROP_SOURCE);
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+/** @param {string[]} args @param {string} [folder] */
+async function upgradeFrom(args, folder = 'frontend') {
+  const r = await runCli(
+    ['upgrade', '--from', '0.6.8', ...args, '--apply', '--json'],
+    {
+      cwd: path.join(root, folder),
+    },
+  );
+  expect(r.status).toBe(0);
+  return JSON.parse(r.stdout);
+}
+
+describe('upgrade --path from a folder inside the project', () => {
+  it.each([['./src'], ['src'], ['src/'], ['./src/']])(
+    'reads --path %s from the folder you ran in',
+    async spelling => {
+      const result = await upgradeFrom(['--path', spelling]);
+
+      expect(result.data.modifiedFiles).toEqual(['src/App.tsx']);
+      expect(renamed('frontend/src/App.tsx')).toBe(true);
+      expect(renamed('src/App.tsx')).toBe(false);
+    },
+  );
+
+  it("scans the project's src without --path", async () => {
+    const result = await upgradeFrom([]);
+
+    expect(result.data.modifiedFiles).toEqual(['../src/App.tsx']);
+    expect(renamed('src/App.tsx')).toBe(true);
+    expect(renamed('frontend/src/App.tsx')).toBe(false);
+  });
+
+  it('names files from the project root when run there', async () => {
+    const result = await upgradeFrom([], '.');
+
+    expect(result.data.modifiedFiles).toEqual(['src/App.tsx']);
+  });
+});