@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/env/package-manager.mjs

@@ -8,11 +8,17 @@
  * the runner that launched us. Returns the correct command prefix for running
  * package binaries (e.g. 'npx astryx', 'yarn astryx', 'pnpm exec astryx'), and
  * the scoped one-off form ('npx @astryxdesign/cli') when the `astryx` bin does
- * not resolve from the project.
+ * not resolve from the project. An integration's declared `cliCommand`, then
+ * a host's door name, come first (see cli-command.mjs).
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {cliDoor, declaredCliCommand} from './cli-command.mjs';
+import {CLI_ROOT} from '../fs/paths.mjs';
+import {cliVersion, runChoice} from '../release/run-context.mjs';
+import {isGlobalCopy} from '../release/choose.mjs';
+import {isInReleaseCache} from '../release/cache.mjs';
 
 /**
  * A package manager we can install with and run binaries through.
@@ -473,25 +479,73 @@ export function cliBinResolves(targetDir = process.cwd()) {
 }
 
 /**
- * The safe, install-aware CLI invocation stem to suggest to users.
+ * The CLI invocation stem every printed command starts with. The one picker:
+ * every hint, error, Doctor fix and doc line that names a command goes through
+ * it (directly, or through {@link formatCliCommand} and
+ * {@link formatCliCommandsIn}). JSON fields that carry a command stay bare.
  *
- * - The `astryx` bin resolves from `targetDir`: `<run-prefix> astryx`
- *   (e.g. `pnpm exec astryx`).
- * - Launched one-off (npx/dlx cache), or the bin does not resolve from
- *   `targetDir` (a global install, a fresh package in a workspace):
- *   `<dlx-prefix> @astryxdesign/cli`. The bare `astryx` name would make npm
- *   fetch an unrelated registry package; the scoped package always resolves
- *   to this CLI.
+ * In order:
+ *
+ * - The `cliCommand` an integration loaded in this project declares, e.g.
+ *   `acme astryx`. When two integrations declare different commands,
+ *   neither is used, the guess below is (even when a host set a door), and
+ *   `astryx doctor` warns.
+ * - The door a host ran this call through (see cli-command.mjs). Empty in a
+ *   plain run.
+ * - Otherwise the guess below.
+ *
+ * The guess names a command that, run from `targetDir`, reaches the release
+ * that answered (spec AST-081 FR5):
+ *
+ * - The project's own CLI answered and its `astryx` bin resolves from
+ *   `targetDir`: `<run-prefix> astryx` (e.g. `pnpm exec astryx`).
+ * - Outside a project, the CLI installed for the computer (or the release it
+ *   keeps) answered: `astryx`.
+ * - Otherwise: `<dlx-prefix> @astryxdesign/cli@<answering version>`, pinned so
+ *   the package runner starts the same release. The bare `astryx` name would
+ *   make npm fetch an unrelated registry package, and the unpinned scoped
+ *   package the newest release.
+ *
+ * With `installed`, the line follows a step that installs the project's own
+ * CLI (an update notice, the hint that matches a project's CLI to its Core),
+ * so the guess is that CLI: `<run-prefix> astryx`. A declared `cliCommand`
+ * and a host's door still come first.
  *
  * @param {string} [targetDir] the project the printed command runs in;
  *   defaults to the working directory
+ * @param {{installed?: boolean}} [options]
+ * @returns {string}
+ */
+export function getCliInvocation(targetDir, {installed = false} = {}) {
+  const declared = declaredCliCommand(targetDir);
+  if (declared.command) return declared.command;
+  const guess = () =>
+    installed
+      ? `${getRunPrefix(targetDir)} ${CLI_BIN}`
+      : guessCliInvocation(targetDir);
+  if (declared.conflict) return guess();
+  return cliDoor() ?? guess();
+}
+
+/**
+ * The package-manager guess alone, without any integration's `cliCommand` or
+ * a host's door. The picker falls back to it when declared commands conflict,
+ * and Doctor names it then.
+ *
+ * @param {string} [targetDir]
  * @returns {string}
  */
