An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @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`
*
* 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. A file
* only the current layout writes (GEMINI.md) that links outside is skipped and
* reported instead, and the rest is written, so init keeps 0.7.0's exit code.
*
* `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, vi} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
import {spawnSync} from 'node:child_process';
import {
installAgentDocs,
removeAgentDocs,
removeXdsBlock,
} from './agent-docs.mjs';
import {PathSafetyError} from '../fs/path-safety.mjs';
import {runCli} from '../../test-utils/run-cli.mjs';
import {doc as initDoc} from '../../clients/cli/commands/init.doc.mjs';
const BLOCK = '<!-- ASTRYX:START -->\nmanaged\n<!-- ASTRYX:END -->';
let tmpDir;
beforeEach(() => {
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-paths-'));
});
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');
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);
});
});
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');
expect(fs.readdirSync(project)).toEqual(['CLAUDE.md']);
});
it('skips a GEMINI.md that links outside, reports it, and writes the rest', () => {
const {project, outside} = layout();
const shared = path.join(outside, 'GEMINI.md');
fs.writeFileSync(shared, '# Shared\n');
fs.symlinkSync(shared, path.join(project, 'GEMINI.md'));
/** @type {Array<[string, string]>} */
const skipped = [];
expect(
installAgentDocs(project, {
renderedBlock: BLOCK,
onSkipped: (rel, reason) => skipped.push([rel, reason]),
}),
).toEqual(['AGENTS.md']);
expect(skipped).toEqual([
['GEMINI.md', expect.stringMatching(/outside the project root/)],
]);
expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
});
it('leaves a .claude folder that links outside alone when root CLAUDE.md holds the copy', () => {
const {project, outside} = layout();
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Claude\n');
fs.symlinkSync(outside, path.join(project, '.claude'));
expect(installAgentDocs(project, {renderedBlock: BLOCK})).toEqual([
'AGENTS.md',
'CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readdirSync(outside)).toEqual([]);
// A CLAUDE.md in the linked folder with no block is not written either.
fs.writeFileSync(path.join(outside, 'CLAUDE.md'), '# Shared\n');
expect(installAgentDocs(project, {renderedBlock: BLOCK})).toEqual([
'AGENTS.md',
'CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), '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'));
// CLAUDE.md is AGENTS.md under another name, so it already has the block.
expect(installAgentDocs(project, {renderedBlock: BLOCK})).toEqual([
'AGENTS.md',
'GEMINI.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);
it('a GEMINI.md linked outside is skipped and reported, and init exits 0', 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, 'GEMINI.md');
fs.writeFileSync(shared, '# Shared\n');
fs.symlinkSync(shared, path.join(project, 'GEMINI.md'));
const json = await runCli(
['init', '--features', 'agents', '--json'],
project,
);
expect(json.status).toBe(0);
const env = JSON.parse(json.stdout);
expect(env.data.docsWritten).toEqual(['AGENTS.md']);
expect(env.data.docsError).toEqual({
kind: 'install-failed',
message: expect.stringMatching(
/^Left as it is: GEMINI\.md \(.*outside the project root/,
),
});
const text = await runCli(['init', '--features', 'agents'], project);
expect(text.status).toBe(0);
expect(text.stderr).toMatch(/^Note: Left as it is: GEMINI\.md/m);
expect(text.stderr).not.toMatch(/Error:/);
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);
});
describe('the managed block is written whatever ignore rules or generated markers say (INV31)', () => {
/** @param {string} project @param {object} [options] */
const run = (project, options = {}) => {
/** @type {Array<[string, string]>} */
const skipped = [];
const written = installAgentDocs(project, {
renderedBlock: BLOCK,
onSkipped: (rel, reason) => skipped.push([rel, reason]),
...options,
});
return {written, skipped};
};
const OLD_BLOCK = '<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->';
it('creates AGENTS.md and the GEMINI.md import even when ignore rules cover them', () => {
const {project} = layout();
fs.writeFileSync(
path.join(project, '.gitignore'),
'AGENTS.md\nGEMINI.md\n',
);
const {written, skipped} = run(project);
expect(written).toEqual(['AGENTS.md', 'GEMINI.md']);
expect(skipped).toEqual([]);
expect(fs.readFileSync(path.join(project, 'GEMINI.md'), 'utf-8')).toContain(
'@./AGENTS.md',
);
});
it('adds the import to an ignored GEMINI.md and keeps its text', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), 'GEMINI.md\n');
fs.writeFileSync(path.join(project, 'GEMINI.md'), '# My Gemini notes\n');
const {written, skipped} = run(project);
expect(written).toEqual(['AGENTS.md', 'GEMINI.md']);
expect(skipped).toEqual([]);
const gemini = fs.readFileSync(path.join(project, 'GEMINI.md'), 'utf-8');
expect(gemini).toMatch(/^# My Gemini notes\n/u);
expect(gemini).toContain('@./AGENTS.md');
});
it('adds the import to a GEMINI.md marked generated and keeps the marker', () => {
const {project} = layout();
fs.writeFileSync(
path.join(project, 'GEMINI.md'),
'<!-- @generated by tool -->\n# Gemini\n',
);
const {written} = run(project);
expect(written).toEqual(['AGENTS.md', 'GEMINI.md']);
const gemini = fs.readFileSync(path.join(project, 'GEMINI.md'), 'utf-8');
expect(gemini).toMatch(/^<!-- @generated by tool -->\n# Gemini\n/u);
expect(gemini).toContain('@./AGENTS.md');
});
it("writes the copy into an ignored .claude/CLAUDE.md beside the user's text", () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), '.claude/\n');
fs.mkdirSync(path.join(project, '.claude'));
const claude = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(claude, `# Mine\n\n${OLD_BLOCK}\n\nMore.\n`);
const {written, skipped} = run(project);
expect(written).toEqual(['AGENTS.md', '.claude/CLAUDE.md', 'GEMINI.md']);
expect(skipped).toEqual([]);
expect(fs.readFileSync(claude, 'utf-8')).toBe(
`# Mine\n\n${BLOCK}\n\nMore.\n`,
);
expect(fs.readdirSync(path.join(project, '.claude'))).toEqual([
'CLAUDE.md',
]);
});
it('still refuses a .claude/CLAUDE.md linked outside the project (INV10)', () => {
const {project, outside} = layout();
const shared = path.join(outside, 'CLAUDE.md');
fs.writeFileSync(shared, `${OLD_BLOCK}\n`);
fs.mkdirSync(path.join(project, '.claude'));
fs.symlinkSync(shared, path.join(project, '.claude', 'CLAUDE.md'));
expect(() => run(project)).toThrow(/outside the project root/u);
expect(fs.readFileSync(shared, 'utf-8')).toBe(`${OLD_BLOCK}\n`);
});
it('--agent claude creates .claude/CLAUDE.md as its option says, even in an ignored .claude', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), '.claude/\n');
const {written, skipped} = run(project, {agent: 'claude'});
expect(written).toEqual(['.claude/CLAUDE.md']);
expect(skipped).toEqual([]);
expect(
fs.readFileSync(path.join(project, '.claude', 'CLAUDE.md'), 'utf-8'),
).toContain(BLOCK);
});
it('creates the .claude folder for --agent claude in a plain project', () => {
const {project} = layout();
expect(
installAgentDocs(project, {agent: 'claude', renderedBlock: BLOCK}),
).toEqual(['.claude/CLAUDE.md']);
expect(fs.existsSync(path.join(project, '.claude', 'CLAUDE.md'))).toBe(
true,
);
});
});
describe('a project with its own layout (INV31)', () => {
it('gives a standalone GEMINI.md that imports no agent file a copy', () => {
const {project} = layout();
// AGENTS.md imports CLAUDE.md, so the project keeps its own layout.
fs.writeFileSync(path.join(project, 'AGENTS.md'), '@CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Claude\n');
fs.writeFileSync(path.join(project, 'GEMINI.md'), '# Gemini\n');
const written = installAgentDocs(project, {renderedBlock: BLOCK});
expect(written).toContain('GEMINI.md');
expect(fs.readFileSync(path.join(project, 'GEMINI.md'), 'utf-8')).toContain(
BLOCK,
);
expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
'@CLAUDE.md\n',
);
});
});
describe('a GEMINI.md linked outside in its own layout, and an ignored root CLAUDE.md', () => {
it('skips a GEMINI.md linked outside in a project with its own layout, and writes the rest', async () => {
const {project, outside} = layout();
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
// AGENTS.md imports CLAUDE.md, so the project keeps its own layout.
fs.writeFileSync(path.join(project, 'AGENTS.md'), '@CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Claude\n');
const shared = path.join(outside, 'GEMINI.md');
fs.writeFileSync(shared, '# Shared\n');
fs.symlinkSync(shared, path.join(project, 'GEMINI.md'));
/** @type {Array<[string, string]>} */
const skipped = [];
const written = installAgentDocs(project, {
renderedBlock: BLOCK,
onSkipped: (rel, reason) => skipped.push([rel, reason]),
});
expect(written).toEqual(['CLAUDE.md']);
expect(skipped).toEqual([
['GEMINI.md', expect.stringMatching(/outside the project root/u)],
]);
expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
const text = await runCli(['init', '--features', 'agents'], project);
expect(text.status).toBe(0);
expect(text.stderr).toMatch(/^Note: Left as it is: GEMINI\.md/mu);
expect(text.stderr).not.toMatch(/Error:/u);
expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
}, 30_000);
it('keeps, and refreshes, the committed .claude/CLAUDE.md copy while root CLAUDE.md is ignored', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
fs.writeFileSync(
path.join(project, 'CLAUDE.md'),
'# CLAUDE\n\nProject-specific guidance for AI coding agents.\n\n<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->\n',
);
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(
copy,
'# Team\n\n<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->\n',
);
const written = installAgentDocs(project, {renderedBlock: BLOCK});
expect(written).toEqual([
'AGENTS.md',
'CLAUDE.md',
'.claude/CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
expect(fs.readFileSync(path.join(project, 'CLAUDE.md'), 'utf-8')).toContain(
BLOCK,
);
// The same with the user's own text in the ignored root CLAUDE.md.
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
installAgentDocs(project, {renderedBlock: BLOCK});
expect(fs.readFileSync(path.join(project, 'CLAUDE.md'), 'utf-8')).toBe(
`# Mine\n\n${BLOCK}\n`,
);
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
// --agent claude keeps it too.
installAgentDocs(project, {agent: 'claude', renderedBlock: BLOCK});
expect(fs.readFileSync(copy, 'utf-8')).toContain(BLOCK);
});
});
describe('third astracat round: first-run copy beside an ignored root, escapes below the root', () => {
it('puts the copy in a committed .claude/CLAUDE.md on the first run while root CLAUDE.md is ignored', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, '# Team\n');
const written = installAgentDocs(project, {renderedBlock: BLOCK});
expect(written).toEqual([
'AGENTS.md',
'CLAUDE.md',
'.claude/CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
});
it('gives .claude/CLAUDE.md no copy on the first run when it is ignored too', () => {
const {project} = layout();
fs.writeFileSync(
path.join(project, '.gitignore'),
'/CLAUDE.md\n.claude/\n',
);
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, '# Team\n');
expect(installAgentDocs(project, {renderedBlock: BLOCK})).toEqual([
'AGENTS.md',
'CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readFileSync(copy, 'utf-8')).toBe('# Team\n');
});
it('--agent all writes .claude/CLAUDE.md beside an ignored root CLAUDE.md', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, '# Team\n');
const written = installAgentDocs(project, {
agent: 'all',
renderedBlock: BLOCK,
});
expect(written).toEqual(
expect.arrayContaining(['CLAUDE.md', '.claude/CLAUDE.md']),
);
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
});
it('run from a subfolder, skips a root CLAUDE.md linked outside with a note and exits 0', async () => {
const {project, outside} = layout();
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 sub = path.join(project, 'src');
fs.mkdirSync(sub);
const json = await runCli(['init', '--features', 'agents', '--json'], sub);
expect(json.status).toBe(0);
const {data} = JSON.parse(json.stdout);
expect(data.docsWritten).toEqual(['../AGENTS.md', '../GEMINI.md']);
expect(data.docsError).toEqual({
kind: 'install-failed',
message: expect.stringMatching(
/^Left as it is: CLAUDE\.md \(.*outside the project root/u,
),
});
const text = await runCli(['init', '--features', 'agents'], sub);
expect(text.status).toBe(0);
expect(text.stderr).toMatch(/^Note: Left as it is: CLAUDE\.md/mu);
expect(text.stderr).not.toMatch(/Error:/u);
expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
// Run at the root, where 0.7.1 wrote it too, the escape still exits 1.
const atRoot = await runCli(['init', '--features', 'agents'], project);
expect(atRoot.status).toBe(1);
expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
}, 60_000);
});
describe('a monorepo package whose CLAUDE.md the repository root ignores', () => {
it.skipIf(spawnSync('git', ['--version']).status !== 0)(
'keeps and refreshes the committed .claude/CLAUDE.md copy',
() => {
const repo = path.join(tmpDir, 'repo');
const project = path.join(repo, 'apps', 'web');
fs.mkdirSync(repo, {recursive: true});
spawnSync('git', ['init', '-q'], {cwd: repo});
fs.mkdirSync(path.join(project, '.claude'), {recursive: true});
fs.writeFileSync(path.join(repo, '.gitignore'), 'apps/web/CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"web"}\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(
copy,
'# Team\n\n<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->\n',
);
const written = installAgentDocs(project, {renderedBlock: BLOCK});
expect(written).toEqual([
'AGENTS.md',
'CLAUDE.md',
'.claude/CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
// Without the repository-root rule, the copy moves to root CLAUDE.md.
fs.writeFileSync(path.join(repo, '.gitignore'), '');
installAgentDocs(project, {renderedBlock: BLOCK});
expect(fs.readFileSync(copy, 'utf-8')).toBe('# Team\n');
},
);
});
describe('a Mercurial monorepo whose root .hgignore excludes the package CLAUDE.md', () => {
for (const [label, rules] of [
['glob syntax', 'syntax: glob\napps/web/CLAUDE.md\n'],
['regexp syntax', '^apps/web/CLAUDE\\.md$\n'],
]) {
it(`keeps the committed .claude/CLAUDE.md copy (${label})`, () => {
const repo = path.join(tmpDir, 'hgrepo');
const project = path.join(repo, 'apps', 'web');
fs.mkdirSync(path.join(repo, '.hg'), {recursive: true});
fs.mkdirSync(path.join(project, '.claude'), {recursive: true});
fs.writeFileSync(path.join(repo, '.hgignore'), rules);
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"web"}\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, '# Team\n');
const written = installAgentDocs(project, {renderedBlock: BLOCK});
expect(written).toEqual([
'AGENTS.md',
'CLAUDE.md',
'.claude/CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
});
}
/**
* Run `fn` with a search path holding only `tools`: name to the shell
* script body that stands in for it, or null for a real command found on
* the current search path. A tool left out cannot be found.
* @param {Record<string, string | null>} tools
* @param {() => void} fn
*/
function withTools(tools, fn) {
const bin = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-tools-'));
const saved = process.env.PATH;
try {
for (const [name, body] of Object.entries(tools)) {
const file = path.join(bin, name);
if (body == null) {
const real = spawnSync('sh', ['-c', `command -v ${name}`], {
encoding: 'utf-8',
}).stdout.trim();
fs.symlinkSync(real, file);
} else {
fs.writeFileSync(file, `#!/bin/sh\n${body}\n`, {mode: 0o755});
}
}
process.env.PATH = bin;
fn();
} finally {
process.env.PATH = saved;
fs.rmSync(bin, {recursive: true, force: true});
}
}
/** A Mercurial monorepo whose package keeps a committed .claude copy. */
function hgProject() {
const repo = fs.mkdtempSync(path.join(tmpDir, 'hgrepo-'));
const project = path.join(repo, 'apps', 'web');
fs.mkdirSync(path.join(repo, '.hg'), {recursive: true});
fs.mkdirSync(path.join(project, '.claude'), {recursive: true});
fs.writeFileSync(
path.join(repo, '.hgignore'),
'syntax: glob\napps/web/CLAUDE.md\n',
);
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"web"}\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(
copy,
'# Team\n\n<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->\n',
);
return {project, copy};
}
it.skipIf(process.platform === 'win32').each([
['hg is not installed', {}],
['hg fails', {hg: 'exit 255'}],
['hg exits with a code it does not document', {hg: 'exit 2'}],
])(
'keeps the copy when the repository cannot answer: %s (fails closed)',
(_label, tools) => {
const {project, copy} = hgProject();
withTools(tools, () => installAgentDocs(project, {renderedBlock: BLOCK}));
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
},
);
it.skipIf(process.platform === 'win32')(
'follows the repository when it answers: a root CLAUDE.md it does not list as ignored moves the copy',
() => {
const {project, copy} = hgProject();
// hg answers, and lists nothing as untracked and ignored.
withTools({hg: 'exit 0'}, () =>
installAgentDocs(project, {renderedBlock: BLOCK}),
);
expect(fs.readFileSync(copy, 'utf-8').trimEnd()).toBe('# Team');
},
);
});
describe('below the project root, an AGENTS.md left as it is', () => {
it('skips the GEMINI.md import of it too (no import for doctor to fail on) and names both in one note', async () => {
const {project, outside} = layout();
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
const shared = path.join(outside, 'AGENTS.md');
fs.writeFileSync(shared, '# Shared\n');
fs.symlinkSync(shared, path.join(project, 'AGENTS.md'));
const sub = path.join(project, 'src');
fs.mkdirSync(sub);
const json = await runCli(['init', '--features', 'agents', '--json'], sub);
expect(json.status).toBe(0);
const {data} = JSON.parse(json.stdout);
expect(data.docsWritten).toEqual([]);
expect(data.docsError.message).toMatch(
/^Left as they are: AGENTS\.md \(.*outside the project root.*\); GEMINI\.md \(its import of AGENTS\.md/u,
);
expect(fs.existsSync(path.join(project, 'GEMINI.md'))).toBe(false);
const text = await runCli(['init', '--features', 'agents'], sub);
expect(text.status).toBe(0);
expect(text.stderr.split('\n').filter(Boolean)).toEqual([
expect.stringMatching(
/^Note: Left as they are: AGENTS\.md .*; GEMINI\.md /u,
),
]);
expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
}, 60_000);
});
describe('round 6: an ignored .claude/CLAUDE.md follows the usual rule; --agent claude refreshes a kept copy', () => {
const OLD = '<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->';
it('strips the block from an ignored .claude/CLAUDE.md once the ignored root CLAUDE.md holds it', () => {
const {project} = layout();
fs.writeFileSync(
path.join(project, '.gitignore'),
'/CLAUDE.md\n.claude/\n',
);
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, `# Team\n\n${OLD}\n`);
const written = installAgentDocs(project, {renderedBlock: BLOCK});
expect(written).toEqual([
'AGENTS.md',
'CLAUDE.md',
'.claude/CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readFileSync(copy, 'utf-8').trimEnd()).toBe('# Team');
expect(fs.readFileSync(path.join(project, 'CLAUDE.md'), 'utf-8')).toContain(
BLOCK,
);
// --agent claude follows the same rule.
fs.writeFileSync(copy, `# Team\n\n${OLD}\n`);
installAgentDocs(project, {agent: 'claude', renderedBlock: BLOCK});
expect(fs.readFileSync(copy, 'utf-8').trimEnd()).toBe('# Team');
});
it('keeps and refreshes a committed .claude/CLAUDE.md block with --agent claude beside an ignored root', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, `# Team\n\n${OLD}\n`);
const written = installAgentDocs(project, {
agent: 'claude',
renderedBlock: BLOCK,
});
expect(written).toEqual(['CLAUDE.md', '.claude/CLAUDE.md']);
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
expect(fs.readFileSync(path.join(project, 'CLAUDE.md'), 'utf-8')).toBe(
`# Mine\n\n${BLOCK}\n`,
);
});
it('--agent claude writes the committed .claude/CLAUDE.md copy on a first run beside an ignored root', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, '# Team\n');
const written = installAgentDocs(project, {
agent: 'claude',
renderedBlock: BLOCK,
});
expect(written).toEqual(['CLAUDE.md', '.claude/CLAUDE.md']);
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
});
it('--agent claude creates no .claude/CLAUDE.md beside an ignored root when there is none', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
expect(
installAgentDocs(project, {agent: 'claude', renderedBlock: BLOCK}),
).toEqual(['CLAUDE.md']);
expect(fs.existsSync(path.join(project, '.claude'))).toBe(false);
});
});
describe('round 8: refreshing a committed .claude copy that imports AGENTS.md; a linked .claude with --agent claude', () => {
it('refreshes a committed .claude/CLAUDE.md that imports AGENTS.md beside an ignored root', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, '@../AGENTS.md\n');
const OLD = '<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->';
installAgentDocs(project, {renderedBlock: OLD});
expect(fs.readFileSync(copy, 'utf-8')).toBe(`@../AGENTS.md\n\n${OLD}\n`);
// An upgrade's refresh, twice: the copy follows the installed release.
for (let round = 0; round < 2; round++) {
const written = installAgentDocs(project, {
onlyReplace: true,
renderedBlock: BLOCK,
});
if (round === 0) expect(written).toContain('.claude/CLAUDE.md');
expect(fs.readFileSync(copy, 'utf-8')).toBe(
`@../AGENTS.md\n\n${BLOCK}\n`,
);
}
});
it('refreshes a kept .claude/CLAUDE.md copy in a project with its own layout', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
// AGENTS.md imports CLAUDE.md, so the project keeps its own layout.
fs.writeFileSync(path.join(project, 'AGENTS.md'), '@CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(
copy,
'@../CLAUDE.md\n\n<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->\n',
);
installAgentDocs(project, {renderedBlock: BLOCK});
expect(fs.readFileSync(copy, 'utf-8')).toBe(`@../CLAUDE.md\n\n${BLOCK}\n`);
});
it('skips a linked-outside block-less import of an existing AGENTS.md (the shape 0.7.x left alone), with a note, exit 0', async () => {
const {project, outside} = layout();
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'AGENTS.md'), '# Agents\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.writeFileSync(path.join(outside, 'CLAUDE.md'), '@../AGENTS.md\n');
fs.symlinkSync(outside, path.join(project, '.claude'), 'dir');
/** @type {Array<[string, string]>} */
const skipped = [];
const written = installAgentDocs(project, {
renderedBlock: BLOCK,
onSkipped: (rel, reason) => skipped.push([rel, reason]),
});
expect(written).toEqual(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
expect(skipped).toEqual([
['.claude/CLAUDE.md', expect.stringMatching(/outside the project root/u)],
]);
expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), 'utf-8')).toBe(
'@../AGENTS.md\n',
);
const text = await runCli(['init', '--features', 'agents'], project);
expect(text.status).toBe(0);
expect(text.stderr).toMatch(/^Note: Left as it is: \.claude\/CLAUDE\.md/mu);
expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), 'utf-8')).toBe(
'@../AGENTS.md\n',
);
}, 30_000);
for (const [label, contents, withAgents] of [
['plain text', '# Shared\n', true],
['a block', '<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->\n', true],
['an import made before AGENTS.md exists', '@../AGENTS.md\n', false],
]) {
it(`still refuses a linked-outside .claude/CLAUDE.md that 0.7.x wrote (${label}): exit 1, nothing written`, async () => {
const {project, outside} = layout();
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
if (withAgents)
fs.writeFileSync(path.join(project, 'AGENTS.md'), '# Agents\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.writeFileSync(path.join(outside, 'CLAUDE.md'), contents);
fs.symlinkSync(outside, path.join(project, '.claude'), 'dir');
const before = fs.readdirSync(project).sort();
const r = await runCli(
['init', '--features', 'agents', '--json'],
project,
);
expect(r.status).toBe(1);
expect(JSON.parse(r.stdout).data.docsError.kind).toBe('path-safety');
expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), 'utf-8')).toBe(
contents,
);
expect(fs.readFileSync(path.join(project, 'CLAUDE.md'), 'utf-8')).toBe(
'# Mine\n',
);
expect(fs.readdirSync(project).sort()).toEqual(before);
}, 30_000);
}
it('--agent claude skips a .claude linked outside beside an ignored root, with a note, and writes CLAUDE.md', async () => {
const {project, outside} = layout();
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.writeFileSync(path.join(outside, 'CLAUDE.md'), '# Shared\n');
fs.symlinkSync(outside, path.join(project, '.claude'), 'dir');
/** @type {Array<[string, string]>} */
const skipped = [];
const written = installAgentDocs(project, {
agent: 'claude',
renderedBlock: BLOCK,
onSkipped: (rel, reason) => skipped.push([rel, reason]),
});
expect(written).toEqual(['CLAUDE.md']);
expect(skipped).toEqual([
['.claude/CLAUDE.md', expect.stringMatching(/outside the project root/u)],
]);
expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), 'utf-8')).toBe(
'# Shared\n',
);
const text = await runCli(
['init', '--features', 'agents', '--agent', 'claude'],
project,
);
expect(text.status).toBe(0);
expect(text.stderr).toMatch(/^Note: Left as it is: \.claude\/CLAUDE\.md/mu);
expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), 'utf-8')).toBe(
'# Shared\n',
);
}, 30_000);
});
describe('--agent claude beside a committed CLAUDE.md, with .claude linked outside and holding a block', () => {
it('writes CLAUDE.md, skips the .claude/CLAUDE.md block removal with a note, and exits 0, as 0.7.1 did', async () => {
const {project, outside} = layout();
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
const body = '# Team\n\n<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->\n';
fs.writeFileSync(path.join(outside, 'CLAUDE.md'), body);
fs.symlinkSync(outside, path.join(project, '.claude'), 'dir');
const r = await runCli(
['init', '--features', 'agents', '--agent', 'claude', '--json'],
project,
);
expect(r.status).toBe(0);
const {data} = JSON.parse(r.stdout);
expect(data.docsWritten).toEqual(['CLAUDE.md']);
expect(data.docsError.message).toMatch(
/^Left as it is: \.claude\/CLAUDE\.md \(.*outside the project root/u,
);
expect(fs.readFileSync(path.join(project, 'CLAUDE.md'), 'utf-8')).toContain(
BLOCK.split('\n')[0],
);
expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), 'utf-8')).toBe(
body,
);
}, 30_000);
});
describe('a .claude folder linked outside the project: exit parity with 0.7.1 at the project root', () => {
// Each row: preset, root CLAUDE.md (none, committed, or ignored), what the
// linked .claude/CLAUDE.md holds (plain text, a block, or a block-less import
// of AGENTS.md), and the exit (1 = the run refused, nothing written). Each
// matches 0.7.1, checked across every preset, layout, root state, linked
// .claude, AGENTS.md and GEMINI.md combination, except the three rows marked
// `0.7.1: 1`: there 0.7.1 wrote the linked .claude/CLAUDE.md and refused,
// while root CLAUDE.md now holds the copy and .claude/CLAUDE.md gets none, so
// nothing is written outside and nothing is refused.
const OLD = '<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->';
const BODY = {
plain: '# Team\n',
block: `# Team\n\n${OLD}\n`,
import: '@../AGENTS.md\n',
};
for (const [preset, root, dir, exit] of /** @type {const} */ ([
['default', 'none', 'plain', 1],
['default', 'none', 'block', 1],
['default', 'none', 'import', 0],
['default', 'committed', 'plain', 0] /* 0.7.1: 1 */,
['default', 'committed', 'block', 1],
['default', 'committed', 'import', 0],
['default', 'ignored', 'plain', 1],
['default', 'ignored', 'block', 1],
['default', 'ignored', 'import', 0],
['claude', 'none', 'plain', 1],
['claude', 'none', 'block', 1],
['claude', 'none', 'import', 1],
['claude', 'committed', 'plain', 0],
['claude', 'committed', 'block', 0],
['claude', 'committed', 'import', 0],
['claude', 'ignored', 'plain', 0],
['claude', 'ignored', 'block', 0],
['claude', 'ignored', 'import', 0],
['all', 'none', 'plain', 1],
['all', 'none', 'block', 1],
['all', 'none', 'import', 1],
['all', 'committed', 'plain', 0] /* 0.7.1: 1 */,
['all', 'committed', 'block', 1],
['all', 'committed', 'import', 0] /* 0.7.1: 1 */,
['all', 'ignored', 'plain', 1],
['all', 'ignored', 'block', 1],
['all', 'ignored', 'import', 1],
])) {
it(`${preset}, root ${root}, .claude holds ${dir}: exit ${exit}`, () => {
const {project, outside} = layout();
fs.writeFileSync(path.join(project, 'AGENTS.md'), '# Agents\n');
if (root !== 'none')
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
if (root === 'ignored')
fs.writeFileSync(path.join(project, '.gitignore'), '/CLAUDE.md\n');
fs.writeFileSync(path.join(outside, 'CLAUDE.md'), BODY[dir]);
fs.symlinkSync(outside, path.join(project, '.claude'), 'dir');
const run = () =>
installAgentDocs(project, {
agent: preset === 'default' ? undefined : preset,
renderedBlock: BLOCK,
onSkipped: () => {},
});
if (exit === 1) {
expect(run).toThrow(PathSafetyError);
expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
'# Agents\n',
);
} else {
expect(run).not.toThrow();
}
expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), 'utf-8')).toBe(
BODY[dir],
);
});
}
});
describe('a root CLAUDE.md linked outside the project that only imports AGENTS.md (0.7.1 left it alone)', () => {
it('is skipped with a note and init exits 0 at the project root; the rest is written', async () => {
const {project, outside} = layout();
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
fs.writeFileSync(path.join(project, 'AGENTS.md'), '# Agents\n');
fs.writeFileSync(path.join(outside, 'CLAUDE.md'), '@AGENTS.md\n');
fs.symlinkSync(
path.join(outside, 'CLAUDE.md'),
path.join(project, 'CLAUDE.md'),
);
const r = await runCli(['init', '--features', 'agents', '--json'], project);
expect(r.status).toBe(0);
const {data} = JSON.parse(r.stdout);
expect(data.docsWritten).toEqual(['AGENTS.md', 'GEMINI.md']);
expect(data.docsError.message).toMatch(
/^Left as it is: CLAUDE\.md \(.*outside the project root/u,
);
expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), 'utf-8')).toBe(
'@AGENTS.md\n',
);
}, 30_000);
});
describe('a tracked .claude/CLAUDE.md is committed, whatever the ignore files say (INV31)', () => {
/** @param {string} cwd @param {...string} args */
const git = (cwd, ...args) => {
const r = spawnSync(
'git',
['-c', 'user.name=t', '-c', 'user.email=t@e', ...args],
{
cwd,
encoding: 'utf-8',
},
);
if (r.status !== 0) throw new Error(`git ${args.join(' ')}: ${r.stderr}`);
};
it.skipIf(spawnSync('git', ['--version']).status !== 0)(
'keeps the copy in a tracked .claude/CLAUDE.md when an unanchored CLAUDE.md rule ignores both',
() => {
const {project} = layout();
git(project, 'init', '-q');
fs.writeFileSync(path.join(project, '.gitignore'), 'CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, '# Team\n');
// Tracked despite the rule, as `git add -f` leaves it.
git(project, 'add', '-f', '.gitignore', '.claude/CLAUDE.md');
git(project, 'commit', '-q', '-m', 'team claude file');
expect(installAgentDocs(project, {renderedBlock: BLOCK})).toEqual([
'AGENTS.md',
'CLAUDE.md',
'.claude/CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
// --agent claude keeps it too.
installAgentDocs(project, {agent: 'claude', renderedBlock: BLOCK});
expect(fs.readFileSync(copy, 'utf-8')).toContain(BLOCK);
},
);
it.skipIf(spawnSync('git', ['--version']).status !== 0)(
'strips the block from an untracked .claude/CLAUDE.md the same rule ignores',
() => {
const {project} = layout();
git(project, 'init', '-q');
fs.writeFileSync(path.join(project, '.gitignore'), 'CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(
copy,
'# Team\n\n<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->\n',
);
installAgentDocs(project, {renderedBlock: BLOCK});
expect(fs.readFileSync(copy, 'utf-8').trimEnd()).toBe('# Team');
},
);
for (const [label, setUp] of [
[
"the repository's local exclude file",
(/** @type {string} */ project) =>
fs.appendFileSync(
path.join(project, '.git', 'info', 'exclude'),
'/CLAUDE.md\n',
),
],
[
'a configured excludes file',
(/** @type {string} */ project) => {
const excludes = path.join(project, '..', 'global-excludes');
fs.writeFileSync(excludes, 'CLAUDE.md\n');
git(project, 'config', 'core.excludesFile', excludes);
},
],
]) {
it.skipIf(spawnSync('git', ['--version']).status !== 0)(
`keeps the copy in a tracked .claude/CLAUDE.md while ${label} ignores an untracked root CLAUDE.md`,
() => {
const {project} = layout();
git(project, 'init', '-q');
setUp(project);
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, '# Team\n');
git(project, 'add', '-f', '.claude/CLAUDE.md');
git(project, 'commit', '-q', '-m', 'team claude file');
expect(installAgentDocs(project, {renderedBlock: BLOCK})).toEqual([
'AGENTS.md',
'CLAUDE.md',
'.claude/CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
},
);
}
it('keeps the copy when the repository cannot say what it ignores or tracks (fails closed)', () => {
const {project} = layout();
// A .git that git cannot read.
fs.writeFileSync(path.join(project, '.git'), 'gitdir: /nowhere/.git\n');
fs.writeFileSync(path.join(project, '.gitignore'), 'CLAUDE.md\n');
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Mine\n');
fs.mkdirSync(path.join(project, '.claude'));
const copy = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(copy, '# Team\n');
installAgentDocs(project, {renderedBlock: BLOCK});
expect(fs.readFileSync(copy, 'utf-8')).toBe(`# Team\n\n${BLOCK}\n`);
});
});
describe("init's exit-code help names every soft exit-0 case these tests pin", () => {
const exit0 = initDoc.exitCodes.find(entry => entry.code === 0)?.when ?? '';
it.each([
['the home or a settings folder', /home folder, or in a settings folder/u],
[
'a GEMINI.md that resolves outside the project',
/a GEMINI\.md that resolves outside the project/u,
],
[
'a project-root file below the root',
/below the project root, a project-root agent file/u,
],
[
"the project's Claude Code file that only imports an existing AGENTS.md",
/Claude Code file \(root CLAUDE\.md, or \.claude\/CLAUDE\.md when there is no root one\)[^;]*block-less import of an existing AGENTS\.md/u,
],
[
'beside an ignored CLAUDE.md, the copy --agent claude adds or a block-less import',
/beside a CLAUDE\.md the project ignores, the one --agent claude adds or a block-less import of an existing AGENTS\.md/u,
],
[
'--agent claude removing a block beside a CLAUDE.md',
/with --agent claude beside a CLAUDE\.md, one whose block it would remove/u,
],
])('%s', (_label, pattern) => {
expect(exit0).toMatch(pattern);
});
});
describe('init exit codes and output', () => {
it('an ignored GEMINI.md with notes: written through, exit 0, nothing on stderr', async () => {
const {project} = layout();
fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
fs.writeFileSync(path.join(project, '.gitignore'), 'GEMINI.md\n');
fs.writeFileSync(path.join(project, 'GEMINI.md'), '# My Gemini notes\n');
const json = await runCli(
['init', '--features', 'agents', '--json'],
project,
);
expect(json.status).toBe(0);
const {data} = JSON.parse(json.stdout);
expect(data.docsWritten).toEqual(['AGENTS.md', 'GEMINI.md']);
expect(data.docsError).toBeNull();
const text = await runCli(['init', '--features', 'agents'], project);
expect(text.status).toBe(0);
expect(text.stderr).toBe('');
}, 30_000);
it('a path that escapes the project still exits 1, as in 0.7.1', async () => {
const {project, outside} = layout();
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 text = await runCli(['init', '--features', 'agents'], project);
expect(text.status).toBe(1);
expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
}, 30_000);
});
describe("the sandbox app's postinstall stays quiet", () => {
// apps/sandbox runs `astryx init --features agents` on every install, and its
// .gitignore lists the files init writes there.
const sandboxIgnore = fs.readFileSync(
new URL('../../../../apps/sandbox/.gitignore', import.meta.url),
'utf-8',
);
it('prints nothing on stderr on a fresh install, a second install, or with an old .claude/CLAUDE.md init wrote', async () => {
const {project} = layout();
fs.writeFileSync(
path.join(project, 'package.json'),
'{"name":"sandbox"}\n',
);
fs.writeFileSync(path.join(project, '.gitignore'), sandboxIgnore);
for (let round = 0; round < 2; round++) {
const r = await runCli(['init', '--features', 'agents'], project);
expect(r.status, `round ${round}`).toBe(0);
expect(r.stderr, `round ${round}`).toBe('');
}
// A dev machine where an older init created .claude/CLAUDE.md.
fs.mkdirSync(path.join(project, '.claude'), {recursive: true});
const claude = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(
claude,
'# CLAUDE\n\nProject-specific guidance for AI coding agents.\n\n<!-- ASTRYX:START -->\nold\n<!-- ASTRYX:END -->\n',
);
const r = await runCli(['init', '--features', 'agents'], project);
expect(r.status).toBe(0);
expect(r.stderr).toBe('');
expect(fs.readFileSync(claude, 'utf-8')).not.toContain('\nold\n');
}, 60_000);
});
describe('removing the copy in .claude/CLAUDE.md', () => {
it('removes only the managed block, keeps the user text, and only once root CLAUDE.md holds the same block', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Claude\n');
fs.mkdirSync(path.join(project, '.claude'));
const dirFile = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(
dirFile,
`# My notes\nKeep this guidance.\n\n${BLOCK}\n\nAnd this.\n`,
);
expect(installAgentDocs(project, {renderedBlock: BLOCK})).toEqual([
'AGENTS.md',
'CLAUDE.md',
'.claude/CLAUDE.md',
'GEMINI.md',
]);
expect(fs.readFileSync(dirFile, 'utf-8').trimEnd()).toBe(
'# My notes\nKeep this guidance.\n\nAnd this.',
);
expect(fs.readFileSync(path.join(project, 'CLAUDE.md'), 'utf-8')).toContain(
BLOCK,
);
});
it('keeps the copy when root CLAUDE.md does not end up holding the same block', () => {
const {project} = layout();
// A root CLAUDE.md with a malformed block is refused before any write, so
// the copy in .claude/CLAUDE.md stays where it is.
fs.writeFileSync(
path.join(project, 'CLAUDE.md'),
'<!-- ASTRYX:START -->\nbroken\n',
);
fs.mkdirSync(path.join(project, '.claude'));
const dirFile = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(dirFile, `${BLOCK}\n`);
expect(() => installAgentDocs(project, {renderedBlock: BLOCK})).toThrow(
/Malformed/u,
);
expect(fs.readFileSync(dirFile, 'utf-8')).toBe(`${BLOCK}\n`);
});
it('deletes .claude/CLAUDE.md only when nothing but whitespace is left', () => {
const {project} = layout();
fs.writeFileSync(path.join(project, 'CLAUDE.md'), '# Claude\n');
fs.mkdirSync(path.join(project, '.claude'));
const dirFile = path.join(project, '.claude', 'CLAUDE.md');
fs.writeFileSync(dirFile, `\n\n${BLOCK}\n \n`);
installAgentDocs(project, {renderedBlock: BLOCK});
expect(fs.existsSync(dirFile)).toBe(false);
});
});
describe('removeXdsBlock deletes only a file init created', () => {
it('keeps a file whose own text mentions guidance (the 0.7.0 heading match deleted it)', () => {
const {project} = layout();
const file = path.join(project, 'AGENTS.md');
fs.writeFileSync(
file,
`# Team rules\nOur guidance for reviewers.\n\n${BLOCK}\n`,
);
expect(removeXdsBlock(file, {deleteIfEmpty: true})).toBe(true);
expect(fs.readFileSync(file, 'utf-8')).toBe(
'# Team rules\nOur guidance for reviewers.\n',
);
});
it('deletes a file that holds only the heading init writes', () => {
const {project} = layout();
const file = path.join(project, 'AGENTS.md');
fs.writeFileSync(
file,
`# AGENTS.md\n\nProject-specific guidance for AI coding agents.\n\n${BLOCK}\n`,
);
expect(removeXdsBlock(file, {deleteIfEmpty: true})).toBe(true);
expect(fs.existsSync(file)).toBe(false);
});
});