@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/foundation/env/project-scope.mjs

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Whether a folder is outside a project (spec AST-081 FR3).
+ *
+ * A folder is inside a project when the CLI finds a Core or a CLI installed
+ * there or above it, or a package.json above it that declares either one; the
+ * release choice already worked that out (foundation/release/run-context.mjs).
+ * Outside a project, output never gives advice that works only inside one, such
+ * as the setup reminder, the getting-started steps, or a step that adds a theme
+ * to an app; each surface that prints such a step asks here first.
+ *
+ * @input  a folder
+ * @output whether it is outside a project
+ * @position foundation/env — read by the setup reminder, init, doctor, upgrade,
+ *   and the theme, search, discover, and integration-check surfaces.
+ */
+
+import {runChoice} from '../release/run-context.mjs';
+
+/**
+ * True when `cwd` is outside any project.
+ * @param {string} [cwd]
+ * @returns {boolean}
+ */
+export function isOutsideProject(cwd = process.cwd()) {
+  try {
+    return !runChoice(cwd).inProject;
+  } catch {
+    // A folder the release choice cannot read keeps its in-project output.
+    return false;
+  }
+}

package/foundation/env/search-path.d.mts

@@ -0,0 +1,42 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The Astryx CLI package an executable starts, or null.
+ * @param {string} file
+ * @returns {string | null}
+ */
+export function astryxCliRootOf(file: string): string | null;
+/**
+ * Every `astryx` command on the search path, in the order a shell tries
+ * them. The first row is the one that runs.
+ * @param {{searchPath?: string, platform?: NodeJS.Platform}} [options]
+ * @returns {SearchPathCommand[]}
+ */
+export function astryxCommandsOnSearchPath({ searchPath, platform, }?: {
+    searchPath?: string;
+    platform?: NodeJS.Platform;
+}): SearchPathCommand[];
+export type SearchPathCommand = {
+    /**
+     * the command as the shell finds it
+     */
+    file: string;
+    /**
+     * whether it starts the Astryx CLI
+     */
+    astryx: boolean;
+    /**
+     * the CLI package it starts, when known
+     */
+    cliRoot: string | null;
+    /**
+     * that package's version, when known
+     */
+    version: string | null;
+    /**
+     * whether that release hands a project's
+     * run to the project's release (spec AST-081 FR9); `null` when unknown
+     */
+    handsOff: boolean | null;
+};

package/foundation/env/search-path.mjs

