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

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

@@ -21,7 +21,10 @@ 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. ' +
-    'ShadCN-copied compositions are checked automatically during a normal upgrade, or alone with --registry.',
+    '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.',
   fn: 'upgrade',
   options: [
     {
@@ -67,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',
@@ -102,6 +106,7 @@ export const doc = {
     },
     {label: 'Apply a migration', cli: 'astryx upgrade --from 0.1.0 --apply'},
   ],
+  outsideProject: 'own',
   exitCodes: [
     {code: 0, when: 'success, including complete dry-run previews'},
     {
@@ -116,6 +121,24 @@ export const doc = {
   ],
   related: ['init', 'doctor'],
   notes: [
+    {
+      type: 'prose',
+      text: "In global mode: in a project, upgrade runs the codemods of the project's own CLI, whichever astryx command you start; in a project with no CLI of its own, the astryx command you started runs them, so install the CLI at the new Core's version first (`astryx doctor` prints the command). Outside a project, `--list` lists this version's codemods, `--registry` finds no copied compositions, and a migration writes nothing and stops with `ERR_VERSION_DETECT`. See {@link namespace:global} and {@link generic:who-answers}.",
+    },
+    {type: 'heading', level: 3, text: 'A CLI older than your Core'},
+    {
+      type: 'prose',
+      text:
+        'Core codemods ship inside the CLI, so a CLI older than the installed @astryxdesign/core has none for ' +
+        'the releases after its own version. upgrade then says it cannot finish, never reports your code as up to date, ' +
+        'and prints the same upgrade pinned to the CLI release that matches your Core, such as ' +
+        '`cd <project> && npx @astryxdesign/cli@<core-version> upgrade --from <old-version> --path <source-dir> --apply`. ' +
+        'It changes to the folder this run used and names the directory it scanned as an absolute path, both with ' +
+        'symbolic links resolved, so pasted from any folder it upgrades the same code. It is written for a POSIX shell (sh, bash, zsh), or for PowerShell on Windows, ' +
+        'with each argument quoted for that shell; cmd.exe is not a target. The codemods this CLI has still run. ' +
+        'It exits 0, so a script checks the JSON: the result carries `cliBehindCore` with `cliVersion` (the newest release ' +
+        'this CLI has codemods for) and `command`.',
+    },
     {type: 'heading', level: 3, text: 'Protected files'},
     {
       type: 'prose',

package/clients/cli/commands/upgrade.file-protection.test.mjs

@@ -10,6 +10,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
+import {CLI_VERSION} from '../../../test-utils/release-fixtures.mjs';
 
 const CLI = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -44,7 +45,7 @@ function seed({hook = false} = {}) {
   write('package.json', JSON.stringify({name: 'consumer', private: true}));
   write(
     'node_modules/@astryxdesign/core/package.json',
-    JSON.stringify({name: '@astryxdesign/core', version: '0.6.0'}),
+    JSON.stringify({name: '@astryxdesign/core', version: CLI_VERSION}),
   );
   write('.gitattributes', 'generated/** linguist-generated=true\n');
   const source =
@@ -122,7 +123,7 @@ describe('upgrade protected-file contract', () => {
     write('package.json', JSON.stringify({name: 'consumer', private: true}));
     write(
       'node_modules/@astryxdesign/core/package.json',
-      JSON.stringify({name: '@astryxdesign/core', version: '0.1.3'}),
+      JSON.stringify({name: '@astryxdesign/core', version: CLI_VERSION}),
     );
     write(
       'astryx.config.mjs',

package/clients/cli/commands/upgrade.hook-output.test.mjs

@@ -12,6 +12,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {fileURLToPath} from 'node:url';
+import {CLI_VERSION} from '../../../test-utils/release-fixtures.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI = path.resolve(__dirname, '..', 'bin', 'astryx.mjs');
@@ -41,7 +42,7 @@ beforeEach(() => {
   write('package.json', JSON.stringify({name: 'consumer', private: true}));
   write(
     'node_modules/@astryxdesign/core/package.json',
-    JSON.stringify({name: '@astryxdesign/core', version: '0.6.0'}),
+    JSON.stringify({name: '@astryxdesign/core', version: CLI_VERSION}),
   );
   write(
     'src/panel.tsx',

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.older-cli.test.mjs

@@ -0,0 +1,160 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx upgrade` with a CLI older than the installed Core: the human
+ * output never says the code is up to date, warns once with the same upgrade
+ * pinned to the CLI release that matches the Core, and keeps the exit status;
+ * `--json` carries the same facts in `cliBehindCore`. Pasted anywhere, the
+ * printed command runs that upgrade in the same project.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {spawnSync} from 'node:child_process';
+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';
+import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
+import {
+  commandInFolder,
+  getDlxPrefix,
+  quoteCommandArgument,
+} from '../../../foundation/env/package-manager.mjs';
+
+const CLI_VERSION = JSON.parse(
+  fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf8'),
+).version;
+const [MAJOR, MINOR] = CLI_VERSION.split('.').map(Number);
+const NEWER_CORE = `${MAJOR}.${MINOR + 1}.0`;
+const NON_ASCII = /[\u0080-\uFFFF]/;
+
+let tmpDir;
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  const file = path.join(tmpDir, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, body);
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-older-cli-'));
+  write('package.json', JSON.stringify({name: 'consumer', private: true}));
+  write(
+    'node_modules/@astryxdesign/core/package.json',
+    JSON.stringify({name: '@astryxdesign/core', version: NEWER_CORE}),
+  );
+  write('src/index.ts', 'export const x = 1;\n');
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * The pinned command the CLI prints for this project. It names the folder the
+ * CLI ran in and the source directory as the CLI resolved them.
+ * @param {...string} rest the arguments after `--path <dir>`
+ */
+function pinned(...rest) {
+  const project = fs.realpathSync(tmpDir);
+  return commandInFolder(
+    project,
+    [
+      getDlxPrefix(tmpDir),
+      `@astryxdesign/cli@${NEWER_CORE}`,
+      'upgrade',
+      '--from',
+      CLI_VERSION,
+      '--path',
+      quoteCommandArgument(path.join(project, 'src')),
+      ...rest,
+    ].join(' '),
+  );
+}
+
+/**
+ * Stand-ins for the package runners: each drops its own words and the pinned
+ * package, then runs this CLI with the rest of the command.
+ */
+const RUNS_THIS_CLI = [
+  ['npx', 1],
+  ['bunx', 1],
+  ['pnpm', 2],
+  ['yarn', 2],
+]
+  .map(
+    ([name, words]) =>
+      `${name}() { shift ${words}; "$0" ${quoteCommandArgument(path.join(CLI_ROOT, 'clients', 'cli', 'bin', 'astryx.mjs'))} "$@"; }`,
+  )
+  .join('; ');
+
+describe('astryx upgrade with a CLI older than the installed Core', () => {
+  it('says it cannot finish and prints the upgrade pinned to the matching CLI', async () => {
+    const r = await runCli(['upgrade', '--from', CLI_VERSION, '--apply'], {
+      cwd: tmpDir,
+    });
+    const output = `${r.stdout}\n${r.stderr}`;
+
+    expect(r.status).toBe(0);
+    expect(output).not.toMatch(/up to date/i);
+    expect(output).not.toContain('No codemods available');
+    expect(r.stderr).toContain(
+      `This CLI (${CLI_VERSION}) is older than the installed @astryxdesign/core (${NEWER_CORE})`,
+    );
+    // The command has a line of its own, so it copies exactly.
+    expect(r.stderr).toContain(
+      `the CLI that matches your Core:\n  ${pinned('--apply')}\n`,
+    );
+    expect(r.stdout.trim().split('\n').at(-1)).toBe('Upgrade incomplete');
+    expect(output.split('\n').filter(line => NON_ASCII.test(line))).toEqual([]);
+  });
+
+  it('carries cliBehindCore in --json with the same exit status', async () => {
+    const r = await runCli(['--json', 'upgrade', '--from', CLI_VERSION], {
+      cwd: tmpDir,
+    });
+    const parsed = JSON.parse(r.stdout);
+
+    expect(r.status).toBe(0);
+    expect(parsed.type).toBe('upgrade.status');
+    expect(parsed.data.status).toBe('no_codemods');
+    expect(parsed.data.cliBehindCore).toEqual({
+      cliVersion: CLI_VERSION,
+      command: pinned(),
+    });
+  });
+
+  // Where an upgrade runs decides what it finds: the installed Core is read
+  // from that folder, and --path must stay inside it. Printed without its
+  // folder, the command exited 1 when pasted in a subfolder
+  // (ERR_PATH_TRAVERSAL) or in the folder above (ERR_VERSION_DETECT).
+  it.skipIf(process.platform === 'win32')(
+    'prints a command that upgrades the same project wherever it is pasted',
+    async () => {
+      write('src/deep/index.ts', 'export const y = 2;\n');
+      const r = await runCli(['--json', 'upgrade', '--from', CLI_VERSION], {
+        cwd: tmpDir,
+      });
+      const {command} = JSON.parse(r.stdout).data.cliBehindCore;
+
+      for (const pastedIn of [
+        path.join(tmpDir, 'src', 'deep'),
+        path.dirname(tmpDir),
+      ]) {
+        const ran = spawnSync(
+          '/bin/sh',
+          ['-c', `${RUNS_THIS_CLI}; ${command}`, process.execPath],
+          {cwd: pastedIn, encoding: 'utf8'},
+        );
+
+        expect(ran.status, ran.stderr).toBe(0);
+        expect(ran.stdout).toContain(`Installed target: ${NEWER_CORE}`);
+        expect(ran.stdout).toContain(
+          `Scanning ${path.join(fs.realpathSync(tmpDir), 'src')} `,
+        );
+      }
+    },
+    30_000,
+  );
+});

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