-export function getCliInvocation(targetDir) {
-  if (isCliOneOff() || !cliBinResolves(targetDir)) {
-    return `${getDlxPrefix(targetDir)} ${CLI_PACKAGE}`;
+export function guessCliInvocation(targetDir) {
+  // Who answered this run decides the stem, so every command one run prints
+  // reaches the same release, whichever folder a line names.
+  const choice = runChoice(process.cwd());
+  if (choice.copy === 'project' && !isCliOneOff() && cliBinResolves(targetDir)) {
+    return `${getRunPrefix(targetDir)} ${CLI_BIN}`;
   }
-  return `${getRunPrefix(targetDir)} ${CLI_BIN}`;
+  if (!choice.inProject && (isGlobalCopy(CLI_ROOT) || isInReleaseCache(CLI_ROOT))) {
+    return CLI_BIN;
+  }
+  return `${getDlxPrefix(targetDir)} ${CLI_PACKAGE}@${cliVersion()}`;
 }
 
 /**
@@ -512,3 +566,120 @@ export function formatCliCommand(command, targetDir) {
   const stem = getCliInvocation(targetDir);
   return sub ? `${stem} ${sub}` : stem;
 }
+
+/** Code-fence languages whose lines are shell commands. */
+const SHELL_FENCES = new Set(['', 'bash', 'sh', 'shell', 'zsh', 'console']);
+
+/** Code-fence languages that hold prose, such as a prompt to paste. */
+const PROSE_FENCES = new Set(['text', 'txt', 'markdown', 'md']);
+
+/** `astryx` where a shell line starts a command: line start, `$ `, `&&`, `||`, `;`, `|`. */
+const SHELL_COMMAND = /(^\s*(?:\$\s+)?|(?:&&|\|\||;|\|)\s*)astryx(?=\s|$)/g;
+
+/** `astryx` opening an inline code span: `` `astryx docs` `` or `` `astryx` ``. */
+const INLINE_COMMAND = /`astryx(?=[\s`])/g;
+
+/**
+ * Prefix the CLI commands in one line.
+ * @param {string} line
+ * @param {string} stem
+ * @param {string | null} lang the fence the line sits in; null for prose
+ * @returns {string}
+ */
+function prefixLine(line, stem, lang) {
+  if (lang == null) return line.replace(INLINE_COMMAND, `\`${stem}`);
+  if (SHELL_FENCES.has(lang)) return line.replace(SHELL_COMMAND, `$1${stem}`);
+  if (PROSE_FENCES.has(lang)) {
+    return line
+      .replace(INLINE_COMMAND, `\`${stem}`)
+      .replace(SHELL_COMMAND, `$1${stem}`);
+  }
+  return line;
+}
+
+/**
+ * Prefix every CLI command in doc text with `stem`, the invocation from
+ * {@link getCliInvocation}.
+ *
+ * Docs, including an integration's, are written with bare `astryx ...`
+ * commands; this rewrites them when they are shown. In prose, an inline code
+ * span that starts with `astryx`. In a shell code fence (no language, `bash`,
+ * `sh`, `shell`, `zsh`, `console`), each `astryx` that starts a command. In a
+ * `text` or `markdown` fence, both. Other fences, and plain words, are left
+ * alone. JSON output keeps the authored text.
+ *
+ * @param {string} text Markdown-style doc text, or the body of one code block.
+ * @param {string} stem e.g. `pnpm exec astryx`
+ * @param {string | null} [lang] the code block's language when `text` is one
+ *   block's body; omit for Markdown, whose fences are followed
+ * @returns {string}
+ */
+export function prefixCliCommands(text, stem, lang = null) {
+  if (stem === CLI_BIN) return String(text);
+  const blockLang = lang == null ? null : lang.toLowerCase();
+  /** @type {{marker: string, lang: string} | null} */
+  let fence = null;
+  return String(text)
+    .split('\n')
+    .map(line => {
+      if (blockLang != null) return prefixLine(line, stem, blockLang);
+      const marker = /^\s*(`{3,}|~{3,})\s*([\w-]*)/.exec(line);
+      if (marker) {
+        if (fence == null) {
+          fence = {marker: marker[1], lang: marker[2].toLowerCase()};
+        } else if (marker[1].startsWith(fence.marker)) {
+          fence = null;
+        }
+        return line;
+      }
+      return prefixLine(line, stem, fence?.lang ?? null);
+    })
+    .join('\n');
+}
+
+/**
+ * Quote one argument of a printed command so the shell it is pasted into
+ * passes it on unchanged. Printed commands target a POSIX shell (sh, bash,
+ * zsh), and PowerShell on Windows; cmd.exe is not a target. A value made only
+ * of letters, digits and `@ / . _ -` (and, on Windows, a drive path's `:` and
+ * `\`) stays bare. Any other value gets single quotes, inside which both
+ * shells read `$`, backticks, `%`, `!`, spaces and double quotes literally. An
+ * embedded single quote is written `'\''` for a POSIX shell and doubled for
+ * PowerShell, which also ends a single-quoted string at the typographic
+ * quotes `‘ ’ ‚ ‛`, so those are doubled too (`Macy’s` → `'Macy’’s'`).
+ *
+ * @param {string} value
+ * @param {string} [platform] the `process.platform` the command is printed for
+ * @returns {string}
+ */
+export function quoteCommandArgument(value, platform = process.platform) {
+  const text = String(value);
+  if (platform === 'win32') {
+    if (/^[A-Za-z0-9@/._:\\-]+$/u.test(text)) return text;
+    return `'${text.replace(/['\u2018\u2019\u201A\u201B]/gu, quote => quote + quote)}'`;
+  }
+  if (/^[A-Za-z0-9@/._-]+$/u.test(text)) return text;
+  return `'${text.replace(/'/gu, `'\\''`)}'`;
+}
+
+/**
+ * A printed command that changes to `dir`, then runs `command` there, so it
+ * does the same work pasted from any folder. It runs `command` only when the
+ * change worked. For a POSIX shell: `cd <dir> && <command>`. For PowerShell
+ * on Windows: `cd -LiteralPath <dir> -ErrorAction Stop; <command>`, because
+ * `-LiteralPath` reads `[` and `]` in a folder name literally, and a failed
+ * change stops the line in Windows PowerShell 5.1, which has no `&&`, as in
+ * PowerShell 7.
+ *
+ * @param {string} dir an absolute folder
+ * @param {string} command the command to run there, its arguments already
+ *   quoted with {@link quoteCommandArgument}
+ * @param {string} [platform] the `process.platform` the command is printed for
+ * @returns {string}
+ */
+export function commandInFolder(dir, command, platform = process.platform) {
+  const folder = quoteCommandArgument(dir, platform);
+  return platform === 'win32'
+    ? `cd -LiteralPath ${folder} -ErrorAction Stop; ${command}`
+    : `cd ${folder} && ${command}`;
+}

package/foundation/env/package-manager.test.mjs

@@ -1,6 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect, afterEach, vi} from 'vitest';
+import {spawnSync} from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
@@ -11,12 +12,37 @@ import {
   isCliOneOff,
   cliBinResolves,
   getCliInvocation,
+  guessCliInvocation,
   formatCliCommand,
+  prefixCliCommands,
+  quoteCommandArgument,
+  commandInFolder,
 } from './package-manager.mjs';
+import {recordDeclaredCliCommands, runWithCliDoor} from './cli-command.mjs';
+import {CLI_VERSION} from '../../test-utils/release-fixtures.mjs';
 
 let tmpDir;
 const ORIGINAL_ARGV1 = process.argv[1];
 
+/** Prints, as JSON, the folder a command ran in and the arguments it got. */
+const PRINT_RUN =
+  'process.stdout.write(JSON.stringify({cwd: process.cwd(), argv: process.argv.slice(1)}))';
+
+/** PowerShell, when it is on the PATH: printed commands target it on Windows. */
+const PWSH = (process.env.PATH ?? '')
+  .split(path.delimiter)
+  .flatMap(dir => ['pwsh', 'pwsh.exe'].map(name => path.join(dir, name)))
+  .find(file => isFile(file));
+
+/** @param {string} file */
+function isFile(file) {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
 afterEach(() => {
   if (tmpDir) {
     fs.rmSync(tmpDir, {recursive: true, force: true});
@@ -37,8 +63,16 @@ function linkCliBin(dir, name = 'astryx') {
   const binDir = path.join(dir, 'node_modules', '.bin');
   fs.mkdirSync(binDir, {recursive: true});
   fs.writeFileSync(path.join(binDir, name), '');
+  // The installed package the bin belongs to: this copy, so the project's own
+  // CLI is the one answering (spec AST-081 FR5's run-prefix case).
+  const pkg = path.join(dir, 'node_modules', '@astryxdesign', 'cli');
+  fs.mkdirSync(path.dirname(pkg), {recursive: true});
+  if (!fs.existsSync(pkg)) fs.symlinkSync(THIS_CLI, pkg, 'dir');
 }
 
+/** This CLI package's folder. */
+const THIS_CLI = path.resolve(import.meta.dirname, '..', '..');
+
 /** The header a classic Yarn (1.x) lockfile starts with. */
 const YARN_V1_LOCK =
   '# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.\n# yarn lockfile v1\n\n';
@@ -48,7 +82,8 @@ const YARN_BERRY_LOCK =
   '# This file is generated by running "yarn install" inside your project.\n# Manual changes might be lost - proceed with caution!\n\n__metadata:\n  version: 8\n';
 
 /** An installed CLI's entry, outside any runner cache (a global or workspace install). */
-const INSTALLED_ENTRY = '/usr/local/lib/node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs';
+const INSTALLED_ENTRY =
+  '/usr/local/lib/node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs';
 
 describe('detectPackageManager', () => {
   it('detects yarn from yarn.lock', () => {
@@ -132,7 +167,10 @@ describe('detectPackageManager', () => {
     const dir = makeTmpDir();
     fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
     fs.writeFileSync(path.join(dir, 'yarn.lock'), '');
-    fs.writeFileSync(path.join(dir, '.yarnrc.yml'), 'nodeLinker: node-modules\n');
+    fs.writeFileSync(
+      path.join(dir, '.yarnrc.yml'),
+      'nodeLinker: node-modules\n',
+    );
     expect(detectPackageManager(dir)).toBe('yarn');
   });
 
@@ -425,12 +463,14 @@ describe('isCliOneOff', () => {
   });
 
   it('detects a pnpm dlx cache entry', () => {
-    process.argv[1] = '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    process.argv[1] =
+      '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
     expect(isCliOneOff()).toBe(true);
   });
 
   it('detects a bunx cache entry', () => {
-    process.argv[1] = '/home/u/.bun/install/cache/@astryxdesign/cli/bin/astryx.mjs';
+    process.argv[1] =
+      '/home/u/.bun/install/cache/@astryxdesign/cli/bin/astryx.mjs';
     expect(isCliOneOff()).toBe(true);
   });
 
@@ -506,11 +546,11 @@ describe('getCliInvocation', () => {
   // fresh package), the CLI used to print `npx astryx` for a project where that
   // bin does not resolve, so following the hint fetched someone else's package.
   it.each([
-    ['package-lock.json', '{}', 'npx @astryxdesign/cli'],
-    ['pnpm-lock.yaml', '', 'pnpm dlx @astryxdesign/cli'],
-    ['yarn.lock', YARN_BERRY_LOCK, 'yarn dlx @astryxdesign/cli'],
-    ['yarn.lock', YARN_V1_LOCK, 'npx @astryxdesign/cli'],
-    ['bun.lockb', '', 'bunx @astryxdesign/cli'],
+    ['package-lock.json', '{}', `npx @astryxdesign/cli@${CLI_VERSION}`],
+    ['pnpm-lock.yaml', '', `pnpm dlx @astryxdesign/cli@${CLI_VERSION}`],
+    ['yarn.lock', YARN_BERRY_LOCK, `yarn dlx @astryxdesign/cli@${CLI_VERSION}`],
+    ['yarn.lock', YARN_V1_LOCK, `npx @astryxdesign/cli@${CLI_VERSION}`],
+    ['bun.lockb', '', `bunx @astryxdesign/cli@${CLI_VERSION}`],
   ])(
     'prints the scoped package for a project with no local CLI (%s), launched from an installed path',
     (lockfile, contents, expected) => {
@@ -527,21 +567,24 @@ describe('getCliInvocation', () => {
     const dir = makeTmpDir();
     delete process.env.npm_config_user_agent;
     fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"fresh"}');
-    expect(getCliInvocation(dir)).toBe('npx @astryxdesign/cli');
+    expect(getCliInvocation(dir)).toBe(`npx @astryxdesign/cli@${CLI_VERSION}`);
   });
 
   it('uses the dlx runner + scoped package when run one-off', () => {
     process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
     const dir = makeTmpDir();
     delete process.env.npm_config_user_agent;
-    expect(getCliInvocation(dir)).toBe('npx @astryxdesign/cli');
+    expect(getCliInvocation(dir)).toBe(`npx @astryxdesign/cli@${CLI_VERSION}`);
   });
 
   it('pairs the dlx runner with the scoped package for pnpm one-off', () => {
-    process.argv[1] = '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    process.argv[1] =
+      '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
     const dir = makeTmpDir();
     fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
-    expect(getCliInvocation(dir)).toBe('pnpm dlx @astryxdesign/cli');
+    expect(getCliInvocation(dir)).toBe(
+      `pnpm dlx @astryxdesign/cli@${CLI_VERSION}`,
+    );
   });
 });
 
@@ -551,7 +594,9 @@ describe('formatCliCommand', () => {
     const dir = makeTmpDir();
     fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
     linkCliBin(dir);
-    expect(formatCliCommand('astryx component Button', dir)).toBe('pnpm exec astryx component Button');
+    expect(formatCliCommand('astryx component Button', dir)).toBe(
+      'pnpm exec astryx component Button',
+    );
   });
 
   it('accepts a bare subcommand (no leading astryx)', () => {
@@ -566,6 +611,287 @@ describe('formatCliCommand', () => {
     process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
     const dir = makeTmpDir();
     fs.writeFileSync(path.join(dir, 'package-lock.json'), '{}');
-    expect(formatCliCommand('astryx component Button', dir)).toBe('npx @astryxdesign/cli component Button');
+    expect(formatCliCommand('astryx component Button', dir)).toBe(
+      `npx @astryxdesign/cli@${CLI_VERSION} component Button`,
+    );
+  });
+});
+
+describe('the picker: declared cliCommand, then the door, then the guess', () => {
+  /** A pnpm project with the CLI installed: the guess is `pnpm exec astryx`. */
+  function pnpmProject() {
+    process.argv[1] = INSTALLED_ENTRY;
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"app"}');
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    linkCliBin(dir);
+    return dir;
+  }
+
+  it('guesses when nothing is declared', () => {
+    const dir = pnpmProject();
+    recordDeclaredCliCommands(dir, [{name: '@acme/a'}]);
+    expect(getCliInvocation(dir)).toBe('pnpm exec astryx');
+  });
+
+  it("uses an integration's cliCommand over the guess", () => {
+    const dir = pnpmProject();
+    recordDeclaredCliCommands(dir, [
+      {name: '@acme/a', cliCommand: 'acme astryx'},
+      {name: '@acme/b', cliCommand: 'acme astryx'},
+    ]);
+    expect(getCliInvocation(dir)).toBe('acme astryx');
+    expect(formatCliCommand('astryx docs tokens', dir)).toBe(
+      'acme astryx docs tokens',
+    );
+    expect(guessCliInvocation(dir)).toBe('pnpm exec astryx');
+  });
+
+  it('falls back to the guess when integrations declare different commands', () => {
+    const dir = pnpmProject();
+    recordDeclaredCliCommands(dir, [
+      {name: '@acme/a', cliCommand: 'acme astryx'},
+      {name: '@acme/b', cliCommand: 'other astryx'},
+    ]);
+    expect(getCliInvocation(dir)).toBe('pnpm exec astryx');
+  });
+
+  it("puts a declared command ahead of a host's door", () => {
+    const dir = pnpmProject();
+    recordDeclaredCliCommands(dir, [
+      {name: '@acme/a', cliCommand: 'acme astryx'},
+    ]);
+    expect(runWithCliDoor('astryx', () => getCliInvocation(dir))).toBe(
+      'acme astryx',
+    );
+  });
+
+  it("uses a host's door when nothing is declared", () => {
+    const dir = pnpmProject();
+    recordDeclaredCliCommands(dir, []);
+    expect(runWithCliDoor('astryx', () => getCliInvocation(dir))).toBe(
+      'astryx',
+    );
+  });
+
+  it('guesses on a conflict even when a host set a door', () => {
+    const dir = pnpmProject();
+    recordDeclaredCliCommands(dir, [
+      {name: '@acme/a', cliCommand: 'acme astryx'},
+      {name: '@acme/b', cliCommand: 'other astryx'},
+    ]);
+    expect(runWithCliDoor('astryx', () => getCliInvocation(dir))).toBe(
+      'pnpm exec astryx',
+    );
+  });
+});
+
+describe('prefixCliCommands', () => {
+  /** @param {string} text @param {string | null} [lang] */
+  const shown = (text, lang) => prefixCliCommands(text, 'acme astryx', lang);
+
+  it('prefixes inline code spans that run the CLI', () => {
+    expect(
+      shown('Run `astryx docs theme`, then `astryx`. Not `astryx.config.ts`.'),
+    ).toBe(
+      'Run `acme astryx docs theme`, then `acme astryx`. Not `astryx.config.ts`.',
+    );
+  });
+
+  it('prefixes commands in shell fences and leaves code fences alone', () => {
+    const text = [
+      '```bash',
+      '# astryx in a comment stays',
+      'astryx doctor && astryx integration verify',
+      '$ astryx docs',
+      'npm install @astryxdesign/cli',
+      '```',
+      '```tsx',
+      'astryx docs',
+      '```',
+    ].join('\n');
+    expect(shown(text).split('\n')).toEqual([
+      '```bash',
+      '# astryx in a comment stays',
+      'acme astryx doctor && acme astryx integration verify',
+      '$ acme astryx docs',
+      'npm install @astryxdesign/cli',
+      '```',
+      '```tsx',
+      'astryx docs',
+      '```',
+    ]);
+  });
+
+  it("follows one code block's language", () => {
+    expect(shown('astryx docs', 'bash')).toBe('acme astryx docs');
+    expect(shown('1. Read `astryx docs cli`.', 'text')).toBe(
+      '1. Read `acme astryx docs cli`.',
+    );
+    expect(shown("const run = 'astryx docs';", 'ts')).toBe(
+      "const run = 'astryx docs';",
+    );
+  });
+
+  it('leaves plain prose alone', () => {
+    expect(shown('Astryx and astryx themes')).toBe('Astryx and astryx themes');
+  });
+
+  it('changes nothing when the stem is the bare bin', () => {
+    expect(prefixCliCommands('`astryx docs`', 'astryx')).toBe('`astryx docs`');
+  });
+});
+
+describe('quoteCommandArgument', () => {
+  it('leaves a plain value bare', () => {
+    for (const platform of ['linux', 'darwin', 'win32']) {
+      expect(quoteCommandArgument('0.7.1', platform)).toBe('0.7.1');
+      expect(quoteCommandArgument('@acme/widgets', platform)).toBe(
+        '@acme/widgets',
+      );
+      expect(quoteCommandArgument('/home/me/app/src', platform)).toBe(
+        '/home/me/app/src',
+      );
+    }
+  });
+
+  it('single-quotes for a POSIX shell, so $, backticks and double quotes stay literal', () => {
+    expect(quoteCommandArgument('/tmp/my app/src', 'linux')).toBe(
+      "'/tmp/my app/src'",
+    );
+    expect(quoteCommandArgument('/tmp/cost $5/src', 'darwin')).toBe(
+      "'/tmp/cost $5/src'",
+    );
+    expect(quoteCommandArgument('a`id`"b"!', 'linux')).toBe('\'a`id`"b"!\'');
+    expect(quoteCommandArgument("it's", 'linux')).toBe("'it'\\''s'");
+    expect(quoteCommandArgument('C:\\app', 'linux')).toBe("'C:\\app'");
+    expect(quoteCommandArgument('', 'linux')).toBe("''");
+  });
+
+  it('keeps a Windows drive path bare', () => {
+    expect(quoteCommandArgument('C:\\Users\\me\\app\\src', 'win32')).toBe(
+      'C:\\Users\\me\\app\\src',
+    );
+  });
+
+  // Windows output targets PowerShell, not cmd.exe: PowerShell reads a
+  // single-quoted value literally, `$`, backticks, `%` and `!` included.
+  it('single-quotes for PowerShell on Windows, doubling an embedded quote', () => {
+    expect(quoteCommandArgument('C:\\Users\\Jo Smith\\app\\src', 'win32')).toBe(
+      "'C:\\Users\\Jo Smith\\app\\src'",
+    );
+    expect(quoteCommandArgument('C:\\cost $5 %x% !y\\src', 'win32')).toBe(
+      "'C:\\cost $5 %x% !y\\src'",
+    );
+    expect(quoteCommandArgument('C:\\it\'s `x` "q"', 'win32')).toBe(
+      "'C:\\it''s `x` \"q\"'",
+    );
+    // PowerShell also ends a single-quoted string at ‘ ’ ‚ and ‛.
+    expect(
+      quoteCommandArgument('C:\\Users\\jo\\OneDrive - Macy’s\\app', 'win32'),
+    ).toBe("'C:\\Users\\jo\\OneDrive - Macy’’s\\app'");
+    expect(quoteCommandArgument('‘a’ ‚b‛', 'win32')).toBe("'‘‘a’’ ‚‚b‛‛'");
+    // A POSIX shell reads them literally inside single quotes.
+    expect(quoteCommandArgument('/home/jo/Macy’s app', 'linux')).toBe(
+      "'/home/jo/Macy’s app'",
+    );
+  });
+});
+
+describe('commandInFolder', () => {
+  it('enters the folder, then runs the command only if that worked, in a POSIX shell', () => {
+    expect(commandInFolder('/tmp/my app', 'npx x', 'linux')).toBe(
+      "cd '/tmp/my app' && npx x",
+    );
+    expect(commandInFolder('/srv/app', 'npx x', 'darwin')).toBe(
+      'cd /srv/app && npx x',
+    );
+  });
+
+  it('enters the folder literally and stops if it cannot, in PowerShell', () => {
+    expect(commandInFolder('C:\\a[1] b', 'npx x', 'win32')).toBe(
+      "cd -LiteralPath 'C:\\a[1] b' -ErrorAction Stop; npx x",
+    );
+  });
+
+  it.skipIf(process.platform === 'win32')(
+    'runs in the folder with every argument unchanged, pasted into /bin/sh elsewhere',
+    () => {
+      const root = makeTmpDir();
+      const project = path.join(root, 'it\'s Macy’s ‘q’ $5 %x% !y `z` "q" [1]');
+      fs.mkdirSync(project);
+      const args = [path.join(project, 'src'), 'a$b c', "it's", '@scope/pkg@1'];
+      const command = commandInFolder(
+        project,
+        ['npx', ...args.map(arg => quoteCommandArgument(arg, 'linux'))].join(
+          ' ',
+        ),
+        'linux',
+      );
+      const ran = spawnSync(
+        '/bin/sh',
+        [
+          '-c',
+          `npx() { "$0" -e '${PRINT_RUN}' -- "$@"; }; ${command}`,
+          process.execPath,
+        ],
+        {cwd: root, encoding: 'utf8'},
+      );
+
+      expect(ran.status, ran.stderr).toBe(0);
+      expect(JSON.parse(ran.stdout)).toEqual({
+        cwd: fs.realpathSync(project),
+        argv: args,
+      });
+    },
+  );
+
+  describe.runIf(PWSH)('in PowerShell, where it is installed', () => {
+    it('runs in the folder with every argument unchanged', () => {
+      const root = makeTmpDir();
+      const project = path.join(root, 'it\'s Macy’s ‘q’ $5 %x% !y `z` "q" [1]');
+      fs.mkdirSync(project);
+      const args = [path.join(project, 'src'), 'a$b c', "it's", '@scope/pkg@1'];
+      const command = commandInFolder(
+        project,
+        ['npx', ...args.map(arg => quoteCommandArgument(arg, 'win32'))].join(
+          ' ',
+        ),
+        'win32',
+      );
+      const npx = `function npx { & ${quoteCommandArgument(process.execPath, 'win32')} -e '${PRINT_RUN}' -- @args }`;
+      const ran = spawnSync(
+        /** @type {string} */ (PWSH),
+        ['-NoProfile', '-NonInteractive', '-Command', `${npx}; ${command}`],
+        {cwd: root, encoding: 'utf8'},
+      );
+
+      expect(ran.status, ran.stderr).toBe(0);
+      expect(JSON.parse(ran.stdout)).toEqual({
+        cwd: fs.realpathSync(project),
+        argv: args,
+      });
+    });
+
+    it('stops when the folder cannot be entered', () => {
+      const root = makeTmpDir();
+      const command = commandInFolder(
+        path.join(root, 'missing'),
+        'npx',
+        'win32',
+      );
+      const ran = spawnSync(
+        /** @type {string} */ (PWSH),
+        [
+          '-NoProfile',
+          '-NonInteractive',
+          '-Command',
+          `function npx { 'RAN' }; ${command}`,
+        ],
+        {cwd: root, encoding: 'utf8'},
+      );
+
+      expect(ran.stdout).not.toContain('RAN');
+    });
   });
 });

package/foundation/env/project-scope.d.mts

@@ -0,0 +1,9 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * True when `cwd` is outside any project.
+ * @param {string} [cwd]
+ * @returns {boolean}
+ */
+export function isOutsideProject(cwd?: string): boolean;