Skip to content

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.md
new file mode 100644
index 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)
+
+@josephfarina
diff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjs
index 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, onl
return 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.mjs
index 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});