@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/env/cli-command.mjs

@@ -0,0 +1,152 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The command that runs the CLI for this project, when something other
+ * than the package-manager guess says what it is.
+ *
+ * `getCliInvocation` (package-manager.mjs) is the one picker every printed
+ * command goes through. It asks, in order:
+ *
+ * 1. **The integrations** — the `cliCommand` field of each loaded
+ *    integration's manifest. `Project.load` records them per project with
+ *    {@link recordDeclaredCliCommands}. One command, declared by one or more
+ *    integrations, is used. Two different commands cancel each other out: the
+ *    picker falls back to its guess, even when a host set a door, and
+ *    `astryx doctor` warns.
+ * 2. **The door** — the command a host ran this call through. A host sets it
+ *    for the duration of one call with {@link runWithCliDoor}; nothing in the
+ *    public API sets it yet, so it is empty in every plain run.
+ * 3. **The guess** — the package-manager prefix, as before.
+ *
+ * @input A host's door name; the loaded integrations of a project.
+ * @output The declared command for a directory, or the conflict.
+ * @position foundation/env — read by the picker and by `astryx doctor`.
+ */
+
+import {AsyncLocalStorage} from 'node:async_hooks';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * One integration's declared command.
+ * @typedef {object} DeclaredCliCommand
+ * @property {string} package the integration package that declared it
+ * @property {string} command its `cliCommand` value
+ */
+
+/** @type {AsyncLocalStorage<{command: string}>} */
+const doorScope = new AsyncLocalStorage();
+
+/**
+ * Run `fn` with `command` as the door printed commands start with. The slot a
+ * host fills for one call. An integration's `cliCommand` still comes first,
+ * and conflicting ones still fall back to the guess.
+ * @template T
+ * @param {string} command e.g. `astryx` for a global launcher
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function runWithCliDoor(command, fn) {
+  return doorScope.run({command}, fn);
+}
+
+/**
+ * The door of the current call, if a host set one.
+ * @returns {string | undefined}
+ */
+export function cliDoor() {
+  return doorScope.getStore()?.command;
+}
+
+/** @type {Map<string, DeclaredCliCommand[]>} */
+const declaredByProject = new Map();
+
+/**
+ * The directory a project is keyed by: the nearest one with a package.json,
+ * the same root `Project.load` resolves; otherwise the directory itself.
+ * @param {string} dir
+ * @returns {string}
+ */
+function projectKey(dir) {
+  const start = path.resolve(dir);
+  let current = start;
+  for (;;) {
+    if (fs.existsSync(path.join(current, 'package.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return start;
+    current = parent;
+  }
+}
+
+/**
+ * The commands a set of loaded integrations declares, in load order. An
+ * integration that failed to load, or was set aside for a provider conflict,
+ * contributes nothing, so it declares nothing either.
+ * @param {ReadonlyArray<{name?: string, __spec?: string, cliCommand?: string, __loadError?: string, __providerConflict?: unknown}>} integrations
+ * @returns {DeclaredCliCommand[]}
+ */
+export function declaredCliCommandsOf(integrations) {
+  /** @type {DeclaredCliCommand[]} */
+  const declared = [];
+  for (const integration of integrations) {
+    if (integration.__loadError != null) continue;
+    if (integration.__providerConflict != null) continue;
+    if (typeof integration.cliCommand !== 'string') continue;
+    declared.push({
+      package: integration.name ?? integration.__spec ?? '(unnamed)',
+      command: integration.cliCommand,
+    });
+  }
+  return declared;
+}
+
+/**
+ * Choose among declarations: one command, declared by one or more
+ * integrations, is used; different commands are a conflict.
+ * @param {DeclaredCliCommand[]} declared
+ * @returns {{command?: string, conflict: boolean, declared: DeclaredCliCommand[]}}
+ */
+export function chooseDeclaredCliCommand(declared) {
+  const commands = new Set(declared.map(entry => entry.command));
+  if (commands.size === 1) {
+    return {command: declared[0].command, conflict: false, declared};
+  }
+  return {conflict: commands.size > 1, declared};
+}
+
+/**
+ * Record the commands a project's loaded integrations declare. Called by
+ * `Project.load` each time it resolves the integration set; the latest load
+ * wins.
+ * @param {string} projectDir
+ * @param {Parameters<typeof declaredCliCommandsOf>[0]} integrations
+ * @returns {void}
+ */
+export function recordDeclaredCliCommands(projectDir, integrations) {
+  declaredByProject.set(
+    projectKey(projectDir),
+    declaredCliCommandsOf(integrations),
+  );
+}
+
+/**
+ * Whether this process has loaded the project at `targetDir`.
+ * @param {string} [targetDir=process.cwd()]
+ * @returns {boolean}
+ */
+export function hasRecordedProject(targetDir = process.cwd()) {
+  return declaredByProject.has(projectKey(targetDir));
+}
+
+/**
+ * What the integrations of the project at `targetDir` declare, as recorded by
+ * its last `Project.load` in this process; see
+ * {@link chooseDeclaredCliCommand}.
+ * @param {string} [targetDir=process.cwd()]
+ * @returns {{command?: string, conflict: boolean, declared: DeclaredCliCommand[]}}
+ */
+export function declaredCliCommand(targetDir = process.cwd()) {
+  return chooseDeclaredCliCommand(
+    declaredByProject.get(projectKey(targetDir)) ?? [],
+  );
+}

package/foundation/env/cli-command.test.mjs

@@ -0,0 +1,129 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  chooseDeclaredCliCommand,
+  cliDoor,
+  declaredCliCommand,
+  declaredCliCommandsOf,
+  hasRecordedProject,
+  recordDeclaredCliCommands,
+  runWithCliDoor,
+} from './cli-command.mjs';
+
+/** @type {string[]} */
+const dirs = [];
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) {
+    fs.rmSync(dir, {recursive: true, force: true});
+  }
+});
+
+/** A project directory with a package.json, and a folder inside it. */
+function makeProject() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-cli-command-'));
+  dirs.push(dir);
+  fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"app"}');
+  fs.mkdirSync(path.join(dir, 'src'));
+  return dir;
+}
+
+describe('runWithCliDoor', () => {
+  it('sets the door for the call, and only for it', async () => {
+    expect(cliDoor()).toBeUndefined();
+    const inside = await runWithCliDoor('astryx', async () => {
+      await Promise.resolve();
+      return cliDoor();
+    });
+    expect(inside).toBe('astryx');
+    expect(cliDoor()).toBeUndefined();
+  });
+});
+
+describe('declaredCliCommandsOf', () => {
+  it('skips integrations that failed to load or were set aside', () => {
+    expect(
+      declaredCliCommandsOf([
+        {name: '@acme/a', cliCommand: 'acme astryx'},
+        {name: '@acme/b'},
+        {name: '@acme/c', cliCommand: 'c astryx', __loadError: 'boom'},
+        {name: '@acme/d', cliCommand: 'd astryx', __providerConflict: {}},
+        {__spec: '@acme/e', cliCommand: 'acme astryx'},
+      ]),
+    ).toEqual([
+      {package: '@acme/a', command: 'acme astryx'},
+      {package: '@acme/e', command: 'acme astryx'},
+    ]);
+  });
+});
+
+describe('chooseDeclaredCliCommand', () => {
+  it('uses one command, however many packages declare it', () => {
+    const declared = [
+      {package: '@acme/a', command: 'acme astryx'},
+      {package: '@acme/b', command: 'acme astryx'},
+    ];
+    expect(chooseDeclaredCliCommand(declared)).toEqual({
+      command: 'acme astryx',
+      conflict: false,
+      declared,
+    });
+  });
+
+  it('uses neither of two different commands, and calls it a conflict', () => {
+    const result = chooseDeclaredCliCommand([
+      {package: '@acme/a', command: 'acme astryx'},
+      {package: '@acme/b', command: 'other astryx'},
+    ]);
+    expect(result.command).toBeUndefined();
+    expect(result.conflict).toBe(true);
+  });
+
+  it('has nothing to choose with no declarations', () => {
+    expect(chooseDeclaredCliCommand([])).toEqual({
+      conflict: false,
+      declared: [],
+    });
+  });
+});
+
+describe('recordDeclaredCliCommands', () => {
+  it('answers for the project and any folder inside it', () => {
+    const dir = makeProject();
+    expect(hasRecordedProject(dir)).toBe(false);
+    recordDeclaredCliCommands(dir, [
+      {name: '@acme/a', cliCommand: 'acme astryx'},
+    ]);
+    expect(hasRecordedProject(dir)).toBe(true);
+    expect(declaredCliCommand(dir).command).toBe('acme astryx');
+    expect(declaredCliCommand(path.join(dir, 'src')).command).toBe(
+      'acme astryx',
+    );
+  });
+
+  it('lets the latest load win', () => {
+    const dir = makeProject();
+    recordDeclaredCliCommands(dir, [
+      {name: '@acme/a', cliCommand: 'acme astryx'},
+    ]);
+    recordDeclaredCliCommands(dir, []);
+    expect(hasRecordedProject(dir)).toBe(true);
+    expect(declaredCliCommand(dir).command).toBeUndefined();
+  });
+
+  it('does not answer for a nested project of its own', () => {
+    const dir = makeProject();
+    const nested = path.join(dir, 'packages', 'web');
+    fs.mkdirSync(nested, {recursive: true});
+    fs.writeFileSync(path.join(nested, 'package.json'), '{"name":"web"}');
+    recordDeclaredCliCommands(dir, [
+      {name: '@acme/a', cliCommand: 'acme astryx'},
+    ]);
+    expect(hasRecordedProject(nested)).toBe(false);
+    expect(declaredCliCommand(nested).command).toBeUndefined();
+  });
+});

