Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

6.8 KB
Raw Blame
import { describe, it, expect } from 'vitest';
import { execFileSync } from 'child_process';
import { readFileSync, lstatSync, existsSync } from 'fs';
import { dirname, join, resolve } from 'path';
import { fileURLToPath } from 'url';

// Regression guard for #4852. `AGENTS.md` is the cross-vendor agent-instructions
// standard every CLI PortOS drives reads — except Claude Code, whose memory
// discovery hardcodes `CLAUDE.md` with no configurable filename. So each
// location carries both, and the second is a one-line `@AGENTS.md` import.
//
// Two ways that arrangement silently breaks, both guarded here:
//   1. Someone "tidies" the bridge into a symlink. A git symlink checked out on
//      a Windows runner without symlink support materializes as a 9-byte text
//      file containing the literal string `AGENTS.md` — a CLAUDE.md from which
//      Claude Code loads nothing, and the repo's whole memory disappears for
//      that agent with no error anywhere.
//   2. New prose reintroduces `CLAUDE.md` as THE instructions filename, so an
//      agent (or a scaffolded repo) is pointed at a file that may not exist.
//
// Enumeration is via `git grep`, so the scan covers exactly *tracked* files —
// gitignored runtime state (`data/`) and the `lib/slashdo` submodule (a separate
// upstream repo, not ours to police) drop out for free.

const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');

/** Every directory that carries the pair. Adding a nested one? Add it here. */
const INSTRUCTION_DIRS = [
  '.',
  'client/src',
  'client/src/components/dashboard',
  'server',
  'server/lib/aiToolkit',
];

/** Entire body of a bridge file. */
const IMPORT_BODY = '@AGENTS.md\n';

// Historical records and frozen data. Rewriting these would falsify history or,
// for the migrations and the prompt-integrity snapshot, break the exact matching
// they perform against what an older version actually wrote.
const EXCLUDED_PREFIXES = [
  '.changelog/',
  'docs/plans/',
  'docs/superpowers/',
  'data/',
  'lib/slashdo/',
  'scripts/migrations/',
  'server/services/taskPromptDefaults/integrity.snapshot.json',
];

// The modules whose JOB is to know both names — the discovery walker, its tests
// (whose fixtures are literal `CLAUDE.md` files), the shared filename constants,
// and this test. Everywhere else, a bare `CLAUDE.md` must be paired with
// `AGENTS.md` on the same line.
const DUAL_NAME_IMPLEMENTATION = [
  'server/services/agentPromptBuilder.test.js',
  'server/services/promptSections/instructions.js',
  'server/lib/agentInstructionsFile.js',
  'server/lib/agentInstructionsFile.test.js',
  'scripts/agent-instructions-files.test.js',
];

const git = (...args) => execFileSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });

describe('agent-instructions files (#4852)', () => {
  it('every location has a real AGENTS.md and a real CLAUDE.md holding only the import', () => {
    for (const dir of INSTRUCTION_DIRS) {
      const agentsPath = join(REPO_ROOT, dir, 'AGENTS.md');
      const bridgePath = join(REPO_ROOT, dir, 'CLAUDE.md');

      expect(lstatSync(agentsPath).isFile(), `${dir}/AGENTS.md must be a regular file`).toBe(true);
      expect(lstatSync(bridgePath).isFile(), `${dir}/CLAUDE.md must be a regular file`).toBe(true);
      expect(readFileSync(agentsPath, 'utf8').trim().length, `${dir}/AGENTS.md must carry content`).toBeGreaterThan(0);
      expect(readFileSync(bridgePath, 'utf8'), `${dir}/CLAUDE.md must be exactly the @AGENTS.md import`).toBe(IMPORT_BODY);
    }
  });

  it('no tracked AGENTS.md or CLAUDE.md is a symlink', () => {
    // Mode 120000 is git's symlink mode. It survives a Unix checkout and
    // silently degrades to junk text on a Windows runner, so the ban is on the
    // index entry rather than on what happens to be on this machine's disk.
    const symlinks = git('ls-files', '-s', '--', '*AGENTS.md', '*CLAUDE.md')
      .split('\n')
      .filter((line) => line.startsWith('120000'));

    expect(symlinks).toEqual([]);
  });

  it('no tracked file names CLAUDE.md as the canonical instructions file', () => {
    const hits = git('grep', '-n', '--fixed-strings', 'CLAUDE.md', '--', '.')
      .split('\n')
      .filter(Boolean)
      .map((line) => {
        const firstColon = line.indexOf(':');
        const secondColon = line.indexOf(':', firstColon + 1);
        return { file: line.slice(0, firstColon), line: line.slice(0, secondColon), text: line.slice(secondColon + 1) };
      })
      .filter(({ file }) => !EXCLUDED_PREFIXES.some((prefix) => file.startsWith(prefix)))
      .filter(({ file }) => !DUAL_NAME_IMPLEMENTATION.includes(file))
      // `~/.claude/CLAUDE.md` (and `.claude/CLAUDE.md`) is Claude Code's OWN
      // user-level memory location, not a repo convention — it keeps its name.
      .filter(({ text }) => !text.includes('.claude/CLAUDE.md'))
      // Dual naming is the accepted form: an agent told to read
      // "AGENTS.md (or CLAUDE.md)" still finds a managed app that has either.
      .filter(({ text }) => !text.includes('AGENTS.md'));

    expect(hits.map((h) => h.line)).toEqual([]);
  });

  it('every tracked .claude/ symlink resolves to an existing file (#11855)', () => {
    // Git symlinks (mode 120000) under .claude/ point into lib/slashdo, which
    // upstream renames or removes. A dangling one fails any tool that enumerates
    // tracked markdown with ENOENT. Targets inside lib/slashdo are skipped when
    // the submodule is not checked out, because CI only initializes it on demand.
    const submoduleReady = existsSync(join(REPO_ROOT, 'lib/slashdo/package.json'));
    const links = git('ls-files', '-s', '--', '.claude')
      .split('\n')
      .filter((line) => line.startsWith('120000'))
      .map((line) => line.split('\t')[1]);

    expect(links.length, 'detector self-check: .claude/ must track symlinks').toBeGreaterThan(0);

    const dangling = links.filter((link) => {
      // The blob content IS the link target; a Windows checkout without symlink
      // support materializes a text file, so the disk entry can't be trusted.
      const target = git('cat-file', 'blob', `:${link}`);
      if (!submoduleReady && target.includes('lib/slashdo/')) return false;
      return !existsSync(resolve(dirname(join(REPO_ROOT, link)), target));
    });

    expect(dangling).toEqual([]);
  });

  it('the scan actually reads tracked files (detector self-check)', () => {
    // Non-vacuous guard: if the pathspec or the exclusions ever widened to
    // everything, the assertion above would pass by scanning nothing.
    const scanned = git('grep', '-l', '--fixed-strings', 'CLAUDE.md', '--', '.')
      .split('\n')
      .filter(Boolean)
      .filter((file) => !EXCLUDED_PREFIXES.some((prefix) => file.startsWith(prefix)));

    expect(scanned).toContain('AGENTS.md');
    expect(scanned).toContain('server/services/promptSections/instructions.js');
  });
});