@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/commands/agent-docs.mjs

@@ -0,0 +1,545 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file agent-docs — Install/update agent docs for AI coding tools
+ *
+ * Generates a CLI cheat sheet from actual command metadata and injects
+ * it into agent doc files. Supports multiple tools with auto-detection:
+ *
+ * - Claude Code: CLAUDE.md (root) or .claude/CLAUDE.md
+ * - Cursor: .cursorrules
+ * - Codex/generic: AGENTS.md
+ *
+ * Auto-detect: discovers existing files and updates them in place.
+ * Default (no existing files): creates .claude/CLAUDE.md.
+ *
+ * --agent <tool>: target a specific tool preset (claude, cursor, codex, all)
+ * --agent-docs-path <path>: explicit file path(s)
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
+import {assertWithin, PathSafetyError} from '../utils/path-safety.mjs';
+import {getRunPrefix} from '../utils/package-manager.mjs';
+import {discoverComponents} from '../lib/component-discovery.mjs';
+import {humanLog} from '../lib/json.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+
+const AGENTS_MD = 'AGENTS.md';
+const CLAUDE_MD = 'CLAUDE.md';
+const CLAUDE_DIR_MD = path.join('.claude', 'CLAUDE.md');
+
+const MARKER_START = '<!-- ASTRYX:START -->';
+const MARKER_END = '<!-- ASTRYX:END -->';
+// Legacy markers — read during migration so the script finds existing XDS blocks
+const LEGACY_MARKER_START = '<!-- XDS:START -->';
+const LEGACY_MARKER_END = '<!-- XDS:END -->';
+
+/**
+ * Agent tool presets — maps tool names to their file search paths.
+ * Order matters: first existing file wins, last entry is the default (created if none exist).
+ */
+const AGENT_PRESETS = {
+  claude: [CLAUDE_MD, CLAUDE_DIR_MD],
+  cursor: ['.cursorrules', AGENTS_MD],
+  codex: [AGENTS_MD],
+};
+
+/**
+ * Find all existing agent doc files in a directory.
+ * Searches all known locations (AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, .cursorrules).
+ * @param {string} targetDir
+ * @returns {string[]} Relative paths of existing agent doc files
+ */
+export function discoverAgentDocs(targetDir) {
+  const allPaths = [AGENTS_MD, CLAUDE_MD, CLAUDE_DIR_MD, '.cursorrules'];
+  return allPaths.filter(p => fs.existsSync(path.join(targetDir, p)));
+}
+
+/**
+ * Resolve which file(s) to write for a given agent tool preset.
+ * Searches for existing files first, falls back to default creation path.
+ *
+ * @param {string} targetDir
+ * @param {string} agent - Preset name: 'claude', 'cursor', 'codex', 'all'
+ * @returns {{inject: string[], create: string[]}} Files to inject into vs create fresh
+ */
+export function resolveAgentPaths(targetDir, agent) {
+  if (agent === 'all') {
+    // Inject into all existing files, create defaults for each tool
+    const existing = discoverAgentDocs(targetDir);
+    if (existing.length > 0) {
+      return {inject: existing, create: []};
+    }
+    // Nothing exists — create default for each tool
+    return {inject: [], create: [AGENTS_MD, CLAUDE_DIR_MD]};
+  }
+
+  const searchPaths = AGENT_PRESETS[agent];
+  if (!searchPaths) {
+    return {inject: [], create: [AGENTS_MD]};
+  }
+
+  // Find first existing file from search order
+  for (const p of searchPaths) {
+    if (fs.existsSync(path.join(targetDir, p))) {
+      return {inject: [p], create: []};
+    }
+  }
+
+  // None found — create the last entry (default location)
+  return {inject: [], create: [searchPaths[searchPaths.length - 1]]};
+}
+
+/**
+ * Detect which styling system the consumer project has wired up, so the agent
+ * docs recommend a path that actually compiles in THIS project.
+ *
+ * `xstyle`/StyleX needs the StyleX compiler (the `@stylexjs/stylex` runtime
+ * alone throws at runtime → blank page); Tailwind utilities need Tailwind.
+ * Recommending either when it isn't configured yields unstyled or blank output.
+ * Plain CSS variables (via `style`/`className`) always work, so they're the
+ * safe default. Precedence: stylex (compiler wired) → tailwind → css.
+ *
+ * @param {string} targetDir
+ * @returns {'stylex' | 'tailwind' | 'css'}
+ */
+export function detectStylingSystem(targetDir) {
+  try {
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (!fs.existsSync(pkgPath)) return 'css';
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const deps = {...pkg.dependencies, ...pkg.devDependencies};
+    // Key off a StyleX *compiler* plugin — the runtime alone won't render.
+    const stylexCompilers = [
+      '@stylexjs/babel-plugin',
+      'vite-plugin-stylex',
+      'unplugin-stylex',
+      '@stylexswc/unplugin',
+      '@stylexswc/nextjs-plugin',
+      'stylex-webpack',
+    ];
+    if (stylexCompilers.some(d => d in deps)) return 'stylex';
+    if ('tailwindcss' in deps) return 'tailwind';
+    return 'css';
+  } catch {
+    // Best-effort: default to the universally-safe CSS-variable path.
+    return 'css';
+  }
+}
+
+/**
+ * Generate the agent cheat sheet from live CLI metadata.
+ *
+ * Structured as: workflow (behavioral) → rules (error prevention) → CLI reference.
+ * Templates are positioned first in the workflow to teach agents the
+ * "look at reference code" reflex before writing any UI.
+ *
+ * `stylingSystem` tailors the custom-styling guidance to what the project has
+ * configured (see {@link detectStylingSystem}) so the agent never reaches for a
+ * styling path that isn't compiled here.
+ */
+export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPrefix(), stylingSystem = 'css'} = {}) {
+  const run = `${runPrefix} astryx`;
+  const lines = [MARKER_START];
+
+  // Component count from live discovery
+  let componentCount = '90+';
+  if (coreDir) {
+    try {
+      const comps = discoverComponents(coreDir);
+      let total = 0;
+      for (const list of Object.values(comps)) total += list.length;
+      if (total > 0) componentCount = String(total);
+    } catch {
+      // Best-effort: component count is cosmetic; fall back to the default.
+    }
+  }
+
+  // Header — state the CLI prefix once; commands below are shown as `astryx <cmd>`.
+  lines.push(`Astryx v${version} · ${componentCount} components`);
+  lines.push(`CLI: run every command as \`${run} <cmd>\` (shown below as \`astryx ...\`).`);
+  lines.push('');
+
+  // Required setup — components ship precompiled CSS; without these imports
+  // everything renders unstyled. Theme is optional (a default ships in astryx.css).
+  lines.push('SETUP (once, in your app entry e.g. main.tsx) — without these, components render unstyled:');
+  lines.push('  import "@astryxdesign/core/reset.css";');
+  lines.push('  import "@astryxdesign/core/astryx.css";');
+  lines.push('');
+
+  // Workflow — `build` is the front door; discover before writing UI.
+  lines.push("WORKFLOW — discover, don't guess. Before writing UI:");
+  lines.push('1. `astryx build "<idea>"` — START HERE: returns a kit (closest [page] + [block]s + [component]s). No args = full playbook.');
+  lines.push('2. `astryx template <name> [--skeleton]` — scaffold the [page]/[block]s it named, or study their layout. Templates are reference code.');
+  lines.push('3. `astryx component <Name>` — props + examples for every component you use.');
+  lines.push('');
+
+  // Rules — the top error-preventers.
+  lines.push('RULES:');
+  lines.push('- No <div> — components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.');
+  // Styling guidance tailored to the project's configured system — never
+  // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
+  // utilities need Tailwind). Tokens are always the source of truth.
+  if (stylingSystem === 'stylex') {
+    lines.push('- Custom styling: component props first; else the xstyle prop / StyleX tokens (@astryxdesign/core/theme/tokens.stylex). No raw hex/px.');
+  } else if (stylingSystem === 'tailwind') {
+    lines.push('- Custom styling: component props first; else Tailwind utilities backed by tokens (bg-surface, text-primary, rounded-lg) via tailwind-theme.css. No raw hex/px.');
+  } else {
+    lines.push("- Custom styling: component props first; else style/className with tokens — var(--color-*|--spacing-*|--radius-*). No raw hex/px. (No StyleX/Tailwind compiler here — don't use xstyle/utility classes.)");
+  }
+  lines.push('- Tokens for every value (`astryx docs tokens`). Brand/accent via `astryx theme` — never override --color-* in :root.');
+  lines.push('');
+
+  // Command reference — build/template/component are covered in WORKFLOW above.
+  lines.push('MORE CLI:');
+  lines.push('  search "<query>"   find any component / hook / doc / template / block');
+  lines.push(`  component --list   ${componentCount} components by category`);
+  lines.push('  template --list    page + block recipes');
+  const docsDir = path.join(CLI_ROOT, 'docs');
+  if (fs.existsSync(docsDir)) {
+    const topics = fs.readdirSync(docsDir)
+      .map(f => f.match(/^(\w+)\.doc\.mjs$/))
+      .filter(Boolean)
+      .map(m => m[1])
+      .sort();
+    if (topics.length > 0) lines.push(`  docs <topic>       ${topics.join(', ')}`);
+  }
+  lines.push('  swizzle <Name>     eject component source (--gap reports why)');
+  lines.push('  upgrade --apply    run after any @astryxdesign/core bump');
+  lines.push(MARKER_END);
+
+  return lines.join('\n');
+}
+
+/**
+ * Get Astryx version from core package.
+ */
+export function getXdsVersion(coreDir) {
+  if (coreDir) {
+    const pkgPath = path.join(coreDir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      return pkg.version;
+    }
+  }
+  const cliPkgPath = path.join(CLI_ROOT, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(cliPkgPath, 'utf-8'));
+  return pkg.version;
+}
+
+/**
+ * Inject or update Astryx section in a file using Astryx markers.
+ * If the file has existing markers, replaces the content between them.
+ * If the file exists without markers, appends the block (unless onlyReplace is true).
+ * If createIfMissing is true and the file doesn't exist, creates it with a header.
+ *
+ * @param {string} filePath
+ * @param {string} compressedIndex
+ * @param {object} [options]
+ * @param {boolean} [options.createIfMissing] - Create the file if it doesn't exist
+ * @param {string} [options.header] - Header for newly created files
+ * @param {boolean} [options.onlyReplace] - Only write if Astryx markers already exist (skip files without markers)
+ * @returns {boolean} Whether the file was written
+ */
+export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = false, header = '', onlyReplace = false} = {}) {
+  let content;
+
+  if (fs.existsSync(filePath)) {
+    content = fs.readFileSync(filePath, 'utf-8');
+
+    // Find existing section — try new markers first, fall back to legacy XDS markers
+    let startIdx = content.indexOf(MARKER_START);
+    let endIdx = content.indexOf(MARKER_END);
+    let markerEndLength = MARKER_END.length;
+    if (startIdx === -1) {
+      startIdx = content.indexOf(LEGACY_MARKER_START);
+      endIdx = content.indexOf(LEGACY_MARKER_END);
+      markerEndLength = LEGACY_MARKER_END.length;
+    }
+
+    if (startIdx !== -1 && endIdx !== -1) {
+      content =
+        content.slice(0, startIdx) +
+        compressedIndex +
+        content.slice(endIdx + markerEndLength);
+    } else if (onlyReplace) {
+      // File exists but has no Astryx markers — skip it
+      return false;
+    } else {
+      content = content.trimEnd() + '\n\n' + compressedIndex + '\n';
+    }
+  } else if (createIfMissing) {
+    content = header ? header + '\n\n' + compressedIndex + '\n' : compressedIndex + '\n';
+  } else {
+    return false;
+  }
+
+  fs.writeFileSync(filePath, content);
+  return true;
+}
+
+/**
+ * Inject or update Astryx section in AGENTS.md.
+ * Always creates the file if it doesn't exist.
+ */
+export function injectAgentsMd(targetDir, version) {
+  const agentsPath = path.join(targetDir, AGENTS_MD);
+  const compressedIndex = generateCompressedIndex(version, {
+    coreDir: findCoreDir(targetDir),
+    stylingSystem: detectStylingSystem(targetDir),
+  });
+  injectXdsBlock(agentsPath, compressedIndex, {
+    createIfMissing: true,
+    header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,
+  });
+}
+
+/**
+ * Inject or update Astryx section in CLAUDE.md.
+ * Only injects if CLAUDE.md already exists.
+ *
+ * @returns {boolean} Whether the file was written
+ */
+export function injectClaudeMd(targetDir, version) {
+  const claudePath = path.join(targetDir, CLAUDE_MD);
+  const compressedIndex = generateCompressedIndex(version, {
+    coreDir: findCoreDir(targetDir),
+    stylingSystem: detectStylingSystem(targetDir),
+  });
+  return injectXdsBlock(claudePath, compressedIndex);
+}
+
+/**
+ * Remove Astryx section from a file.
+ * If the file becomes empty (only boilerplate header remains), deletes it.
+ *
+ * @returns {boolean} Whether the Astryx section was found and removed
+ */
+export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
+  if (!fs.existsSync(filePath)) return false;
+
+  let content = fs.readFileSync(filePath, 'utf-8');
+  // Find existing section — try new markers first, fall back to legacy
+  let startIdx = content.indexOf(MARKER_START);
+  let endIdx = content.indexOf(MARKER_END);
+  let markerEndLen = MARKER_END.length;
+  if (startIdx === -1) {
+    startIdx = content.indexOf(LEGACY_MARKER_START);
+    endIdx = content.indexOf(LEGACY_MARKER_END);
+    markerEndLen = LEGACY_MARKER_END.length;
+  }
+
+  if (startIdx === -1 || endIdx === -1) return false;
+
+  const before = content.slice(0, startIdx).trimEnd();
+  const after = content.slice(endIdx + markerEndLen).trimStart();
+  content = before + (after ? '\n\n' + after : '') + '\n';
+
+  if (deleteIfEmpty) {
+    const stripped = content.replace(/^#.*\n+.*guidance.*\n*/m, '').trim();
+    if (!stripped) {
+      fs.unlinkSync(filePath);
+      return true;
+    }
+  }
+
+  fs.writeFileSync(filePath, content);
+  return true;
+}
+
+/**
+ * Remove Astryx section from all known agent doc files.
+ */
+export function removeAgentDocs(targetDir) {
+  const allPaths = discoverAgentDocs(targetDir);
+
+  for (const p of allPaths) {
+    const filePath = path.join(targetDir, p);
+    // Delete if empty for files we created (AGENTS.md, .claude/CLAUDE.md)
+    const deleteIfEmpty = p === AGENTS_MD || p === CLAUDE_DIR_MD;
+    if (removeXdsBlock(filePath, {deleteIfEmpty})) {
+      if (!fs.existsSync(filePath)) {
+        humanLog(`✓ Removed empty ${p}`);
+      } else {
+        humanLog(`✓ Removed design system section from ${p}`);
+      }
+    }
+  }
+}
+
+/**
+ * Programmatic entry point for installing agent docs.
+ * Used by the init wizard, upgrade command, and agent-docs command.
+ *
+ * Strategy (when no agent/paths specified):
+ * - Discover all existing agent doc files and update them
+ * - If nothing found, create .claude/CLAUDE.md as default
+ *
+ * @param {string} targetDir
+ * @param {object} [options]
+ * @param {boolean} [options.zh]
+ * @param {string} [options.lang]
+ * @param {string} [options.agent] - Tool preset: 'claude', 'cursor', 'codex', 'all'
+ * @param {string[]} [options.paths] - Explicit paths (overrides agent/auto-detect)
+ * @param {boolean} [options.onlyReplace] - Only update files that already have Astryx markers (for upgrades)
+ * @returns {string[]} List of files written
+ */
+export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onlyReplace = false} = {}) {
+  const coreDir = findCoreDir(targetDir);
+  const version = getXdsVersion(coreDir);
+  const runPrefix = getRunPrefix(targetDir);
+  const stylingSystem = detectStylingSystem(targetDir);
+  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, runPrefix, stylingSystem});
+  const written = [];
+
+  // Explicit paths override everything
+  if (paths && paths.length > 0) {
+    // Path-safety: each --agent-docs-path entry must resolve inside the
+    // target directory. Reject absolute paths (silent re-rooting via
+    // path.join hides intent) and `..` traversal.
+    for (const p of paths) {
+      assertWithin(p, targetDir, {label: 'agent docs path'});
+    }
+    for (const p of paths) {
+      const filePath = path.join(targetDir, p);
+      const dir = path.dirname(filePath);
+      if (dir !== targetDir) {
+        fs.mkdirSync(dir, {recursive: true});
+      }
+      injectXdsBlock(filePath, compressedIndex, {
+        createIfMissing: true,
+        header: `# ${path.basename(p, path.extname(p))}\n\nProject-specific guidance for AI coding agents.`,
+      });
+      written.push(p);
+    }
+    return written;
+  }
+
+  // Agent preset
+  if (agent) {
+    const {inject, create} = resolveAgentPaths(targetDir, agent);
+    for (const p of inject) {
+      injectXdsBlock(path.join(targetDir, p), compressedIndex);
+      written.push(p);
+    }
+    for (const p of create) {
+      const filePath = path.join(targetDir, p);
+      const dir = path.dirname(filePath);
+      if (dir !== targetDir) {
+        fs.mkdirSync(dir, {recursive: true});
+      }
+      injectXdsBlock(filePath, compressedIndex, {
+        createIfMissing: true,
+        header: `# ${path.basename(p, path.extname(p))}\n\nProject-specific guidance for AI coding agents.`,
+      });
+      written.push(p);
+    }
+    return written;
+  }
+
+  // Auto-detect: update all existing agent doc files
+  const existing = discoverAgentDocs(targetDir);
+
+  if (existing.length > 0) {
+    for (const p of existing) {
+      const didWrite = injectXdsBlock(path.join(targetDir, p), compressedIndex, {onlyReplace});
+      if (didWrite) written.push(p);
+    }
+    return written;
+  }
+
+  // Nothing exists — create .claude/CLAUDE.md as default (skip if onlyReplace)
+  if (onlyReplace) return written;
+
+  const defaultPath = CLAUDE_DIR_MD;
+  fs.mkdirSync(path.join(targetDir, '.claude'), {recursive: true});
+  injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {
+    createIfMissing: true,
+    header: `# CLAUDE.md\n\nProject-specific guidance for AI coding agents.`,
+  });
+  written.push(defaultPath);
+  return written;
+}
+
+const VALID_AGENTS = ['claude', 'cursor', 'codex', 'all'];
+
+export function registerAgentDocs(program) {
+  program
+    .command('agent-docs')
+    .description('Install/update the component index for AI coding agents')
+    .option('--remove', 'Remove the design system section from all agent doc files')
+    .option('--agent <tool>', 'Target tool: claude, cursor, codex, all')
+    .option('--agent-docs-path <path...>', 'Explicit file path(s) to write to')
+    .action(options => {
+      const targetDir = process.cwd();
+      const coreDir = findCoreDir(targetDir);
+      const version = getXdsVersion(coreDir);
+      const zh = program.opts().zh || false;
+      const lang = program.opts().lang || null;
+
+      if (options.remove) {
+        humanLog('\n🗑️  Removing agent docs...\n');
+        removeAgentDocs(targetDir);
+        humanLog('\n✅ Agent docs removed.\n');
+        return;
+      }
+
+      // Validate --agent
+      if (options.agent && !VALID_AGENTS.includes(options.agent)) {
+        cliError(`Unknown agent "${options.agent}". Valid: ${VALID_AGENTS.join(', ')}`, {code: ERROR_CODES.ERR_UNKNOWN_AGENT});
+        return;
+      }
+
+      humanLog(`\n📚 Installing agent docs (v${version})...\n`);
+
+      // Collect explicit paths from --agent-docs-path (commander parses variadic as array or single)
+      const explicitPaths = options.agentDocsPath
+        ? Array.isArray(options.agentDocsPath)
+          ? options.agentDocsPath
+          : [options.agentDocsPath]
+        : undefined;
+
+      let targets;
+      try {
+        targets = installAgentDocs(targetDir, {
+          zh,
+          lang,
+          agent: options.agent,
+          paths: explicitPaths,
+        });
+      } catch (err) {
+        if (err instanceof PathSafetyError) {
+          cliError(err.message, {code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+          return;
+        }
+        throw err;
+      }
+
+      const runPrefix = getRunPrefix(targetDir);
+      const run = `${runPrefix} astryx`;
+
+      for (const t of targets) {
+        humanLog(`✓ ${t}`);
+      }
+
+      humanLog(`
+✅ Agent docs installed!
+
+Your AI coding agent will now:
+  • See the component index in ${targets.join(' and ')}
+  • Run \`${run} component <name>\` to read detailed docs
+  • Run \`${run} docs principles\` for design principles
+  • Run \`${run} docs tokens\` for design token reference
+  • Follow design system patterns and avoid anti-patterns
+
+To update:
+  ${run} agent-docs
+
+To remove:
+  ${run} agent-docs --remove
+`);
+    });
+}

package/src/commands/agent-docs.path-safety.test.mjs

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Path-safety regression tests for `--agent-docs-path`.
+ *
+ * `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.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} 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 {PathSafetyError} from '../utils/path-safety.mjs';
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-paths-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('installAgentDocs path safety', () => {
+  it('rejects --agent-docs-path that escapes the target directory', () => {
+    const target = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(target, {recursive: true});
+    fs.mkdirSync(outside, {recursive: true});
+
+    expect(() =>
+      installAgentDocs(target, {paths: ['../OUT.md']}),
+    ).toThrow(PathSafetyError);
+
+    expect(fs.existsSync(path.join(tmpDir, 'OUT.md'))).toBe(false);
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('rejects an absolute --agent-docs-path with a clear error', () => {
+    const target = path.join(tmpDir, 'project');
+    fs.mkdirSync(target, {recursive: true});
+    const absPath = path.join(tmpDir, 'absolute.md');
+
+    expect(() =>
+      installAgentDocs(target, {paths: [absPath]}),
+    ).toThrow(/absolute paths are not allowed/i);
+
+    expect(fs.existsSync(absPath)).toBe(false);
+  });
+
+  it('rejects deeper traversal segments', () => {
+    const target = path.join(tmpDir, 'a', 'b', 'c');
+    fs.mkdirSync(target, {recursive: true});
+
+    expect(() =>
+      installAgentDocs(target, {paths: ['../../../escaped.md']}),
+    ).toThrow(PathSafetyError);
+
+    expect(fs.existsSync(path.join(tmpDir, 'escaped.md'))).toBe(false);
+  });
+});