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

package/api/upgrade/upgrade.mjs

@@ -24,6 +24,7 @@
 import {list} from './list/list.mjs';
 import {registryUpgrade} from './registry/registry.mjs';
 import {run} from './run/run.mjs';
+import {relativeToOrigin, scopeToProject} from './_adapter.mjs';
 import {isValidSemver} from '../../foundation/env/semver.mjs';
 import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
 import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
@@ -88,7 +89,11 @@ export async function upgrade(options = {}, {cwd = process.cwd()} = {}) {
       logger.log('Aborted\n');
       throw new AstryxError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);
     }
-    return registryUpgrade(options, {cwd});
+    const scoped = scopeToProject(options, cwd);
+    return registryUpgrade(scoped.options, {
+      cwd: scoped.cwd,
+      origin: scoped.origin,
+    });
   }
 
   if (!options.list && !options.from) {
@@ -112,5 +117,11 @@ export async function upgrade(options = {}, {cwd = process.cwd()} = {}) {
     return list();
   }
 
-  return run(options, {cwd});
+  // A run from a subfolder upgrades the project the folder belongs to, and
+  // names files relative to the folder it ran in.
+  const scoped = scopeToProject(options, cwd);
+  return relativeToOrigin(
+    await run(scoped.options, {cwd: scoped.cwd, origin: scoped.origin}),
+    scoped,
+  );
 }

package/api/upgrade/upgrade.test.mjs

@@ -246,6 +246,200 @@ describe('upgrade() — receipts', () => {
     expect(content).not.toMatch(/Astryx v0\.0\.1 ·/);
   });
 