package/foundation/env/node-version.test.mjs

@@ -20,15 +20,27 @@ import {
 
 describe('parseNodeVersion', () => {
   it('parses a plain semver string', () => {
-    expect(parseNodeVersion('22.14.1')).toEqual({major: 22, minor: 14, patch: 1});
+    expect(parseNodeVersion('22.14.1')).toEqual({
+      major: 22,
+      minor: 14,
+      patch: 1,
+    });
   });
 
   it('strips a leading v', () => {
-    expect(parseNodeVersion('v20.10.0')).toEqual({major: 20, minor: 10, patch: 0});
+    expect(parseNodeVersion('v20.10.0')).toEqual({
+      major: 20,
+      minor: 10,
+      patch: 0,
+    });
   });
 
   it('ignores a prerelease/build suffix on the patch segment', () => {
-    expect(parseNodeVersion('16.20.2-nightly')).toEqual({major: 16, minor: 20, patch: 2});
+    expect(parseNodeVersion('16.20.2-nightly')).toEqual({
+      major: 16,
+      minor: 20,
+      patch: 2,
+    });
   });
 
   it('defaults missing segments to 0', () => {

package/foundation/env/package-manager.d.mts

@@ -130,21 +130,55 @@ export function isCliOneOff(): boolean;
  */
 export function cliBinResolves(targetDir?: string): boolean;
 /**
- * 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?: string): string;
+export function getCliInvocation(targetDir?: string, { installed }?: {
+    installed?: boolean;
+}): string;
+/**
+ * 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 guessCliInvocation(targetDir?: string): string;
 /**
  * Format a full, runnable CLI command from a subcommand string.
  *
@@ -157,6 +191,56 @@ export function getCliInvocation(targetDir?: string): string;
  * @returns {string}
  */
 export function formatCliCommand(command: string, targetDir?: string): string;
+/**
+ * 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: string, stem: string, lang?: string | null): string;
+/**
+ * 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: string, platform?: string): string;
+/**
+ * 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: string, command: string, platform?: string): string;
 /** The published CLI package name — used for one-off (uninstalled) invocations. */
 export const CLI_PACKAGE: "@astryxdesign/cli";
 /** The CLI binary name — only resolves once the CLI is installed (or run via CLI_PACKAGE). */

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

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The picker's guess when the CLI installed for the computer answers:
+ * `astryx` outside a project, and the pinned package inside one, where the
+ * global copy never answers for itself (spec AST-081 FR5).
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {guessCliInvocation} from './package-manager.mjs';
+import {
+  CLI_VERSION,
+  cleanupFixtures,
+  installCore,
+  project,
+  tempDir,
+} from '../../test-utils/release-fixtures.mjs';
+
+vi.mock('../release/choose.mjs', async importOriginal => ({
+  .../** @type {object} */ (await importOriginal()),
+  isGlobalCopy: () => true,
+}));
+
+afterEach(cleanupFixtures);
+
+describe('guessCliInvocation for the copy installed for the computer', () => {
+  it('prints the bare `astryx` command outside a project', () => {
+    const empty = tempDir('empty');
+    fs.writeFileSync(path.join(empty, 'package-lock.json'), '{}');
+    const before = process.cwd();
+    process.chdir(empty);
+    try {
+      expect(guessCliInvocation(empty)).toBe('astryx');
+    } finally {
+      process.chdir(before);
+    }
+  });
+
+  it('prints the pinned package inside a project it answers as the matched release', () => {
+    const root = project(tempDir(), {'@astryxdesign/core': CLI_VERSION});
+    installCore(root, CLI_VERSION);
+    fs.writeFileSync(path.join(root, 'package-lock.json'), '{}');
+    expect(guessCliInvocation(root)).toBe(
+      `npx @astryxdesign/cli@${CLI_VERSION}`,
+    );
+  });
+});
+
+describe('one stem per run', () => {
+  it('names the release that answered the run, whichever folder a line names', () => {
+    // The run answers outside a project; a line about a project folder whose
+    // own CLI sits beyond the read reach still gets the same stem.
+    const empty = tempDir('empty');
+    const other = project(tempDir(), {'@astryxdesign/core': CLI_VERSION});
+    installCore(other, CLI_VERSION);
+    const before = process.cwd();
+    process.chdir(empty);
+    try {
+      expect(guessCliInvocation(other)).toBe(guessCliInvocation(empty));
+    } finally {
+      process.chdir(before);
+    }
+  });
+});