@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/env/user-settings.mjs

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The CLI's per-user settings file (spec AST-081 FR8):
+ * `astryx/settings.json` in the platform's per-user configuration folder.
+ *
+ * It holds the person's choices about the computer-level agent text:
+ *
+ * ```json
+ * {"computerAgentText": {"install": true, "links": ["/home/me/.claude/skills/astryx"]}}
+ * ```
+ *
+ * - `computerAgentText.install`: `false` after `astryx init --user
+ *   --remove-agents`, `true` after `astryx init --user`. A missing file or
+ *   value means install.
+ * - `computerAgentText.links`: the links to the skill folder Astryx made, so
+ *   removal removes exactly those.
+ *
+ * Only `astryx init --user` and the global copy's refresh change it. No environment variable or option
+ * does. A file that cannot be read or parsed counts as missing, and one that
+ * cannot be written never fails a run.
+ *
+ * @input  the per-user configuration folder
+ * @output the settings, and writes to them
+ * @position packages/cli/foundation/env
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {userConfigDir} from './user-dirs.mjs';
+
+/**
+ * @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 = userConfigDir()) {
+  return path.join(configDir, 'settings.json');
+}
+
+/**
+ * The whole settings object; `{}` when the file is missing or unreadable.
+ * @param {string} [configDir]
+ * @returns {Record<string, unknown>}
+ */
+export function readSettings(configDir = userConfigDir()) {
+  try {
+    const value = JSON.parse(fs.readFileSync(settingsFile(configDir), 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value)
+      ? value
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The person's choices about the computer-level agent text.
+ * @param {string} [configDir]
+ * @returns {ComputerAgentTextSettings}
+ */
+export function computerAgentTextSettings(configDir = userConfigDir()) {
+  const raw = readSettings(configDir).computerAgentText;
+  const value =
+    raw && typeof raw === 'object' && !Array.isArray(raw)
+      ? /** @type {Record<string, unknown>} */ (raw)
+      : {};
+  const links = Array.isArray(value.links)
+    ? value.links.filter(link => typeof link === 'string')
+    : [];
+  return {install: value.install !== false, links};
+}
+
+/**
+ * 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,
+  configDir = userConfigDir(),
+) {
+  const next = {
+    ...readSettings(configDir),
+    computerAgentText: {install: choice.install, links: choice.links},
+  };
+  const file = settingsFile(configDir);
+  try {
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {afterEach, describe, expect, it} from 'vitest';
+import {
+  computerAgentTextSettings,
+  readSettings,
+  recordComputerAgentTextSettings,
+  settingsFile,
+} from './user-settings.mjs';
+
+/** @type {string[]} */
+const dirs = [];
+const tmp = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-settings-'));
+  dirs.push(dir);
+  return dir;
+};
+afterEach(() => {
+  for (const dir of dirs.splice(0)) {
+    fs.rmSync(dir, {recursive: true, force: true});
+  }
+});
+
+describe('the settings file (spec AST-081 FR8)', () => {
+  it('means install, with no links, when missing or unreadable', () => {
+    const dir = tmp();
+    expect(computerAgentTextSettings(dir)).toEqual({install: true, links: []});
+    fs.writeFileSync(settingsFile(dir), 'not json');
+    expect(readSettings(dir)).toEqual({});
+    expect(computerAgentTextSettings(dir)).toEqual({install: true, links: []});
+  });
+
+  it('records and reads the choice and the links Astryx made, keeping other settings', () => {
+    const dir = tmp();
+    fs.writeFileSync(settingsFile(dir), '{"other":true}');
+    expect(
+      recordComputerAgentTextSettings(
+        {install: true, links: ['/h/.claude/skills/astryx']},
+        dir,
+      ),
+    ).toBe(true);
+    expect(JSON.parse(fs.readFileSync(settingsFile(dir), 'utf8'))).toEqual({
+      other: true,
+      computerAgentText: {install: true, links: ['/h/.claude/skills/astryx']},
+    });
+    expect(computerAgentTextSettings(dir)).toEqual({
+      install: true,
+      links: ['/h/.claude/skills/astryx'],
+    });
+    recordComputerAgentTextSettings({install: false, links: []}, dir);
+    expect(computerAgentTextSettings(dir)).toEqual({install: false, links: []});
+  });
+
+  it('never fails when the folder cannot be written', () => {
+    const file = path.join(tmp(), 'file');
+    fs.writeFileSync(file, '');
+    expect(
+      recordComputerAgentTextSettings({install: false, links: []}, file),
+    ).toBe(false);
+  });
+});

package/foundation/fs/file-protection.mjs

@@ -9,8 +9,22 @@
  */
 
 import * as fs from 'node:fs';
+import {createRequire} from 'node:module';
 import * as path from 'node:path';
-import ignore from 'ignore';
+
+/**
+ * The `ignore` matcher factory, loaded on first use: this module is reached
+ * from every CLI run through the agent-docs helpers, and only a run that
+ * classifies a file needs the matcher.
+ * @type {typeof import('ignore') | undefined}
+ */
+let ignoreFactory;
+
+/** @param {import('ignore').Options} [options] */
+function ignore(options) {
+  ignoreFactory ??= createRequire(import.meta.url)('ignore');
+  return /** @type {typeof import('ignore')} */ (ignoreFactory)(options);
+}
 
 const DEPENDENCY_DIRS = new Set([
   'node_modules',

package/foundation/fs/module-loader.d.mts

@@ -21,7 +21,8 @@ export function importUserModule(file: string, { fresh }?: {
 /**
  * Load a generated theme artifact and its extensionless JS/JSX/TS/TSX graph.
  * Package specifiers resolve from the consumer project, while relative paths
- * resolve from that same project root.
+ * resolve from that same project root. An import of an existing `.css` file
+ * loads as an empty module.
  * @param {string} specifier
  * @param {string} cwd
  * @returns {Promise<Record<string, unknown>>}

package/foundation/fs/module-loader.mjs

@@ -7,9 +7,11 @@
  * user-authored module (`.ts` via jiti, `.mjs`/`.js` via native dynamic
  * import) and (b) find conventional files by basename in a fixed
  * load-precedence order. Generated theme artifacts also use a dedicated jiti
- * path that resolves extensionless JSX/TSX registry imports. These helpers
- * centralize that behavior so callers stay in lockstep. A module's stdout writes go to stderr while it loads, so
- * project code that prints cannot corrupt a `--json` envelope.
+ * path that resolves extensionless JSX/TSX registry imports and loads the
+ * stylesheets they import as empty modules. These helpers centralize that
+ * behavior so callers stay in lockstep. A module's stdout writes go to stderr
+ * while it loads, so project code that prints cannot corrupt a `--json`
+ * envelope.
  *
  * `loadModuleWithParser` builds on these primitives to provide the single
  * load/validation boundary shared by config, integration, codemod, and
@@ -125,6 +127,56 @@ const THEME_ARTIFACT_EXTENSIONS = [
   '.cts',
 ];
 
+/**
+ * @param {string | symbol} specifier
+ * @returns {specifier is string}
+ */
+function isStylesheetSpecifier(specifier) {
+  return typeof specifier === 'string' && specifier.endsWith('.css');
+}
+
+/**
+ * Whether `specifier`, resolved from the module at `from`, names an existing
+ * `.css` file.
+ * @param {string} specifier
+ * @param {string} from
+ */
+function resolvesToStylesheet(specifier, from) {
+  try {
+    return createRequire(from).resolve(specifier).endsWith('.css');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A built theme module may import a stylesheet so that the app's bundler emits
+ * it. Node cannot load a stylesheet, so an import that ends in `.css` and
+ * resolves from the theme module to an existing `.css` file loads as an empty
+ * module. Any other import loads as before: a missing stylesheet fails like
+ * any missing import, and `./tokens.css` loads `tokens.css.js` when that is
+ * the file it names. jiti shows only the import text, so the check resolves it
+ * from the theme module's folder, not from the importing module's. A module in
+ * another folder fails on a stylesheet it reaches by a different relative
+ * path, and passes on a missing stylesheet whose path exists from the theme
+ * module's folder.
+ * @param {() => string} themeModule returns the theme module's path
+ * @returns {Record<string, unknown>}
+ */
+function themeArtifactStylesheets(themeModule) {
+  return new Proxy(
+    {},
+    {
+      has: (_target, specifier) =>
+        specifier !== themeModule() &&
+        isStylesheetSpecifier(specifier) &&
+        resolvesToStylesheet(specifier, themeModule()),
+      get: (_target, specifier) =>
+        isStylesheetSpecifier(specifier) ? {} : undefined,
+    },
+  );
+}
+
 class ThemeArtifactNotFoundError extends Error {
   code = 'ERR_THEME_ARTIFACT_NOT_FOUND';
 
@@ -153,17 +205,20 @@ function isMissingPackageExport(error) {
 /**
  * Load a generated theme artifact and its extensionless JS/JSX/TS/TSX graph.
  * Package specifiers resolve from the consumer project, while relative paths
- * resolve from that same project root.
+ * resolve from that same project root. An import of an existing `.css` file
+ * loads as an empty module.
  * @param {string} specifier
  * @param {string} cwd
  * @returns {Promise<Record<string, unknown>>}
  */
 export async function importThemeArtifact(specifier, cwd) {
+  let themeModule = path.join(cwd, 'package.json');
   const loader = createJiti(path.join(cwd, 'package.json'), {
     moduleCache: false,
     jsx: true,
     interopDefault: true,
     extensions: THEME_ARTIFACT_EXTENSIONS,
+    virtualModules: themeArtifactStylesheets(() => themeModule),
   });
   let target;
   if (specifier.startsWith('.') || path.isAbsolute(specifier)) {
@@ -179,6 +234,7 @@ export async function importThemeArtifact(specifier, cwd) {
   if (!fs.existsSync(target)) {
     throw new ThemeArtifactNotFoundError(specifier);
   }
+  themeModule = target;
   return await withStdoutOnStderr(() => loader.import(target));
 }
 

package/foundation/fs/module-loader.stdout.test.mjs

@@ -14,6 +14,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import {fileURLToPath, pathToFileURL} from 'node:url';
+import {CLI_VERSION} from '../../test-utils/release-fixtures.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const LOADER_URL = pathToFileURL(path.join(HERE, 'module-loader.mjs')).href;
@@ -268,7 +269,7 @@ describe('--json stdout stays one envelope when project modules print', () => {
     write('package.json', JSON.stringify({name: 'consumer', private: true}));
     write(
       'node_modules/@astryxdesign/core/package.json',
-      JSON.stringify({name: '@astryxdesign/core', version: '0.6.3'}),
+      JSON.stringify({name: '@astryxdesign/core', version: CLI_VERSION}),
     );
     write(
       'astryx.config.js',
@@ -289,7 +290,7 @@ describe('--json stdout stays one envelope when project modules print', () => {
     );
     write(
       'node_modules/@astryxdesign/core/package.json',
-      JSON.stringify({name: '@astryxdesign/core', version: '0.6.3'}),
+      JSON.stringify({name: '@astryxdesign/core', version: CLI_VERSION}),
     );
     write(
       'astryx.config.mjs',

package/foundation/fs/module-loader.test.mjs

@@ -9,6 +9,7 @@ import {pathToFileURL} from 'node:url';
 import {z} from 'zod';
 import {
   findPresentFiles,
+  importThemeArtifact,
   importUserModule,
   loadModuleWithParser,
 } from './module-loader.mjs';
@@ -155,6 +156,199 @@ process.stdout.write(JSON.stringify({first: first.default?.answer, fresh: fresh.
   });
 });
 
+describe('importThemeArtifact', () => {
+  const STYLESHEET_RAN = '__astryxThemeArtifactStylesheetRan';
+
+  /** @param {string} file @param {string} content */
+  function write(file, content) {
+    const target = path.join(tmpDir, file);
+    fs.mkdirSync(path.dirname(target), {recursive: true});
+    fs.writeFileSync(target, content);
+  }
+
+  beforeEach(() => {
+    write('package.json', JSON.stringify({type: 'module'}));
+    write(
+      'ocean.css',
+      '[data-astryx-theme="ocean"] { --color-text: black; }\n',
+    );
+  });
+
+  afterEach(() => {
+    Reflect.deleteProperty(globalThis, STYLESHEET_RAN);
+  });
+
+  it('loads a built module that imports its stylesheet, without running the stylesheet', async () => {
+    // Valid JavaScript, so running this stylesheet would leave a trace.
+    write('ran.css', `globalThis.${STYLESHEET_RAN} = true;\n`);
+    write(
+      'ocean.js',
+      "import './ocean.css';\nimport './ran.css';\nexport const oceanTheme = {name: 'ocean'};\n",
+    );
+
+    const mod = await importThemeArtifact('./ocean.js', tmpDir);
+
+    expect(mod.oceanTheme).toEqual({name: 'ocean'});
+    expect(Reflect.get(globalThis, STYLESHEET_RAN)).toBeUndefined();
+  });
+
+  it('loads a CommonJS built module that requires its stylesheet', async () => {
+    write('commonjs/package.json', JSON.stringify({type: 'commonjs'}));
+    write(
+      'commonjs/ocean.css',
+      '[data-astryx-theme="ocean"] { --color-text: black; }\n',
+    );
+    write(
+      'commonjs/ocean.js',
+      "require('./ocean.css');\nexports.oceanTheme = {name: 'ocean'};\n",
+    );
+
+    const mod = await importThemeArtifact('./commonjs/ocean.js', tmpDir);
+
+    expect(mod.oceanTheme).toEqual({name: 'ocean'});
+  });
+
+  it('loads stylesheets imported by a nested module, through a package export, and dynamically', async () => {
+    const packageDir = 'node_modules/@acme/themes';
+    write(
+      `${packageDir}/package.json`,
+      JSON.stringify({
+        name: '@acme/themes',
+        type: 'module',
+        exports: {
+          './themes/ocean': './dist/ocean.js',
+          './themes/ocean.css': './dist/ocean.css',
+        },
+      }),
+    );
+    write(
+      `${packageDir}/dist/ocean.css`,
+      '[data-astryx-theme="ocean"] { --color-text: black; }\n',
+    );
+    write(
+      `${packageDir}/dist/tokens.js`,
+      "import '@acme/themes/themes/ocean.css';\nexport const tokens = {};\n",
+    );
+    write(
+      `${packageDir}/dist/ocean.js`,
+      "import {tokens} from './tokens.js';\nawait import('./ocean.css');\nexport const oceanTheme = {name: 'ocean', tokens};\n",
+    );
+
+    const mod = await importThemeArtifact('@acme/themes/themes/ocean', tmpDir);
+
+    expect(mod.oceanTheme).toEqual({name: 'ocean', tokens: {}});
+  });
+
+  it('still resolves an extensionless import to its directory index beside a same-named stylesheet', async () => {
+    write('ocean/index.js', "export const oceanTheme = {name: 'ocean'};\n");
+    write(
+      'entry.js',
+      "import './ocean.css';\nexport {oceanTheme} from './ocean';\n",
+    );
+
+    const mod = await importThemeArtifact('./entry.js', tmpDir);
+
+    expect(mod.oceanTheme).toEqual({name: 'ocean'});
+  });
+
+  it('loads a module whose import ends in .css but names a JavaScript file', async () => {
+    write('tokens.css.js', "export const vars = {accent: 'blue'};\n");
+    write(
+      'ocean.js',
+      "import './ocean.css';\nimport {vars} from './tokens.css';\nexport const oceanTheme = {name: 'ocean', vars};\n",
+    );
+
+    const mod = await importThemeArtifact('./ocean.js', tmpDir);
+
+    expect(mod.oceanTheme).toEqual({name: 'ocean', vars: {accent: 'blue'}});
+  });
+
+  it.each([
+    ['a missing file', "import './fonts.css';\n", /fonts\.css/],
+    [
+      'a package that is not installed',
+      "import '@acme/missing-fonts/inter.css';\n",
+      /@acme\/missing-fonts\/inter\.css/,
+    ],
+  ])(
+    'still rejects a stylesheet import of %s',
+    async (_label, stylesheetImport, expected) => {
+      write(
+        'ocean.js',
+        `import './ocean.css';\n${stylesheetImport}export const oceanTheme = {name: 'ocean'};\n`,
+      );
+
+      await expect(importThemeArtifact('./ocean.js', tmpDir)).rejects.toThrow(
+        expected,
+      );
+    },
+  );
+
+  it('still rejects a theme module path that names a stylesheet', async () => {
+    await expect(importThemeArtifact('./ocean.css', tmpDir)).rejects.toThrow(
+      /Unknown file extension "\.css"/,
+    );
+  });
+
+  it('still rejects a stylesheet import that its package does not export', async () => {
+    const packageDir = 'node_modules/@acme/themes';
+    write(
+      `${packageDir}/package.json`,
+      JSON.stringify({
+        name: '@acme/themes',
+        type: 'module',
+        exports: {'./themes/ocean': './dist/ocean.js'},
+      }),
+    );
+    write(
+      `${packageDir}/dist/ocean.css`,
+      '[data-astryx-theme="ocean"] { --color-text: black; }\n',
+    );
+    write(
+      `${packageDir}/dist/ocean.js`,
+      "import '@acme/themes/themes/ocean.css';\nexport const oceanTheme = {name: 'ocean'};\n",
+    );
+
+    await expect(
+      importThemeArtifact('@acme/themes/themes/ocean', tmpDir),
+    ).rejects.toThrow(/not defined by "exports"/);
+  });
+
+  it.each([
+    [
+      'a missing dependency',
+      "import './missing.js';\nexport const oceanTheme = {name: 'ocean'};\n",
+      /missing\.js/,
+    ],
+    [
+      'a syntax error in a module it imports',
+      "import './broken.js';\nexport const oceanTheme = {name: 'ocean'};\n",
+      /ParseError/,
+    ],
+    [
+      'a throwing module',
+      "throw new Error('broken theme module');\n",
+      /broken theme module/,
+    ],
+    [
+      'an asset that is not a stylesheet',
+      "import './logo.svg';\nexport const oceanTheme = {name: 'ocean'};\n",
+      /Unknown file extension "\.svg"/,
+    ],
+  ])(
+    'still rejects a built module that imports its stylesheet and has %s',
+    async (_label, rest, expected) => {
+      write('logo.svg', '<svg xmlns="http://www.w3.org/2000/svg"/>\n');
+      write('broken.js', 'export const broken = ;\n');
+      write('ocean.js', `import './ocean.css';\n${rest}`);
+
+      await expect(importThemeArtifact('./ocean.js', tmpDir)).rejects.toThrow(
+        expected,
+      );
+    },
+  );
+});
+
 describe('loadModuleWithParser', () => {
   // Temp module files live under a repo-local dir (not /tmp): Vite's dynamic
   // import blocks /tmp, so we mirror the existing repo-local temp pattern.

package/foundation/fs/path-compare.d.mts

@@ -0,0 +1,33 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Whether the platform's file systems ignore letter case by default.
+ * @param {NodeJS.Platform} [platform]
+ * @returns {boolean}
+ */
+export function ignoresCase(platform?: NodeJS.Platform): boolean;
+/**
+ * A path in the form two spellings of one folder share.
+ * @param {string} p
+ * @param {NodeJS.Platform} [platform]
+ * @returns {string}
+ */
+export function pathKey(p: string, platform?: NodeJS.Platform): string;
+/**
+ * Whether two paths name the same folder or file.
+ * @param {string} a
+ * @param {string} b
+ * @param {NodeJS.Platform} [platform]
+ * @returns {boolean}
+ */
+export function samePath(a: string, b: string, platform?: NodeJS.Platform): boolean;
+/**
+ * `child` relative to `parent`, compared the way the file system compares
+ * names; `null` when `child` is not inside `parent` (or is `parent`).
+ * @param {string} parent
+ * @param {string} child
+ * @param {NodeJS.Platform} [platform]
+ * @returns {string | null}
+ */
+export function relativeWithin(parent: string, child: string, platform?: NodeJS.Platform): string | null;

package/foundation/fs/path-compare.mjs

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Path comparison that matches the file system (spec AST-081 FR11):
+ * Windows and macOS file systems ignore letter case by default, so two
+ * spellings that differ only in case name the same folder there, and the
+ * release choice must treat them as one.
+ *
+ * @input  paths and the platform
+ * @output whether two paths are the same, and a path relative to a folder
+ * @position packages/cli/foundation/fs — used by the release choice and the
+ *   release cache.
+ */
+
+import * as path from 'node:path';
+
+/**
+ * Whether the platform's file systems ignore letter case by default.
+ * @param {NodeJS.Platform} [platform]
+ * @returns {boolean}
+ */
+export function ignoresCase(platform = process.platform) {
+  return platform === 'win32' || platform === 'darwin';
+}
+
+/**
+ * The path module of a platform.
+ * @param {NodeJS.Platform} platform
+ * @returns {typeof path.posix}
+ */
+function pathsOf(platform) {
+  return platform === 'win32' ? path.win32 : path.posix;
+}
+
+/**
+ * A path in the form two spellings of one folder share.
+ * @param {string} p
+ * @param {NodeJS.Platform} [platform]
+ * @returns {string}
+ */
+export function pathKey(p, platform = process.platform) {
+  const normal = pathsOf(platform).normalize(p);
+  return ignoresCase(platform) ? normal.toLowerCase() : normal;
+}
+
+/**
+ * Whether two paths name the same folder or file.
+ * @param {string} a
+ * @param {string} b
+ * @param {NodeJS.Platform} [platform]
+ * @returns {boolean}
+ */
+export function samePath(a, b, platform = process.platform) {
+  return pathKey(a, platform) === pathKey(b, platform);
+}
+
+/**
+ * `child` relative to `parent`, compared the way the file system compares
+ * names; `null` when `child` is not inside `parent` (or is `parent`).
+ * @param {string} parent
+ * @param {string} child
+ * @param {NodeJS.Platform} [platform]
+ * @returns {string | null}
+ */
+export function relativeWithin(parent, child, platform = process.platform) {
+  const paths = pathsOf(platform);
+  const rel = paths.relative(
+    pathKey(parent, platform),
+    pathKey(child, platform),
+  );
+  if (rel === '' || rel.startsWith('..') || paths.isAbsolute(rel)) return null;
+  return rel;
+}