@@ -0,0 +1,205 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The `astryx` commands on the computer's search path (spec AST-081
+ * FR10, FR11): which program each one starts, in the order a shell tries
+ * them, so `doctor`, `init --user`, and the update notices can tell the Astryx CLI
+ * apart from another program and a release that predates the hand-off from
+ * one that hands a project's run to the project's release.
+ *
+ * A command belongs to the Astryx CLI when its real file sits in the CLI
+ * package (npm and Bun link it), or when it is a package manager's small shim
+ * script that starts the CLI package's bin (npm on Windows, pnpm, Yarn); the
+ * package folder is read from the shim's text.
+ *
+ * @input  the search path and, on Windows, its executable names
+ * @output one row per `astryx` command found
+ * @position packages/cli/foundation/env — read by doctor, init --user, and
+ *   the update notices.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** The CLI package whose bin the `astryx` command starts. */
+const CLI_PACKAGE = '@astryxdesign/cli';
+
+/** The bare command name. */
+const COMMAND = 'astryx';
+
+/** Shims are small; anything larger is a program, not a shim. */
+const MAX_SHIM_BYTES = 64 * 1024;
+
+/**
+ * A CLI package folder named in a shim's text, with the shim's own folder
+ * written as `$basedir` (sh), `%~dp0` or `%dp0%` (cmd), or `$PSScriptRoot`
+ * (PowerShell).
+ */
+const SHIM_PACKAGE =
+  /((?:\$basedir(?:_abs|_win)?|%~dp0|%dp0%|\$PSScriptRoot)?[^"'\s:;$%]*node_modules[\\/]@astryxdesign[\\/]cli)(?=[\\/"'])/gu;
+
+/** The shim folder written in a shim's text, in each shell's spelling. */
+const SHIM_BASE =
+  /^(?:\$basedir(?:_abs|_win)?|%~dp0|%dp0%|\$PSScriptRoot)[\\/]?/u;
+
+/**
+ * The absolute target some package managers record in a shim's comment
+ * (`# cmd-shim-target=<file>`).
+ */
+const SHIM_TARGET_LINE = /^\s*(?:#|@?rem|::)\s*cmd-shim-target=(.+?)\s*$/imu;
+
+/**
+ * @typedef {object} SearchPathCommand
+ * @property {string} file the command as the shell finds it
+ * @property {boolean} astryx whether it starts the Astryx CLI
+ * @property {string | null} cliRoot the CLI package it starts, when known
+ * @property {string | null} version that package's version, when known
+ * @property {boolean | null} handsOff whether that release hands a project's
+ *   run to the project's release (spec AST-081 FR9); `null` when unknown
+ */
+
+/**
+ * The CLI package's version, when `dir` is the Astryx CLI package.
+ * @param {string} dir
+ * @returns {string | null}
+ */
+function cliVersionAt(dir) {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(dir, 'package.json'), 'utf8'),
+    );
+    return pkg?.name === CLI_PACKAGE ? String(pkg.version ?? '') : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Releases that hand off carry the release-choice module.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function handsOffAt(dir) {
+  return fs.existsSync(path.join(dir, 'foundation', 'release', 'choose.mjs'));
+}
+
+/**
+ * The Astryx CLI package an executable starts, or null.
+ * @param {string} file
+ * @returns {string | null}
+ */
+export function astryxCliRootOf(file) {
+  let real;
+  try {
+    real = fs.realpathSync(file);
+  } catch {
+    return null;
+  }
+  for (let dir = path.dirname(real); ;) {
+    if (cliVersionAt(dir) !== null) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  let text;
+  try {
+    if (fs.statSync(real).size > MAX_SHIM_BYTES) return null;
+    text = fs.readFileSync(real, 'utf8');
+  } catch {
+    return null;
+  }
+  const base = path.dirname(file);
+  const target = SHIM_TARGET_LINE.exec(text)?.[1];
+  if (target && path.isAbsolute(target)) {
+    for (let dir = path.dirname(target); ;) {
+      if (cliVersionAt(dir) !== null) return dir;
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  for (const match of text.matchAll(SHIM_PACKAGE)) {
+    const named = match[1]
+      .replace(SHIM_BASE, `${base}${path.sep}`)
+      .replace(/[\\/]/gu, path.sep);
+    const dir = path.resolve(base, named);
+    if (cliVersionAt(dir) !== null) return dir;
+  }
+  return null;
+}
+
+/**
+ * Whether a small script names the CLI package's files, even when that
+ * package cannot be read from here.
+ * @param {string} file
+ * @returns {boolean}
+ */
+function namesCliPackage(file) {
+  try {
+    const real = fs.realpathSync(file);
+    if (fs.statSync(real).size > MAX_SHIM_BYTES) return false;
+    return /node_modules[\\/]@astryxdesign[\\/]cli[\\/]/u.test(
+      fs.readFileSync(real, 'utf8'),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every `astryx` command on the search path, in the order a shell tries
+ * them. The first row is the one that runs.
+ * @param {{searchPath?: string, platform?: NodeJS.Platform}} [options]
+ * @returns {SearchPathCommand[]}
+ */
+export function astryxCommandsOnSearchPath({
+  searchPath = process.env.PATH ?? process.env.Path ?? '',
+  platform = process.platform,
+} = {}) {
+  const windows = platform === 'win32';
+  const names = windows
+    ? ['astryx.cmd', 'astryx.exe', 'astryx.ps1', 'astryx']
+    : [COMMAND];
+  /** @type {SearchPathCommand[]} */
+  const rows = [];
+  const seen = new Set();
+  for (const dir of searchPath.split(windows ? ';' : path.delimiter)) {
+    if (!dir) continue;
+    for (const name of names) {
+      const file = path.join(dir, name);
+      let stat;
+      try {
+        stat = fs.statSync(file);
+      } catch {
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      if (!windows) {
+        try {
+          fs.accessSync(file, fs.constants.X_OK);
+        } catch {
+          continue;
+        }
+      }
+      let key = file;
+      try {
+        key = fs.realpathSync(file);
+      } catch {
+        // Keep the path as found.
+      }
+      if (seen.has(key)) break;
+      seen.add(key);
+      const cliRoot = astryxCliRootOf(file);
+      rows.push({
+        file,
+        astryx: cliRoot !== null || namesCliPackage(file),
+        cliRoot,
+        version: cliRoot ? cliVersionAt(cliRoot) : null,
+        handsOff: cliRoot ? handsOffAt(cliRoot) : null,
+      });
+      // One command per folder: the shell runs the first name it finds.
+      break;
+    }
+  }
+  return rows;
+}

package/foundation/env/search-path.test.mjs

@@ -0,0 +1,122 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Reading the `astryx` commands on the search path (spec AST-081
+ * FR11): links, and each package manager's shim, down to the CLI package and
+ * its version.
+ */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {astryxCommandsOnSearchPath, astryxCliRootOf} from './search-path.mjs';
+import {
+  cleanupFixtures,
+  tempDir,
+  writeJson,
+} from '../../test-utils/release-fixtures.mjs';
+
+afterEach(cleanupFixtures);
+
+/**
+ * A CLI package at `dir`, with or without the hand-off.
+ * @param {string} dir
+ * @param {string} version
+ * @param {boolean} [handsOff]
+ */
+function cliPackage(dir, version, handsOff = false) {
+  writeJson(path.join(dir, 'package.json'), {
+    name: '@astryxdesign/cli',
+    version,
+  });
+  if (handsOff) {
+    fs.mkdirSync(path.join(dir, 'foundation', 'release'), {recursive: true});
+    fs.writeFileSync(path.join(dir, 'foundation', 'release', 'choose.mjs'), '');
+  }
+  return dir;
+}
+
+/**
+ * An executable shim at `file` with `text`.
+ * @param {string} file
+ * @param {string} text
+ */
+function shim(file, text) {
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, text);
+  fs.chmodSync(file, 0o755);
+  return file;
+}
+
+describe.skipIf(process.platform === 'win32')('astryxCliRootOf', () => {
+  it('reads a pnpm 10 shim ($basedir)', () => {
+    const home = tempDir('pnpm');
+    const pkg = cliPackage(
+      path.join(home, 'global', '5', 'node_modules', '@astryxdesign', 'cli'),
+      '0.6.8',
+    );
+    const bin = shim(
+      path.join(home, 'astryx'),
+      '#!/bin/sh\nbasedir=$(dirname "$0")\nexec node "$basedir/global/5/node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs" "$@"\n',
+    );
+    expect(astryxCliRootOf(bin)).toBe(pkg);
+  });
+
+  it('reads a pnpm 12 shim ($basedir_abs, a folder above the shim)', () => {
+    const home = tempDir('pnpm12');
+    const pkg = cliPackage(
+      path.join(
+        home,
+        'global',
+        'v11',
+        '3f2a',
+        'node_modules',
+        '@astryxdesign',
+        'cli',
+      ),
+      '0.6.8',
+    );
+    const bin = shim(
+      path.join(home, 'bin', 'astryx'),
+      [
+        '#!/bin/sh',
+        'basedir=$(dirname "$(echo "$0" | sed -e \'s,\\\\,/,g\')")',
+        'basedir_abs=$(cd "$basedir" && pwd)',
+        'exec node "$basedir_abs/../global/v11/3f2a/node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs" "$@"',
+        '',
+      ].join('\n'),
+    );
+    expect(astryxCliRootOf(bin)).toBe(pkg);
+    const [row] = astryxCommandsOnSearchPath({
+      searchPath: path.dirname(bin),
+      platform: 'linux',
+    });
+    expect(row).toEqual({
+      file: bin,
+      astryx: true,
+      cliRoot: pkg,
+      version: '0.6.8',
+      handsOff: false,
+    });
+  });
+
+  it('reads a cmd-shim-target comment with an absolute target', () => {
+    const elsewhere = tempDir('target');
+    const pkg = cliPackage(
+      path.join(elsewhere, 'node_modules', '@astryxdesign', 'cli'),
+      '0.8.0',
+      true,
+    );
+    const bin = shim(
+      path.join(tempDir('bin'), 'astryx'),
+      `#!/bin/sh\n# cmd-shim-target=${path.join(pkg, 'clients', 'cli', 'bin', 'astryx.mjs')}\nexec node "$TARGET" "$@"\n`,
+    );
+    expect(astryxCliRootOf(bin)).toBe(pkg);
+    expect(
+      astryxCommandsOnSearchPath({
+        searchPath: path.dirname(bin),
+        platform: 'linux',
+      })[0],
+    ).toMatchObject({version: '0.8.0', handsOff: true});
+  });
+});

package/foundation/env/user-dirs.d.mts

@@ -0,0 +1,39 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * An environment folder setting, when it names an absolute path.
+ * @param {string | undefined} value
+ * @returns {string | null}
+ */
+export function absoluteDirSetting(value: string | undefined): string | null;
+/**
+ * @typedef {object} UserDirOptions
+ * @property {string} [home] the home folder; defaults to the current user's
+ * @property {NodeJS.Platform} [platform]
+ * @property {Record<string, string | undefined>} [env]
+ */
+/**
+ * The CLI's per-user cache folder: `~/.cache/astryx` on Linux (or
+ * `$XDG_CACHE_HOME/astryx`), `~/Library/Caches/astryx` on macOS, and
+ * `%LOCALAPPDATA%\astryx\Cache` on Windows.
+ * @param {UserDirOptions} [options]
+ * @returns {string}
+ */
+export function userCacheDir({ home, platform, env, }?: UserDirOptions): string;
+/**
+ * The CLI's per-user configuration folder: `~/.config/astryx` on Linux (or
+ * `$XDG_CONFIG_HOME/astryx`), `~/Library/Application Support/astryx` on
+ * macOS, and `%APPDATA%\astryx` on Windows.
+ * @param {UserDirOptions} [options]
+ * @returns {string}
+ */
+export function userConfigDir({ home, platform, env, }?: UserDirOptions): string;
+export type UserDirOptions = {
+    /**
+     * the home folder; defaults to the current user's
+     */
+    home?: string | undefined;
+    platform?: NodeJS.Platform | undefined;
+    env?: Record<string, string | undefined> | undefined;
+};

package/foundation/env/user-dirs.mjs

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The per-user folders the CLI may write to (spec AST-081 FR7): the
+ * platform's cache directory and its configuration directory, each with an
+ * `astryx` folder of its own.
+ *
+ * A folder named by the platform's own environment setting
+ * (`XDG_CACHE_HOME`, `XDG_CONFIG_HOME`, `LOCALAPPDATA`, `APPDATA`) is used
+ * only when it is an absolute path; a relative one is ignored, as the XDG
+ * base directory rules require, so a run never writes into the folder it
+ * starts in.
+ *
+ * @input  the home folder, the platform, and those standard settings
+ * @output absolute folder paths
+ * @position packages/cli/foundation/env
+ */
+
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+/**
+ * An environment folder setting, when it names an absolute path.
+ * @param {string | undefined} value
+ * @returns {string | null}
+ */
+export function absoluteDirSetting(value) {
+  return typeof value === 'string' && value !== '' && path.isAbsolute(value)
+    ? value
+    : null;
+}
+
+/**
+ * @typedef {object} UserDirOptions
+ * @property {string} [home] the home folder; defaults to the current user's
+ * @property {NodeJS.Platform} [platform]
+ * @property {Record<string, string | undefined>} [env]
+ */
+
+/**
+ * The CLI's per-user cache folder: `~/.cache/astryx` on Linux (or
+ * `$XDG_CACHE_HOME/astryx`), `~/Library/Caches/astryx` on macOS, and
+ * `%LOCALAPPDATA%\astryx\Cache` on Windows.
+ * @param {UserDirOptions} [options]
+ * @returns {string}
+ */
+export function userCacheDir({
+  home = os.homedir(),
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  const join = platform === 'win32' ? path.win32.join : path.join;
+  if (platform === 'win32') {
+    return join(
+      absoluteDirSetting(env.LOCALAPPDATA) ?? join(home, 'AppData', 'Local'),
+      'astryx',
+      'Cache',
+    );
+  }
+  if (platform === 'darwin') return join(home, 'Library', 'Caches', 'astryx');
+  return join(
+    absoluteDirSetting(env.XDG_CACHE_HOME) ?? join(home, '.cache'),
+    'astryx',
+  );
+}
+
+/**
+ * The CLI's per-user configuration folder: `~/.config/astryx` on Linux (or
+ * `$XDG_CONFIG_HOME/astryx`), `~/Library/Application Support/astryx` on
+ * macOS, and `%APPDATA%\astryx` on Windows.
+ * @param {UserDirOptions} [options]
+ * @returns {string}
+ */
+export function userConfigDir({
+  home = os.homedir(),
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  const join = platform === 'win32' ? path.win32.join : path.join;
+  if (platform === 'win32') {
+    return join(
+      absoluteDirSetting(env.APPDATA) ?? join(home, 'AppData', 'Roaming'),
+      'astryx',
+    );
+  }
+  if (platform === 'darwin') {
+    return join(home, 'Library', 'Application Support', 'astryx');
+  }
+  return join(
+    absoluteDirSetting(env.XDG_CONFIG_HOME) ?? join(home, '.config'),
+    'astryx',
+  );
+}

package/foundation/env/user-dirs.test.mjs

@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import * as path from 'node:path';
+import {describe, expect, it} from 'vitest';
+import {absoluteDirSetting, userCacheDir, userConfigDir} from './user-dirs.mjs';
+
+const home = path.join(path.sep, 'home', 'ada');
+
+describe('per-user folders (spec AST-081 FR7)', () => {
+  it('uses the platform defaults', () => {
+    expect(userCacheDir({home, platform: 'linux', env: {}})).toBe(
+      path.join(home, '.cache', 'astryx'),
+    );
+    expect(userConfigDir({home, platform: 'linux', env: {}})).toBe(
+      path.join(home, '.config', 'astryx'),
+    );
+    expect(userCacheDir({home, platform: 'darwin', env: {}})).toBe(
+      path.join(home, 'Library', 'Caches', 'astryx'),
+    );
+    expect(userConfigDir({home, platform: 'darwin', env: {}})).toBe(
+      path.join(home, 'Library', 'Application Support', 'astryx'),
+    );
+  });
+
+  it('uses an absolute XDG setting and ignores a relative or empty one', () => {
+    const xdg = path.join(path.sep, 'xdg');
+    expect(
+      userCacheDir({home, platform: 'linux', env: {XDG_CACHE_HOME: xdg}}),
+    ).toBe(path.join(xdg, 'astryx'));
+    expect(
+      userConfigDir({home, platform: 'linux', env: {XDG_CONFIG_HOME: xdg}}),
+    ).toBe(path.join(xdg, 'astryx'));
+    for (const value of ['rel-cache', './cache', '']) {
+      expect(
+        userCacheDir({home, platform: 'linux', env: {XDG_CACHE_HOME: value}}),
+      ).toBe(path.join(home, '.cache', 'astryx'));
+      expect(
+        userConfigDir({home, platform: 'linux', env: {XDG_CONFIG_HOME: value}}),
+      ).toBe(path.join(home, '.config', 'astryx'));
+    }
+  });
+
+  it.skipIf(process.platform !== 'win32')(
+    'uses LOCALAPPDATA and APPDATA on Windows only when absolute',
+    () => {
+      const winHome = 'C:\\Users\\ada';
+      expect(
+        userCacheDir({
+          home: winHome,
+          platform: 'win32',
+          env: {LOCALAPPDATA: 'D:\\Local'},
+        }),
+      ).toBe('D:\\Local\\astryx\\Cache');
+      expect(
+        userConfigDir({
+          home: winHome,
+          platform: 'win32',
+          env: {APPDATA: 'Roaming'},
+        }),
+      ).toBe('C:\\Users\\ada\\AppData\\Roaming\\astryx');
+    },
+  );
+
+  it('reads only absolute folder settings', () => {
+    expect(absoluteDirSetting(undefined)).toBeNull();
+    expect(absoluteDirSetting('')).toBeNull();
+    expect(absoluteDirSetting('cache')).toBeNull();
+    expect(absoluteDirSetting(path.resolve('cache'))).toBe(
+      path.resolve('cache'),
+    );
+  });
+});

package/foundation/env/user-settings.d.mts

@@ -0,0 +1,46 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @typedef {object} ComputerAgentTextSettings
+ * @property {boolean} install Whether the computer-level text is wanted.
+ * @property {string[]} links The links to its skill folder Astryx made, so
+ *   removal removes exactly those.
+ */
+/**
+ * The settings file's path.
+ * @param {string} [configDir]
+ * @returns {string}
+ */
+export function settingsFile(configDir?: string): string;
+/**
+ * The whole settings object; `{}` when the file is missing or unreadable.
+ * @param {string} [configDir]
+ * @returns {Record<string, unknown>}
+ */
+export function readSettings(configDir?: string): Record<string, unknown>;
+/**
+ * The person's choices about the computer-level agent text.
+ * @param {string} [configDir]
+ * @returns {ComputerAgentTextSettings}
+ */
+export function computerAgentTextSettings(configDir?: string): ComputerAgentTextSettings;
+/**
+ * Record the person's choices about the computer-level agent text, keeping
+ * every other setting. Returns whether the file was written.
+ * @param {ComputerAgentTextSettings} choice
+ * @param {string} [configDir]
+ * @returns {boolean}
+ */
+export function recordComputerAgentTextSettings(choice: ComputerAgentTextSettings, configDir?: string): boolean;
+export type ComputerAgentTextSettings = {
+    /**
+     * Whether the computer-level text is wanted.
+     */
+    install: boolean;
+    /**
+     * The links to its skill folder Astryx made, so
+     * removal removes exactly those.
+     */
+    links: string[];
+};