@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/foundation/agent-docs/agent-docs.path-safety.test.mjs

@@ -1,22 +1,31 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Path-safety regression tests for `--agent-docs-path`.
+ * @file Path-safety regression tests for agent-doc writes.
  *
  * `installAgentDocs(targetDir, {paths})` previously joined each path
  * onto `targetDir` with no validation, so:
  *   - `../OUT.md` wrote outside `targetDir`
  *   - `/tmp/x.md` was silently re-rooted under `targetDir`
  *
- * Both cases now throw PathSafetyError before any file is touched.
+ * Auto-detected and preset files were never checked at all, so a `CLAUDE.md`
+ * or `.claude/` symlinked out of the project had the block written through
+ * it. Every case now throws PathSafetyError before any file is touched.
+ *
+ * `removeAgentDocs` (`init --remove-agents`) stripped or deleted a block
+ * through the same kind of link and reported success. It now refuses with
+ * `ERR_PATH_TRAVERSAL` before any file is touched.
  */
 
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {installAgentDocs} from './agent-docs.mjs';
+import {installAgentDocs, removeAgentDocs} from './agent-docs.mjs';
 import {PathSafetyError} from '../fs/path-safety.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const BLOCK = '<!-- ASTRYX:START -->\nmanaged\n<!-- ASTRYX:END -->';
 
 let tmpDir;
 beforeEach(() => {
@@ -26,6 +35,28 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
+/** A project dir plus a sibling dir outside it. */
+function layout() {
+  const project = path.join(tmpDir, 'project');
+  const outside = path.join(tmpDir, 'outside');
+  fs.mkdirSync(project, {recursive: true});
+  fs.mkdirSync(outside, {recursive: true});
+  return {project, outside};
+}
+
+/**
+ * @param {() => unknown} fn
+ * @returns {unknown} what `fn` threw
+ */
+function thrownBy(fn) {
+  try {
+    fn();
+  } catch (err) {
+    return err;
+  }
+  throw new Error('expected a throw');
+}
+
 describe('installAgentDocs path safety', () => {
   it('rejects --agent-docs-path that escapes the target directory', () => {
     const target = path.join(tmpDir, 'project');
@@ -64,3 +95,234 @@ describe('installAgentDocs path safety', () => {
     expect(fs.existsSync(path.join(tmpDir, 'escaped.md'))).toBe(false);
   });
 });
+
+describe('installAgentDocs never writes through a symlink out of the project', () => {
+  it('refuses an auto-detected file that links outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, '# Shared\n');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() => installAgentDocs(project, {renderedBlock: BLOCK})).toThrow(
+      /outside the project root/,
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
+  });
+
+  it('refuses a preset file reached through a symlinked directory', () => {
+    const {project, outside} = layout();
+    fs.symlinkSync(outside, path.join(project, '.claude'));
+
+    expect(() =>
+      installAgentDocs(project, {agent: 'claude', renderedBlock: BLOCK}),
+    ).toThrow(PathSafetyError);
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('refuses an existing preset file that links outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'rules');
+    fs.writeFileSync(shared, 'rules\n');
+    fs.symlinkSync(shared, path.join(project, '.cursorrules'));
+
+    expect(() =>
+      installAgentDocs(project, {agent: 'cursor', renderedBlock: BLOCK}),
+    ).toThrow(PathSafetyError);
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('rules\n');
+  });
+
+  it('writes nothing when any file of the set escapes', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), '# Agents\n');
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, '# Shared\n');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() => installAgentDocs(project, {renderedBlock: BLOCK})).toThrow(
+      PathSafetyError,
+    );
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
+      '# Agents\n',
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
+  });
+
+  it('refuses to refresh a managed block that lives outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `# Shared\n\n${BLOCK.replace('managed', 'old')}\n`);
+    const before = fs.readFileSync(shared, 'utf-8');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() =>
+      installAgentDocs(project, {onlyReplace: true, renderedBlock: BLOCK}),
+    ).toThrow(PathSafetyError);
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(before);
+  });
+
+  it('refuses to strip a duplicate block from a wrapper that links outside', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\n${BLOCK}\n`);
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `@AGENTS.md\n\n${BLOCK}\n`);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() => installAgentDocs(project, {renderedBlock: BLOCK})).toThrow(
+      PathSafetyError,
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(`@AGENTS.md\n\n${BLOCK}\n`);
+  });
+
+  it('still refreshes in-project blocks beside an unmarked outside link it skips', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(
+      path.join(project, 'AGENTS.md'),
+      `# Agents\n\n${BLOCK.replace('managed', 'old')}\n`,
+    );
+    const shared = path.join(outside, 'rules');
+    fs.writeFileSync(shared, 'rules\n');
+    fs.symlinkSync(shared, path.join(project, '.cursorrules'));
+
+    expect(
+      installAgentDocs(project, {onlyReplace: true, renderedBlock: BLOCK}),
+    ).toEqual(['AGENTS.md']);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toContain(
+      'managed',
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('rules\n');
+  });
+
+  it('writes through a symlink that stays inside the project', () => {
+    const {project} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), '# Agents\n');
+    fs.symlinkSync('AGENTS.md', path.join(project, 'CLAUDE.md'));
+
+    expect(installAgentDocs(project, {renderedBlock: BLOCK})).toEqual([
+      'AGENTS.md',
+      'CLAUDE.md',
+    ]);
+    const content = fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8');
+    expect(content.split('<!-- ASTRYX:START -->')).toHaveLength(2);
+  });
+});
+
+describe('init --features agents with an agent doc linked outside the project', () => {
+  it('writes nothing outside, reports path-safety, and exits 1 in both modes', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(project, {recursive: true});
+    fs.mkdirSync(outside, {recursive: true});
+    fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, '# Shared\n');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    const json = await runCli(['init', '--features', 'agents', '--json'], project);
+    expect(json.status).toBe(1);
+    const env = JSON.parse(json.stdout);
+    expect(env.type).toBe('init.run');
+    expect(env.data.docsError).toMatchObject({kind: 'path-safety'});
+
+    const text = await runCli(['init', '--features', 'agents'], project);
+    expect(text.status).toBe(1);
+
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
+  }, 30_000);
+});
+
+describe('removeAgentDocs never changes a file out of the project', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('refuses to strip a block from a file that links outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `# Shared\n\n${BLOCK}\n`);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    const err = thrownBy(() => removeAgentDocs(project));
+    expect(err).toBeInstanceOf(PathSafetyError);
+    expect(err).toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(`# Shared\n\n${BLOCK}\n`);
+  });
+
+  it('refuses to delete a file reached through a symlinked directory', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    const content = `# CLAUDE\n\nProject-specific guidance for AI coding agents.\n\n${BLOCK}\n`;
+    fs.writeFileSync(shared, content);
+    fs.symlinkSync(outside, path.join(project, '.claude'));
+
+    expect(thrownBy(() => removeAgentDocs(project))).toMatchObject({
+      code: 'ERR_PATH_TRAVERSAL',
+    });
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(content);
+  });
+
+  it('changes nothing when any file of the set escapes', () => {
+    const {project, outside} = layout();
+    const agents = `# Agents\n\nkeep\n\n${BLOCK}\n`;
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), agents);
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `# Shared\n\n${BLOCK}\n`);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(thrownBy(() => removeAgentDocs(project))).toBeInstanceOf(PathSafetyError);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(agents);
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(`# Shared\n\n${BLOCK}\n`);
+  });
+
+  it('still strips in-project blocks beside an unmarked outside link it skips', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\nkeep\n\n${BLOCK}\n`);
+    const shared = path.join(outside, 'rules');
+    fs.writeFileSync(shared, 'rules\n');
+    fs.symlinkSync(shared, path.join(project, '.cursorrules'));
+
+    removeAgentDocs(project);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
+      '# Agents\n\nkeep\n',
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('rules\n');
+  });
+
+  it('strips through a symlink that stays inside the project', () => {
+    const {project} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\nkeep\n\n${BLOCK}\n`);
+    fs.symlinkSync('AGENTS.md', path.join(project, 'CLAUDE.md'));
+
+    removeAgentDocs(project);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
+      '# Agents\n\nkeep\n',
+    );
+  });
+});
+
+describe('init --remove-agents with an agent doc linked outside the project', () => {
+  it('changes nothing outside, fails with ERR_PATH_TRAVERSAL, and exits 1 in both modes', async () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
+    const shared = path.join(outside, 'CLAUDE.md');
+    const content = `# Shared\n\n${BLOCK}\n`;
+    fs.writeFileSync(shared, content);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    const json = await runCli(['init', '--remove-agents', '--json'], project);
+    expect(json.status).toBe(1);
+    const env = JSON.parse(json.stdout);
+    expect(env).toMatchObject({apiVersion: 1, code: 'ERR_PATH_TRAVERSAL'});
+    expect(env.error).toMatch(/"CLAUDE\.md": resolves outside the project root/);
+    expect(env).not.toHaveProperty('data');
+
+    const text = await runCli(['init', '--remove-agents'], project);
+    expect(text.status).toBe(1);
+    expect(text.stderr).toMatch(/^Error: .*"CLAUDE\.md": resolves outside the project root/m);
+    expect(text.stdout).not.toMatch(/removed/i);
+
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(content);
+  }, 30_000);
+});