+  it('leaves the block of a project at the top of a home settings folder, saying why and not pointing at init', async () => {
+    const saved = {
+      HOME: process.env.HOME,
+      USERPROFILE: process.env.USERPROFILE,
+    };
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    const warned = [];
+    const warn = vi
+      .spyOn(console, 'error')
+      .mockImplementation((...a) => warned.push(a.join(' ')));
+    logger.setSilent(false);
+    try {
+      const project = path.join(tmpDir, '.dotfiles');
+      fs.mkdirSync(project, {recursive: true});
+      writePkg(project, {'@astryxdesign/core': '0.0.15'});
+      writeInstalledCore(project, '0.0.15');
+      writeAgentBlock(project, 'AGENTS.md', '0.0.1');
+
+      const res = await upgrade({from: '0.0.15', apply: true}, {cwd: project});
+
+      expect(res.data.agentDocs.action).toBe('error');
+      expect(res.data.agentDocs.refreshed).toBe(false);
+      expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toMatch(
+        /Astryx v0\.0\.1 ·/,
+      );
+      const text = warned.join('\n');
+      expect(text).toContain(
+        `Agent docs not refreshed: ${fs.realpathSync(project)} is the home folder or a settings folder in it, which every project's agents read. To keep agent docs, move the project into a folder of its own; otherwise update or remove the Astryx block there by hand.`,
+      );
+      expect(text).not.toContain('init --features agents');
+    } finally {
+      logger.setSilent(true);
+      warn.mockRestore();
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+
+  it('with no block, in a project at the top of a home settings folder, says why instead of pointing at init', async () => {
+    const saved = {
+      HOME: process.env.HOME,
+      USERPROFILE: process.env.USERPROFILE,
+    };
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    const warned = [];
+    const warn = vi
+      .spyOn(console, 'error')
+      .mockImplementation((...a) => warned.push(a.join(' ')));
+    logger.setSilent(false);
+    try {
+      const project = path.join(tmpDir, '.dotfiles');
+      fs.mkdirSync(project, {recursive: true});
+      writePkg(project, {'@astryxdesign/core': '0.0.15'});
+      writeInstalledCore(project, '0.0.15');
+
+      const res = await upgrade({from: '0.0.15'}, {cwd: project});
+
+      expect(res.data.agentDocs.action).toBe('error');
+      const text = warned.join('\n');
+      expect(text).toContain(
+        `Agent docs not installed: ${fs.realpathSync(project)} is the home folder or a settings folder in it, which every project's agents read. To have agent docs, move the project into a folder of its own, or add the Astryx block to its agent file by hand.`,
+      );
+      expect(text).not.toContain('init --features agents');
+    } finally {
+      logger.setSilent(true);
+      warn.mockRestore();
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+
+  it('a dry run in a project at the top of a home settings folder reports the refusal, not a refresh to apply', async () => {
+    const saved = {
+      HOME: process.env.HOME,
+      USERPROFILE: process.env.USERPROFILE,
+    };
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    const warned = [];
+    const warn = vi
+      .spyOn(console, 'error')
+      .mockImplementation((...a) => warned.push(a.join(' ')));
+    logger.setSilent(false);
+    try {
+      const project = path.join(tmpDir, '.dotfiles');
+      fs.mkdirSync(project, {recursive: true});
+      writePkg(project, {'@astryxdesign/core': '0.0.15'});
+      writeInstalledCore(project, '0.0.15');
+      writeAgentBlock(project, 'AGENTS.md', '0.0.1');
+
+      const res = await upgrade({from: '0.0.15'}, {cwd: project});
+
+      expect(res.data.agentDocs.action).toBe('error');
+      expect(res.data.agentDocs.refreshed).toBe(false);
+      const text = warned.join('\n');
+      expect(text).toContain(
+        `Agent docs not refreshed: ${fs.realpathSync(project)} is the home folder or a settings folder in it`,
+      );
+      expect(text).not.toContain('--apply to refresh');
+      expect(text).not.toContain('init --features agents');
+    } finally {
+      logger.setSilent(true);
+      warn.mockRestore();
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+
+  it('refreshes the agent docs of a project in an agent worktree inside a home settings folder', async () => {
+    const saved = {
+      HOME: process.env.HOME,
+      USERPROFILE: process.env.USERPROFILE,
+    };
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    try {
+      const project = path.join(tmpDir, '.codex', 'worktrees', 'a1b2c3', 'web');
+      fs.mkdirSync(project, {recursive: true});
+      writePkg(project, {'@astryxdesign/core': '0.0.15'});
+      writeInstalledCore(project, '0.0.15');
+      writeAgentBlock(project, 'AGENTS.md', '0.0.1');
+
+      const res = await upgrade({from: '0.0.15', apply: true}, {cwd: project});
+
+      expect(res.data.agentDocs.action).toBe('refreshed');
+      expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toMatch(
+        /Astryx v0\.0\.15 ·/,
+      );
+    } finally {
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+
+  it('refreshes the managed block in an ignored .claude/CLAUDE.md and keeps the text around it (INV31)', async () => {
+    writePkg(tmpDir);
+    writeInstalledCore(tmpDir, '0.0.15');
+    writeAgentBlock(tmpDir, 'AGENTS.md', '0.0.1');
+    fs.mkdirSync(path.join(tmpDir, '.claude'));
+    writeAgentBlock(tmpDir, '.claude/CLAUDE.md', '0.0.1');
+    const claude = path.join(tmpDir, '.claude', 'CLAUDE.md');
+    fs.writeFileSync(
+      claude,
+      `# Team notes\n\n${fs.readFileSync(claude, 'utf-8')}\nMore notes.\n`,
+    );
+    fs.writeFileSync(path.join(tmpDir, '.gitignore'), '.claude/\n');
+
+    const res = await upgrade({from: '0.0.15', apply: true}, {cwd: tmpDir});
+
+    expect(res.data.agentDocs.action).toBe('refreshed');
+    expect(res.data.agentDocs.files).toEqual([
+      'AGENTS.md',
+      '.claude/CLAUDE.md',
+    ]);
+    expect(res.data.agentDocs).not.toHaveProperty('protectedFiles');
+    const content = fs.readFileSync(claude, 'utf-8');
+    expect(content).toMatch(/^# Team notes\n/u);
+    expect(content).toMatch(/Astryx v0\.0\.15 ·/u);
+    expect(content).toMatch(/More notes\.\n$/u);
+  });
+
+  it('refreshes a committed .claude/CLAUDE.md that imports AGENTS.md and keeps a copy beside an ignored root CLAUDE.md', async () => {
+    writePkg(tmpDir);
+    writeInstalledCore(tmpDir, '0.0.15');
+    writeAgentBlock(tmpDir, 'AGENTS.md', '0.0.1');
+    writeAgentBlock(tmpDir, 'CLAUDE.md', '0.0.1');
+    fs.writeFileSync(path.join(tmpDir, '.gitignore'), '/CLAUDE.md\n');
+    fs.mkdirSync(path.join(tmpDir, '.claude'));
+    const copy = path.join(tmpDir, '.claude', 'CLAUDE.md');
+    fs.writeFileSync(
+      copy,
+      `@../AGENTS.md\n\n${generateCompressedIndex('0.0.1')}\n`,
+    );
+
+    for (let round = 0; round < 2; round++) {
+      await upgrade({from: '0.0.15', apply: true}, {cwd: tmpDir});
+      const content = fs.readFileSync(copy, 'utf-8');
+      expect(content, `round ${round}`).toMatch(/^@\.\.\/AGENTS\.md\n/u);
+      expect(content, `round ${round}`).toMatch(/Astryx v0\.0\.15 ·/u);
+    }
+    const dry = await upgrade({from: '0.0.15'}, {cwd: tmpDir});
+    expect(dry.data.agentDocs.status).toBe('current');
+  });
+
   it('reports would-refresh on a dry run without writing (honors cwd)', async () => {
     writePkg(tmpDir);
     writeInstalledCore(tmpDir, '0.0.15');

package/api/upgrade/upgrade.type.d.mts

@@ -44,7 +44,7 @@ export type AgentDocsSummary = {
      */
     fromVersions: string[];
     /**
-     * Files rewritten (apply) or that would be rewritten (dry-run).
+     * Files rewritten (apply) or that would be rewritten (dry-run), relative to the folder the command ran in.
      */
     files: string[];
     /**
@@ -73,7 +73,9 @@ export type RegistryCompositionItemSummary = {
     files: RegistryCompositionFileSummary[];
 };
 /**
- * Aggregate receipt for ShadCN-copied composition reconciliation.
+ * Aggregate receipt for ShadCN-copied composition reconciliation. File paths
+ * are relative to the scanned source directory, or, when the upgrade ran in a
+ * folder below the project root, to that folder.
  */
 export type RegistryCompositionSummary = {
     applied: boolean;
@@ -140,7 +142,7 @@ export type UpgradeRegistryResponse = {
  */
 export type ProtectedCodemodFile = {
     /**
-     * Project-relative path.
+     * Path relative to the folder the command ran in.
      */
     file: string;
     /**

package/api/upgrade/upgrade.type.mjs

@@ -45,7 +45,7 @@
  * @property {'missing' | 'stale' | 'current'} status
  * @property {string} installedVersion Installed core version the block should reflect.
  * @property {string[]} fromVersions Distinct stale block versions found (the "from" side of the refresh).
- * @property {string[]} files Files rewritten (apply) or that would be rewritten (dry-run).
+ * @property {string[]} files Files rewritten (apply) or that would be rewritten (dry-run), relative to the folder the command ran in.
  * @property {boolean} refreshed True only when a block was actually rewritten (apply mode).
  * @property {'refreshed' | 'would-refresh' | 'nudge-init' | 'error' | 'none'} action
  */
@@ -70,7 +70,9 @@
  */
 
 /**
- * Aggregate receipt for ShadCN-copied composition reconciliation.
+ * Aggregate receipt for ShadCN-copied composition reconciliation. File paths
+ * are relative to the scanned source directory, or, when the upgrade ran in a
+ * folder below the project root, to that folder.
  * @typedef {object} RegistryCompositionSummary
  * @property {boolean} applied
  * @property {boolean} ok False when conflicts, missing files, invalid receipts, or failures remain.
@@ -99,7 +101,7 @@
 /**
  * A required codemod change blocked by effective working-tree protection.
  * @typedef {object} ProtectedCodemodFile
- * @property {string} file Project-relative path.
+ * @property {string} file Path relative to the folder the command ran in.
  * @property {string[]} codemods Codemods that still require a change.
  * @property {string[]} reasons Protection categories (generated, vendored, ignored, and hard boundaries).
  * @property {string[]} declarations Effective declarations that protect the file.
@@ -132,11 +134,11 @@
  * @property {boolean} [data.complete] False when protected required changes remain.
  * @property {'ERR_CODEMOD_PROTECTED'} [data.errorCode] Stable incomplete-result code when complete is false.
  * @property {number} [data.filesChanged] Distinct files changed across core + integration codemods (apply mode). One file that four codemods each changed counts once.
- * @property {string[]} [data.modifiedFiles] Project-relative files changed or previewed.
+ * @property {string[]} [data.modifiedFiles] Files changed or previewed, relative to the folder the command ran in.
  * @property {ProtectedCodemodFile[]} [data.protectedFiles] Protected files that still require a codemod change after regeneration.
- * @property {Array<{file: string, location?: string, reason: string}>} [data.declinedCandidates] Candidates left unchanged because proof was insufficient.
+ * @property {Array<{file: string, location?: string, reason: string}>} [data.declinedCandidates] Candidates left unchanged because proof was insufficient. Each `file` is relative to the folder the command ran in.
  * @property {number} [data.transformsApplied] Total codemod changes. A code or config codemod counts once for each file it changed, so one file changed by four of them counts four times; a project codemod counts once, however many files it writes.
- * @property {Array<{file: string, codemod: string, error: string}>} [data.errors] Per-codemod errors, when any codemod failed.
+ * @property {Array<{file: string, codemod: string, error: string}>} [data.errors] Per-codemod errors, when any codemod failed. Each `file` is relative to the folder the command ran in.
  * @property {CliBehindCore} [data.cliBehindCore] Present only when the installed Core is newer than this CLI: codemods for the releases after `cliBehindCore.cliVersion` did not run.
  */
 

package/assets/codemods/transforms/v0.7.0/__tests__/validate-data-token-ownership.test.mjs

@@ -29,6 +29,17 @@ describe('validate-data-token-ownership', () => {
     }
   });
 
+  it('reports prebuilt CSS availability without requiring a source compile step', async () => {
+    await expect(
+      run('const fill = "var(--color-data-categorical-blue)";'),
+    ).rejects.toThrow(
+      /in prebuilt mode, loads @astryxdesign\/core\/astryx\.css/,
+    );
+    await expect(
+      run('.bar { fill: var(--color-data-categorical-blue); }', 'chart.css'),
+    ).rejects.toThrow(/load @astryxdesign\/core\/astryx\.css in prebuilt mode/);
+  });
+
   it('leaves fallbacks, dataVars access, and comments unchanged', async () => {
     const source = `
 // var(--color-data-categorical-green)

package/assets/codemods/transforms/v0.7.0/validate-data-token-ownership.mjs

@@ -56,7 +56,7 @@ export default function validateDataTokenOwnership(file, api) {
       ROOT_DATA_DECLARATION.test(file.source)
     ) {
       throw new Error(
-        'This generated theme CSS still emits canonical data defaults at :root. Rebuild it with `astryx theme build`; defaults now come from compiled dataVars consumers.',
+        'This generated theme CSS still emits canonical data defaults at :root. Rebuild it with `astryx theme build`; defaults come from source-compiled dataVars consumers or @astryxdesign/core/astryx.css in prebuilt mode.',
       );
     }
     const uncommented = file.source.replace(CSS_COMMENT, comment =>
@@ -66,7 +66,7 @@ export default function validateDataTokenOwnership(file, api) {
     if (cssMatch) {
       const line = uncommented.slice(0, cssMatch.index).split('\n').length;
       throw new Error(
-        `Raw var(${cssMatch[1]}) without a fallback at line ${line} needs manual migration: compiled dataVars output is not guaranteed in this stylesheet, so add an explicit fallback or style the element from code that imports dataVars from @astryxdesign/core/theme/dataTokens.stylex.`,
+        `Raw var(${cssMatch[1]}) without a fallback at line ${line} needs an availability check: load @astryxdesign/core/astryx.css in prebuilt mode, ensure a source-compiled dataVars consumer retains the group, or add an explicit fallback. CSS-capable code imports dataVars from @astryxdesign/core/theme/dataTokens.stylex.`,
       );
     }
     return undefined;
@@ -95,7 +95,7 @@ export default function validateDataTokenOwnership(file, api) {
   if (found) {
     const {token, line} = found;
     throw new Error(
-      `Direct var(${token})${line == null ? '' : ` at line ${line}`} needs manual migration: CSS-capable code imports dataVars from @astryxdesign/core/theme/dataTokens.stylex; Canvas and other non-CSS APIs use resolveThemeToken() or useTheme().token().`,
+      `Direct var(${token})${line == null ? '' : ` at line ${line}`} needs manual migration: CSS-capable code imports dataVars from @astryxdesign/core/theme/dataTokens.stylex and, in prebuilt mode, loads @astryxdesign/core/astryx.css; Canvas and other non-CSS APIs use resolveThemeToken() or useTheme().token().`,
     );
   }
   return undefined;

package/assets/docs/author-a-theme.doc.mjs

@@ -28,7 +28,7 @@ export const docs = {
         {type: 'code', lang: 'json', label: 'Minimal palette config (palette.config.json)', code: '{"families": [{"id": "ocean", "seed": "#0074e2"}]}'},
         {type: 'code', lang: 'bash', label: 'Generate and preview', code: '# Print the palette without writing files\nastryx theme palette generate palette.config.json\n\n# Write palette + receipt, and open a visual preview\nastryx theme palette generate palette.config.json \\\n  --out src/themes/ocean/tokens/ocean.palette.ts \\\n  --preview preview.html'},
         {type: 'prose', text: "The command writes a `.ts` file exporting 21 shades (stops 0–100) for both light and dark, plus a `.receipt.json` to regenerate later. Point your theme's tokens at the palette, then run defineTheme (see below)."},
-        {type: 'prose', text: 'For the full palette config fields and CLI flags, run `astryx docs cli/commands/theme-palette-generate`. For the integration-authoring walkthrough of connecting a palette to theme tokens, run `astryx docs cli/integrations/building-blocks/themes/generate-a-palette`.'},
+        {type: 'prose', text: 'For the full palette config fields and CLI flags, run `astryx docs cli/commands/theme-palette-generate`. For the integration-authoring walkthrough of connecting a palette to theme tokens, run `astryx docs authoring/building-blocks/themes/generate-a-palette`.'},
       ],
     },
     {
@@ -61,7 +61,7 @@ export const docs = {
           ['adaptations', 'Width-breakpoint overrides merge by fixed name. Inherited ordered rules keep their relative order; child rules append and re-resolve against the child root axes.'],
         ]},
         {type: 'prose', text: "Inheritance is resolved when the theme is defined, so an extended theme is flat: `astryx theme build` emits one self-contained stylesheet holding everything the child inherited, and the base theme's CSS does not need to be loaded next to it. A base that is not a theme (most often an import that missed) throws when `defineTheme` runs, rather than producing a theme that silently inherits nothing."},
-        {type: 'prose', text: 'For the integration-specific guidance on mapping a palette to tokens when extending, see `astryx docs cli/integrations/building-blocks/themes/define-the-theme`.'},
+        {type: 'prose', text: 'For the integration-specific guidance on mapping a palette to tokens when extending, see `astryx docs authoring/building-blocks/themes/define-the-theme`.'},
       ],
     },
     {