An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): preserve imported agent doc wrappers (#6164)
Joeye5b4571b003b
diff --git a/.changeset/preserve-agent-doc-imports.md b/.changeset/preserve-agent-doc-imports.mdnew file mode 100644index 0000000000..f75c892d63--- /dev/null+++ b/.changeset/preserve-agent-doc-imports.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] Preserve `@path` agent doc imports and remove previously duplicated managed blocks (#6164)++@josephfarinadiff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjsindex c0b466f4d4..f1bf28d492 100644--- a/packages/cli/foundation/agent-docs/agent-docs.mjs+++ b/packages/cli/foundation/agent-docs/agent-docs.mjs@@ -48,6 +48,65 @@ import {// clients/cli/index.mjs, tests) keep their `from './agent-docs.mjs'` paths.export {discoverAgentDocs, isAstryxInitialized};+/**+ * Find tool-specific files that import another detected agent doc.+ *+ * Claude's `@path` directive is a real include, so injecting the full managed+ * block beside it duplicates the same instructions. Only an import whose+ * normalized target is another known agent doc counts; prose mentions and+ * standalone files keep the normal initialization behavior. Import cycles have+ * no canonical owner, so their members also stay standalone.+ *+ * @param {string} targetDir+ * @param {string[]} agentDocs+ * @returns {Set<string>}+ */+function discoverAgentDocWrappers(targetDir, agentDocs) {+ const known = new Set(agentDocs.map(p => path.normalize(p)));+ /** @type {Map<string, Set<string>>} */+ const imports = new Map();++ for (const rel of agentDocs) {+ let content;+ try {+ content = fs.readFileSync(path.join(targetDir, rel), 'utf-8');+ } catch {+ continue;+ }++ const targets = new Set();+ for (const line of content.split(/\r?\n/)) {+ const match = /^\s*@([^\s]+)\s*$/.exec(line);+ if (match == null || path.isAbsolute(match[1])) continue;+ const imported = path.normalize(path.join(path.dirname(rel), match[1]));+ if (imported !== path.normalize(rel) && known.has(imported)) {+ targets.add(imported);+ }+ }+ if (targets.size > 0) imports.set(rel, targets);+ }++ /** @param {string} start */+ const isCyclic = start => {+ /**+ * @param {string} current+ * @param {Set<string>} seen+ */+ const visit = (current, seen) => {+ for (const imported of imports.get(current) ?? []) {+ if (imported === start) return true;+ if (seen.has(imported)) continue;+ seen.add(imported);+ if (visit(imported, seen)) return true;+ }+ return false;+ };+ return visit(start, new Set([start]));+ };++ return new Set([...imports.keys()].filter(rel => !isCyclic(rel)));+}+/*** Locate the single well-formed managed block in `content`.*@@ -532,8 +591,11 @@ export function removeAgentDocs(targetDir) {* Used by the init command, 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 AGENTS.md as default (tool-agnostic standard)+ * - Discover all existing agent doc files.+ * - Leave `@path` import wrappers untouched; if an older run expanded a block+ * into one, remove that duplicate block.+ * - Initialize or refresh every standalone file.+ * - If nothing exists, create AGENTS.md as the tool-agnostic default.** @param {string} targetDir* @param {object} [options]@@ -601,14 +663,31 @@ export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onlreturn written;}- // Auto-detect: update all existing agent doc files+ // Auto-detect: initialize standalone files, but do not expand the managed+ // block beside an `@path` import of another agent doc. Remove a block from a+ // wrapper if an older run already duplicated it there.const existing = discoverAgentDocs(targetDir);if (existing.length > 0) {- for (const p of existing) {+ const wrappers = discoverAgentDocWrappers(targetDir, existing);+ const targets = existing.filter(p => !wrappers.has(p));++ for (const p of targets) {const didWrite = injectXdsBlock(path.join(targetDir, p), compressedIndex, {onlyReplace});if (didWrite) written.push(p);}+ for (const p of wrappers) {+ const filePath = path.join(targetDir, p);+ if (removeXdsBlock(filePath)) {+ written.push(p);+ } else {+ const content = fs.readFileSync(filePath, 'utf-8');+ if (content.includes(MARKER_START) || content.includes(LEGACY_MARKER_START)) {+ // Preserve the existing fail-closed behavior for malformed blocks.+ injectXdsBlock(filePath, compressedIndex, {onlyReplace: true});+ }+ }+ }return written;}diff --git a/packages/cli/foundation/agent-docs/agent-docs.test.mjs b/packages/cli/foundation/agent-docs/agent-docs.test.mjsindex 91c691558f..340fd99e94 100644--- a/packages/cli/foundation/agent-docs/agent-docs.test.mjs+++ b/packages/cli/foundation/agent-docs/agent-docs.test.mjs@@ -504,6 +504,74 @@ describe('installAgentDocs', () => {expect(claudeContent).toContain('<!-- ASTRYX:START -->');});+ it('preserves import wrappers while initializing standalone files', () => {+ setupCorePackage(tmpDir);+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n');+ fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});+ const wrapperPath = path.join(tmpDir, '.claude', 'CLAUDE.md');+ const wrapper = '@../AGENTS.md\n';+ fs.writeFileSync(wrapperPath, wrapper);+ fs.writeFileSync(path.join(tmpDir, '.cursorrules'), 'Cursor rules.\n');++ const written = installAgentDocs(tmpDir);++ expect(written).toEqual(['AGENTS.md', '.cursorrules']);+ expect(fs.readFileSync(wrapperPath, 'utf-8')).toBe(wrapper);+ expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toContain(+ '<!-- ASTRYX:START -->',+ );+ expect(fs.readFileSync(path.join(tmpDir, '.cursorrules'), 'utf-8')).toContain(+ '<!-- ASTRYX:START -->',+ );+ });++ it('keeps cyclic imports standalone when another file exists', () => {+ setupCorePackage(tmpDir);+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '@CLAUDE.md\n');+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '@AGENTS.md\n');+ fs.writeFileSync(path.join(tmpDir, '.cursorrules'), 'Cursor rules.\n');++ const written = installAgentDocs(tmpDir);++ expect(written).toEqual(['AGENTS.md', 'CLAUDE.md', '.cursorrules']);+ for (const rel of written) {+ expect(fs.readFileSync(path.join(tmpDir, rel), 'utf-8')).toContain(+ '<!-- ASTRYX:START -->',+ );+ }+ });++ it('removes a managed block previously expanded into an import wrapper', () => {+ setupCorePackage(tmpDir);+ installAgentDocs(tmpDir, {agent: 'codex'});+ fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});+ const wrapperPath = path.join(tmpDir, '.claude', 'CLAUDE.md');+ const wrapper = '@../AGENTS.md\n';+ fs.writeFileSync(wrapperPath, wrapper);+ installAgentDocs(tmpDir, {agent: 'claude'});+ expect(fs.readFileSync(wrapperPath, 'utf-8')).toContain(+ '<!-- ASTRYX:START -->',+ );++ const written = installAgentDocs(tmpDir, {onlyReplace: true});++ expect(written).toContain('AGENTS.md');+ expect(written).toContain('.claude/CLAUDE.md');+ expect(fs.readFileSync(wrapperPath, 'utf-8')).toBe(wrapper);+ });++ it('refuses a malformed managed block inside an import wrapper', () => {+ setupCorePackage(tmpDir);+ installAgentDocs(tmpDir, {agent: 'codex'});+ fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});+ fs.writeFileSync(+ path.join(tmpDir, '.claude', 'CLAUDE.md'),+ '@../AGENTS.md\n<!-- ASTRYX:START -->\nincomplete\n',+ );++ expect(() => installAgentDocs(tmpDir)).toThrow(/malformed|no matching/i);+ });+it('updates existing .claude/CLAUDE.md', () => {setupCorePackage(tmpDir);fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});