package/foundation/agent-docs/agent-docs.test.mjs

@@ -55,6 +55,15 @@ describe('generateCompressedIndex', () => {
     expect(frameRule).not.toMatch(/https?:/);
   });
 
+  it('starts every page from a template before any component', () => {
+    const lines = generateCompressedIndex('1.0.0').split('\n');
+    const workflow = lines.findIndex(l => l.startsWith('WORKFLOW'));
+    expect(lines[workflow]).toMatch(/start every page from a template/);
+    expect(lines[workflow + 1]).toMatch(/^1\. `astryx build /);
+    expect(lines[workflow + 2]).toMatch(/^2\. `astryx template <name> <path>`/);
+    expect(lines.join('\n')).not.toMatch(/reference code/);
+  });
+
   it('includes the post-generation self-check rule', () => {
     const result = generateCompressedIndex('1.0.0');
     expect(result).toContain('SELF-CHECK before you finish');
@@ -134,7 +143,6 @@ describe('generateCompressedIndex', () => {
     const line = topicLine(generateCompressedIndex('1.0.0'));
     for (const topic of [
       'getting-started',
-      'cli-integrations',
       'browser-support',
       'styling-libraries',
       'working-with-ai',
@@ -143,6 +151,16 @@ describe('generateCompressedIndex', () => {
     }
   });
 
+  it('points to the CLI docs tree on a line of its own', () => {
+    // The integration guide lives in the docs tree now (cli/integrations), so
+    // the topic line no longer names it; the tree's entry point does.
+    const block = generateCompressedIndex('1.0.0');
+    expect(block).toContain(
+      '  docs cli           commands, API reference, integration authoring (one level at a time)',
+    );
+    expect(topicLine(block)).not.toContain('cli-integrations');
+  });
+
   it('lists the topics it is given, so an integration’s reach the agent', () => {
     const line = topicLine(
       generateCompressedIndex('1.0.0', {topics: ['tokens', 'deploying']}),

package/foundation/config/integration-debug.test.mjs

@@ -63,11 +63,18 @@ function config(integrations, ownHandler = false) {
   );
 }
 
-/** @param {Record<string, unknown>} [astryx] */
-function packageJson(astryx) {
+/**
+ * @param {Record<string, unknown>} [astryx]
+ * @param {Record<string, string>} [dependencies]
+ */
+function packageJson(astryx, dependencies) {
   fs.writeFileSync(
     path.join(tmpDir, 'package.json'),
-    JSON.stringify({name: 'consumer', ...(astryx ? {astryx} : {})}),
+    JSON.stringify({
+      name: 'consumer',
+      ...(dependencies ? {dependencies} : {}),
+      ...(astryx ? {astryx} : {}),
+    }),
   );
 }
 
@@ -172,6 +179,24 @@ describe('an app can refuse an inherited handler', () => {
 
     expect(fired()).toEqual(['reporting-integration']);
   });
+
+  it('keeps an autolinked handler in a project with no astryx.config', async () => {
+    packageJson(undefined, {'reporting-integration': '1.0.0'});
+    integration('reporting-integration');
+
+    await runOneCommand();
+
+    expect(fired()).toEqual(['reporting-integration']);
+  });
+
+  it('drops an autolinked handler under astryx.inheritDebug false with no astryx.config', async () => {
+    packageJson({inheritDebug: false}, {'reporting-integration': '1.0.0'});
+    integration('reporting-integration');
+
+    await runOneCommand();
+
+    expect(fired()).toEqual([]);
+  });
 });
 
 describe('loading the project twice delivers once', () => {

package/foundation/config/project-themes.test.mjs

@@ -15,6 +15,7 @@ function installThemeIntegration(packageName, slug) {
     ...packageName.split('/'),
   );
   const themeDir = path.join(packageDir, 'themes', slug);
+  const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
   fs.mkdirSync(themeDir, {recursive: true});
   fs.writeFileSync(
     path.join(packageDir, 'package.json'),
@@ -22,28 +23,19 @@ function installThemeIntegration(packageName, slug) {
   );
   fs.writeFileSync(
     path.join(packageDir, 'astryx.integration.mjs'),
-    `export default {themes: './themes'};\n`,
+    `export default {themes: './themes'};
+`,
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug,
-          displayName: 'Ocean',
-          description: 'Blue and calm.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    }),
+    path.join(themeDir, `${stem}.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: '${slug}', displayName: 'Ocean', description: 'Blue and calm.', maintained: true};
+`,
   );
   fs.writeFileSync(
-    path.join(themeDir, 'oceanTheme.ts'),
-    `export const oceanTheme = {};\n`,
+    path.join(themeDir, `${stem}.ts`),
+    `export const ${stem} = {};
+`,
   );
 }
 
@@ -99,7 +91,7 @@ describe('Project themes', () => {
     ]);
   });
 
-  it('records an invalid integration theme catalog as an issue', async () => {
+  it('records an invalid integration theme descriptor as an issue', async () => {
     installThemeIntegration('@acme/themes', 'ocean');
     fs.rmSync(
       path.join(

package/foundation/config/project.d.mts

@@ -9,6 +9,14 @@
  * @returns {string|null}
  */
 export function findConfigPath(startDir?: string): string | null;
+/**
+ * The provider ledger a Project resolved at load: one outcome for every
+ * package directory configured, autolinked, or authored. Internal: upgrade
+ * resolves on top of it, and tests account for every candidate with it.
+ * @param {Project} project
+ * @returns {import('../integrations/provider-resolution.mjs').ProviderLedger}
+ */
+export function providerLedgerOf(project: Project): import("../integrations/provider-resolution.mjs").ProviderLedger;
 /**
  * An integration issue tagged with the owner package. The base
  * {@link import('../integrations/issue').AstryxIntegrationIssue} fields plus the
@@ -87,9 +95,9 @@ export class Project {
     /**
      * Core + integration component ownership records. Wraps
      * discoverOwnedComponents for core and discoverIntegrationComponents (via
-     * discoverOwnedComponents) for integrations, but applies the skip+warn
-     * policy per integration: a broken integration's components are skipped and
-     * its issues collected, never thrown. Memoized per instance.
+     * discoverOwnedComponents) for integrations. Invalid component records are
+     * omitted and reported; valid component siblings and other contribution kinds
+     * remain available. Memoized per instance.
      *
      * @returns {Promise<Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>>}
      */
@@ -102,10 +110,11 @@ export class Project {
         issuesUrl: string | undefined;
     }>>;
     /**
-     * Core + integration templates, type-tagged. Wraps discoverTemplates (core +
-     * external blocks) and discoverIntegrationTemplatesForOne per integration so
-     * a broken integration's templates are skipped and its issues collected.
-     * Memoized per instance.
+     * Core + integration templates, type-tagged, with valid integration
+     * replacements projected over their Core targets. Wraps raw template discovery
+     * (Core + external blocks) and discoverIntegrationTemplatesForOne per integration
+     * so unusable template files are reported and omitted while valid siblings
+     * remain available. Memoized per instance.
      *
      * @returns {Promise<Array<object>>}
      */
@@ -113,8 +122,8 @@ export class Project {
     /**
      * Bundled source themes plus themes contributed by installed integrations.
      * Each record keeps its package owner and source directory so callers can
-     * both list and copy it without reconstructing paths. A broken integration's
-     * themes are skipped under the same issue policy as every other kind.
+     * both list and copy it without reconstructing paths. A broken theme
+     * contribution is reported without hiding the package's other valid kinds.
      *
      * @returns {Promise<import('../discovery/theme-discovery.mjs').DiscoveredTheme[]>}
      */
@@ -137,8 +146,8 @@ export class Project {
     /**
      * Core registry transforms + integration codemods for an upgrade range.
      * Wraps getTransformsBetween (core) and discoverIntegrationCodemods /
-     * selectIntegrationCodemods (integrations). A broken integration's codemods
-     * are skipped (issue collected) rather than failing the whole resolution.
+     * selectIntegrationCodemods (integrations). An invalid codemod contribution
+     * is reported and omitted without hiding other valid contribution kinds.
      * Memoized per (from, to) key.
      *
      * @param {string} fromVersion exclusive lower bound