Codeman/test/agent-skill.test.ts

/**
 * @fileoverview Unit tests for the agent-skill injection helpers in hooks-config.ts
 * (`applyAgentSkill`, `installAgentSkillInto`, `removeAgentSkillFrom`).
 *
 * These run against the REAL packaged source (`skills/codeman/` at the repo root),
 * so they double as a guard that the skill files exist and are readable: an npm
 * publish without them would be caught here before the `files` entry silently
 * ignores the missing directory.
 *
 * Filesystem tests in a per-test temp dir; the self-ignoring block also runs real
 * `git` there (no global or system config). Port: N/A.
 */

import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { mkdtemp, rm, mkdir, writeFile, readFile, symlink, readdir, stat, utimes } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { join } from 'node:path';
import { tmpdir, homedir } from 'node:os';
import {
  applyAgentSkill,
  installAgentSkillInto,
  removeAgentSkillFrom,
  refreshUserAgentSkill,
  seedAgentSessionPreamble,
  removeAgentSessionPreamble,
  pruneAgentSessionPreambles,
} from '../src/hooks-config.js';

const MARKER_PREFIX = '<!-- codeman-managed-agent-skill';

/** Run `fn` against a throwaway XDG cache dir, restoring the env afterwards. */
async function withCacheDir(fn: (cacheDir: string) => Promise<void>): Promise<void> {
  const prevXdg = process.env.XDG_CACHE_HOME;
  const cacheDir = join(casePath, 'xdg-cache');
  process.env.XDG_CACHE_HOME = cacheDir;
  try {
    await fn(cacheDir);
  } finally {
    if (prevXdg === undefined) delete process.env.XDG_CACHE_HOME;
    else process.env.XDG_CACHE_HOME = prevXdg;
  }
}

let casePath: string;
const skillDir = () => join(casePath, '.claude', 'skills', 'codeman');

beforeEach(async () => {
  casePath = await mkdtemp(join(tmpdir(), 'codeman-agent-skill-'));
});

afterEach(async () => {
  await rm(casePath, { recursive: true, force: true });
});

describe('installAgentSkillInto / applyAgentSkill(enabled)', () => {
  it('installs SKILL.md (marker appended) and the reference files from the packaged source', async () => {
    const result = await applyAgentSkill(casePath, true);
    expect(result).toBe('installed');

    const skillMd = await readFile(join(skillDir(), 'SKILL.md'), 'utf-8');
    expect(skillMd.startsWith('---\nname: codeman')).toBe(true);
    expect(skillMd).toContain(MARKER_PREFIX);

    // Reference files ride along byte-for-byte (no marker there).
    const sourceEndpoints = await readFile(
      join(process.cwd(), 'skills', 'codeman', 'reference', 'endpoints.md'),
      'utf-8'
    );
    const injectedEndpoints = await readFile(join(skillDir(), 'reference', 'endpoints.md'), 'utf-8');
    expect(injectedEndpoints).toBe(sourceEndpoints);
    expect(existsSync(join(skillDir(), 'reference', 'recipes.md'))).toBe(true);
  });

  it('is idempotent: a second run reports unchanged', async () => {
    await applyAgentSkill(casePath, true);
    expect(await applyAgentSkill(casePath, true)).toBe('unchanged');
  });

  it('refreshes a stale Codeman-managed copy back to the packaged content', async () => {
    await applyAgentSkill(casePath, true);
    const original = await readFile(join(skillDir(), 'SKILL.md'), 'utf-8');
    // Simulate an older injected version: content differs but the marker is intact.
    await writeFile(join(skillDir(), 'SKILL.md'), `stale content\n${MARKER_PREFIX}: old -->\n`);

    expect(await applyAgentSkill(casePath, true)).toBe('refreshed');
    expect(await readFile(join(skillDir(), 'SKILL.md'), 'utf-8')).toBe(original);
  });

  it('never clobbers a user-authored skills/codeman (no marker)', async () => {
    await mkdir(skillDir(), { recursive: true });
    await writeFile(join(skillDir(), 'SKILL.md'), '---\nname: codeman\n---\nmy own skill\n');

    expect(await applyAgentSkill(casePath, true)).toBe('foreign');
    expect(await readFile(join(skillDir(), 'SKILL.md'), 'utf-8')).toContain('my own skill');
    expect(existsSync(join(skillDir(), 'reference'))).toBe(false);
    // Not even the ignore file: a foreign copy is the user's to track or not.
    expect(existsSync(join(skillDir(), '.gitignore'))).toBe(false);
  });

  it('refuses to write through a symlinked skill dir (dogfooding layout)', async () => {
    await mkdir(join(casePath, '.claude', 'skills'), { recursive: true });
    await symlink(join(casePath, 'elsewhere'), skillDir());
    expect(await installAgentSkillInto(skillDir())).toBe('symlink');
  });

  it('refuses to write through a symlinked skills/ parent', async () => {
    await mkdir(join(casePath, 'real-skills'), { recursive: true });
    await mkdir(join(casePath, '.claude'), { recursive: true });
    await symlink(join(casePath, 'real-skills'), join(casePath, '.claude', 'skills'));
    expect(await installAgentSkillInto(skillDir())).toBe('symlink');
    expect(await readdir(join(casePath, 'real-skills'))).toEqual([]);
  });

  // A cloned repository can commit `reference` as a link, and a Docker case's container
  // can plant one in the bind-mounted workspace the host injects into (on by default).
  it('refuses a symlinked reference/ folder inside the copy, so nothing is written where it points', async () => {
    const outside = join(casePath, 'outside');
    await mkdir(outside, { recursive: true });
    await writeFile(join(outside, 'history.md'), 'my notes\n');
    await mkdir(skillDir(), { recursive: true });
    await symlink(outside, join(skillDir(), 'reference'));

    expect(await applyAgentSkill(casePath, true)).toBe('symlink');
    expect(await readdir(outside)).toEqual(['history.md']);
    expect(await readFile(join(outside, 'history.md'), 'utf-8')).toBe('my notes\n');
    // Refused before the first write: no SKILL.md, no ignore file.
    expect(await readdir(skillDir())).toEqual(['reference']);
  });

  it('refuses a symlinked reference/ folder planted beside an existing Codeman copy', async () => {
    await applyAgentSkill(casePath, true);
    const outside = join(casePath, 'outside');
    await mkdir(outside, { recursive: true });
    await writeFile(join(outside, 'recipes.md'), 'my recipes\n');
    await rm(join(skillDir(), 'reference'), { recursive: true });
    await symlink(outside, join(skillDir(), 'reference'));
    const skillMd = await readFile(join(skillDir(), 'SKILL.md'), 'utf-8');
    await writeFile(join(skillDir(), 'SKILL.md'), `stale\n${MARKER_PREFIX}: old -->\n`);

    expect(await applyAgentSkill(casePath, true)).toBe('symlink');
    expect(await readdir(outside)).toEqual(['recipes.md']);
    expect(await readFile(join(outside, 'recipes.md'), 'utf-8')).toBe('my recipes\n');
    // The stale copy is left as found, not refreshed through the link.
    expect(await readFile(join(skillDir(), 'SKILL.md'), 'utf-8')).not.toBe(skillMd);
  });
});

describe('removeAgentSkillFrom / applyAgentSkill(disabled)', () => {
  it('refuses to delete through a symlinked reference/ folder inside the copy', async () => {
    await applyAgentSkill(casePath, true);
    const outside = join(casePath, 'outside');
    await mkdir(outside, { recursive: true });
    // Files named like the packaged reference files: an unlink through the link would take them.
    for (const name of await readdir(join(skillDir(), 'reference'))) {
      await writeFile(join(outside, name), 'not yours\n');
    }
    const names = (await readdir(outside)).sort();
    expect(names.length).toBeGreaterThan(0);
    await rm(join(skillDir(), 'reference'), { recursive: true });
    await symlink(outside, join(skillDir(), 'reference'));

    expect(await applyAgentSkill(casePath, false)).toBe('symlink');
    expect((await readdir(outside)).sort()).toEqual(names);
    for (const name of names) expect(await readFile(join(outside, name), 'utf-8')).toBe('not yours\n');
    expect(existsSync(join(skillDir(), 'SKILL.md'))).toBe(true);
  });

  it('removes our copy and prunes the emptied directories', async () => {
    await applyAgentSkill(casePath, true);
    expect(await applyAgentSkill(casePath, false)).toBe('removed');
    expect(existsSync(skillDir())).toBe(false);
    expect(existsSync(join(casePath, '.claude', 'skills'))).toBe(false);
    // `.claude` itself is not ours to prune.
    expect(existsSync(join(casePath, '.claude'))).toBe(true);
  });

  it('reports absent when there is nothing to remove', async () => {
    expect(await applyAgentSkill(casePath, false)).toBe('absent');
  });

  it('leaves a user-authored copy untouched', async () => {
    await mkdir(skillDir(), { recursive: true });
    await writeFile(join(skillDir(), 'SKILL.md'), 'my own skill\n');
    expect(await applyAgentSkill(casePath, false)).toBe('foreign');
    expect(existsSync(join(skillDir(), 'SKILL.md'))).toBe(true);
  });

  it("preserves a user's extra files in the directory (no rm -rf)", async () => {
    await applyAgentSkill(casePath, true);
    await writeFile(join(skillDir(), 'reference', 'my-notes.md'), 'mine\n');

    expect(await applyAgentSkill(casePath, false)).toBe('removed');
    expect(existsSync(join(skillDir(), 'SKILL.md'))).toBe(false);
    expect(existsSync(join(skillDir(), 'reference', 'endpoints.md'))).toBe(false);
    // The user's file and the directories holding it survive.
    expect(await readFile(join(skillDir(), 'reference', 'my-notes.md'), 'utf-8')).toBe('mine\n');
    // And so does the ignore file, so their notes stay out of `git status` as before.
    expect(await readFile(join(skillDir(), '.gitignore'), 'utf-8')).toBe('*\n');
  });
});

describe('the injected copy ignores itself in git', () => {
  const ENV = {
    ...process.env,
    LC_ALL: 'C',
    GIT_AUTHOR_NAME: 'T',
    GIT_AUTHOR_EMAIL: 't@example.com',
    GIT_COMMITTER_NAME: 'T',
    GIT_COMMITTER_EMAIL: 't@example.com',
    GIT_CONFIG_GLOBAL: '/dev/null',
    GIT_CONFIG_NOSYSTEM: '1',
  };
  const git = (...args: string[]) =>
    execFileSync('git', args, { cwd: casePath, env: ENV, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
  /** Exit status of `git check-ignore -q -- <path>`: 0 ignored, 1 not ignored. */
  const checkIgnore = (path: string): number => {
    try {
      git('check-ignore', '-q', '--', path);
      return 0;
    } catch (err) {
      return (err as { status: number }).status;
    }
  };
  /** A repository with one commit and a tracked `.gitignore` of its own. */
  const initRepo = async () => {
    git('init', '-q', '-b', 'main');
    await writeFile(join(casePath, 'README.md'), 'hello\n');
    await writeFile(join(casePath, '.gitignore'), 'node_modules/\n');
    git('add', 'README.md', '.gitignore');
    git('-c', 'commit.gpgsign=false', 'commit', '-q', '-m', 'init');
  };

  it('writes a .gitignore of `*` into the copy on install', async () => {
    expect(await applyAgentSkill(casePath, true)).toBe('installed');
    expect(await readFile(join(skillDir(), '.gitignore'), 'utf-8')).toBe('*\n');
    // Never part of the skill content: a second run has nothing to do.
    expect(await applyAgentSkill(casePath, true)).toBe('unchanged');
  });

  it('keeps `git status` of the user repository clean, and leaves its own ignore file alone', async () => {
    await initRepo();
    await applyAgentSkill(casePath, true);
    await applyAgentSkill(casePath, true, '.agents/skills');

    expect(git('status', '--porcelain', '--untracked-files=all')).toBe('');
    expect(await readFile(join(casePath, '.gitignore'), 'utf-8')).toBe('node_modules/\n');
    // Nor the repository's local exclude file (git's template may or may not create one).
    const exclude = join(casePath, '.git', 'info', 'exclude');
    if (existsSync(exclude)) expect(await readFile(exclude, 'utf-8')).not.toContain('codeman');
  });

  it('ignores the copy contents, never the folder above it (Claude Code checks only those)', async () => {
    // Claude Code 2.1.319 skips a nested skills folder when `git check-ignore` says its
    // project directory is ignored; it never checks a skill folder or its SKILL.md.
    await initRepo();
    await applyAgentSkill(casePath, true);
    expect(checkIgnore('.claude/skills/codeman/SKILL.md')).toBe(0);
    expect(checkIgnore('.claude/skills/codeman')).toBe(1);
    expect(checkIgnore('.claude/skills')).toBe(1);
    expect(checkIgnore('.claude')).toBe(1);
  });

  it('never overwrites a .gitignore that is already in the folder', async () => {
    await applyAgentSkill(casePath, true);
    await writeFile(join(skillDir(), '.gitignore'), '# mine\nSKILL.md\n');
    // A stale copy: the refresh rewrites the skill but not the ignore file.
    await writeFile(join(skillDir(), 'SKILL.md'), `stale\n${MARKER_PREFIX}: old -->\n`);
    expect(await applyAgentSkill(casePath, true)).toBe('refreshed');
    expect(await readFile(join(skillDir(), '.gitignore'), 'utf-8')).toBe('# mine\nSKILL.md\n');
  });

  it('a copy injected before the ignore file existed gains it on the next install', async () => {
    await applyAgentSkill(casePath, true);
    await rm(join(skillDir(), '.gitignore'));
    // Every skill file is current, so only the ignore file is new: still a refresh.
    expect(await applyAgentSkill(casePath, true)).toBe('refreshed');
    expect(await readFile(join(skillDir(), '.gitignore'), 'utf-8')).toBe('*\n');
  });

  it('does not write through a symlink planted at the ignore file name', async () => {
    await mkdir(skillDir(), { recursive: true });
    const outside = join(casePath, 'outside.txt');
    await writeFile(outside, 'untouched\n');
    await symlink(outside, join(skillDir(), '.gitignore'));
    expect(await applyAgentSkill(casePath, true)).toBe('installed');
    expect(await readFile(outside, 'utf-8')).toBe('untouched\n');
  });

  it('uninstall removes the ignore file with the copy, so no folder is left behind', async () => {
    await initRepo();
    await applyAgentSkill(casePath, true);
    expect(await applyAgentSkill(casePath, false)).toBe('removed');
    expect(existsSync(skillDir())).toBe(false);
    expect(existsSync(join(casePath, '.claude', 'skills'))).toBe(false);
    expect(git('status', '--porcelain', '--untracked-files=all')).toBe('');
  });

  it("uninstall keeps an ignore file that is not Codeman's", async () => {
    await applyAgentSkill(casePath, true);
    await writeFile(join(skillDir(), '.gitignore'), 'SKILL.md\n');
    expect(await applyAgentSkill(casePath, false)).toBe('removed');
    expect(await readFile(join(skillDir(), '.gitignore'), 'utf-8')).toBe('SKILL.md\n');
  });

  it('the packaged source carries no ignore file (the plugin mirror pins its file set)', () => {
    expect(existsSync(join(process.cwd(), 'skills', 'codeman', '.gitignore'))).toBe(false);
    expect(existsSync(join(process.cwd(), 'plugins', 'codeman', 'skills', 'codeman', '.gitignore'))).toBe(false);
  });
});

describe('preamble single-source (seed + §0 heredoc parity)', () => {
  const packagedDir = join(process.cwd(), 'skills', 'codeman');

  it("SKILL.md's §0 heredoc is byte-identical to the packaged preamble.sh", async () => {
    const skillMd = await readFile(join(packagedDir, 'SKILL.md'), 'utf-8');
    const openTag = "<<'PREAMBLE'\n";
    const open = skillMd.indexOf(openTag);
    expect(open).toBeGreaterThan(-1);
    const start = open + openTag.length;
    const end = skillMd.indexOf('\nPREAMBLE\n', start);
    expect(end).toBeGreaterThan(start);
    // slice(.., end + 1) keeps the final line's own newline.
    const heredoc = skillMd.slice(start, end + 1);

    // The server seeds preamble.sh while agents that paste §0 write the heredoc; any
    // byte of drift between the two would make the §0 grep rewrite a seeded file (or
    // worse, ship different behavior depending on which path wrote it).
    const preamble = await readFile(join(packagedDir, 'preamble.sh'), 'utf-8');
    expect(preamble).toBe(heredoc);
  });

  it("SKILL.md's shell survives Claude Code's skill-argument substitution unchanged", async () => {
    // When Claude Code loads a skill WITH arguments (the Skill tool passes the user's request words),
    // it rewrites the skill body before the model sees it. Measured on 2.1.300: every `$ARGUMENTS[N]`,
    // `$ARGUMENTS` and bare `$N` (digits, then no word character) becomes the matching argument, 0-based,
    // and a backslash before `$` is consumed as an escape. A bare `$1` in §0 arrived as
    // `sessions/5/terminal` and `timeout=claude` for "start 5 claude workers", so an agent pasting §0
    // wrote a broken preamble. `${1}` is the same bash and is never touched; keep it that way.
    const skillMd = await readFile(join(packagedDir, 'SKILL.md'), 'utf-8');
    const substitute = (body: string, args: string[]): string =>
      body
        .replace(/(?<!\\)\\\$(?=\d|ARGUMENTS)/g, '$')
        .replace(/\$ARGUMENTS\[(\d+)\]/g, (m, i: string) => args[Number(i)] ?? m)
        .replace(/\$(\d+)(?!\w)/g, (m, i: string) => args[Number(i)] ?? m)
        .replaceAll('$ARGUMENTS', args.join(' '));
    const args = 'start 5 claude workers, one per TODO item'.split(/\s+/);
    expect(substitute(skillMd, args)).toBe(skillMd);

    // And the heredoc an agent pastes from the substituted body is still the seeded preamble.
    const rendered = substitute(skillMd, args);
    const start = rendered.indexOf("<<'PREAMBLE'\n") + "<<'PREAMBLE'\n".length;
    const preamble = await readFile(join(packagedDir, 'preamble.sh'), 'utf-8');
    expect(rendered.slice(start, rendered.indexOf('\nPREAMBLE\n', start) + 1)).toBe(preamble);
  });

  it('seedAgentSessionPreamble writes the stamped preamble to the XDG cache path, 0600', async () => {
    const prevXdg = process.env.XDG_CACHE_HOME;
    const cacheDir = join(casePath, 'xdg-cache');
    process.env.XDG_CACHE_HOME = cacheDir;
    try {
      await seedAgentSessionPreamble('seed-test-session');
      const target = join(cacheDir, 'codeman-agent-seed-test-session.sh');
      const content = await readFile(target, 'utf-8');
      expect(content.startsWith('# ---- Codeman agent preamble')).toBe(true);
      expect(content).toMatch(/\nCODEMAN_PREAMBLE=\d+\.\d+\.\d+\n$/);
      expect((await stat(target)).mode & 0o777).toBe(0o600);
    } finally {
      if (prevXdg === undefined) delete process.env.XDG_CACHE_HOME;
      else process.env.XDG_CACHE_HOME = prevXdg;
    }
  });

  it('removeAgentSessionPreamble drops one session cache and shrugs at a missing one', async () => {
    // Seeding writes one file per claude session and nothing used to remove them
    // (236 leftovers measured on a working machine); session teardown calls this.
    await withCacheDir(async (cacheDir) => {
      await seedAgentSessionPreamble('gone-session');
      expect(existsSync(join(cacheDir, 'codeman-agent-gone-session.sh'))).toBe(true);

      await removeAgentSessionPreamble('gone-session');
      expect(existsSync(join(cacheDir, 'codeman-agent-gone-session.sh'))).toBe(false);

      await expect(removeAgentSessionPreamble('never-existed')).resolves.toBeUndefined();
    });
  });

  it('pruneAgentSessionPreambles takes only aged caches with no live session behind them', async () => {
    await withCacheDir(async (cacheDir) => {
      const aged = (name: string) => join(cacheDir, name);
      for (const id of ['live-old', 'dead-old', 'dead-fresh']) {
        await seedAgentSessionPreamble(id);
      }
      // Age two of them past the cutoff; `dead-fresh` stays new.
      const old = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
      await utimes(aged('codeman-agent-live-old.sh'), old, old);
      await utimes(aged('codeman-agent-dead-old.sh'), old, old);
      // An unrelated file in the same cache dir must be invisible to the sweep.
      await writeFile(aged('someone-elses-file.sh'), 'not ours\n');

      const removed = await pruneAgentSessionPreambles(['live-old']);

      expect(removed).toBe(1);
      expect(existsSync(aged('codeman-agent-dead-old.sh'))).toBe(false);
      // A live session's cache is load-bearing: the skill's two-line loader reads it
      // mid-run, so age alone must never take it.
      expect(existsSync(aged('codeman-agent-live-old.sh'))).toBe(true);
      // And a recently-seeded one belongs to a session this process may not know about.
      expect(existsSync(aged('codeman-agent-dead-fresh.sh'))).toBe(true);
      expect(existsSync(aged('someone-elses-file.sh'))).toBe(true);
    });
  });

  it('pruneAgentSessionPreambles reports 0 rather than throwing when there is no cache dir', async () => {
    const prevXdg = process.env.XDG_CACHE_HOME;
    process.env.XDG_CACHE_HOME = join(casePath, 'no-such-cache');
    try {
      expect(await pruneAgentSessionPreambles([])).toBe(0);
    } finally {
      if (prevXdg === undefined) delete process.env.XDG_CACHE_HOME;
      else process.env.XDG_CACHE_HOME = prevXdg;
    }
  });

  it('seedAgentSessionPreamble falls back to ~/.cache when XDG_CACHE_HOME is unset', async () => {
    const prevXdg = process.env.XDG_CACHE_HOME;
    delete process.env.XDG_CACHE_HOME;
    try {
      await seedAgentSessionPreamble('seed-home-session');
      // setup.ts points HOME at a per-file fixture, so this never touches the real ~.
      const target = join(homedir(), '.cache', 'codeman-agent-seed-home-session.sh');
      expect(existsSync(target)).toBe(true);
    } finally {
      if (prevXdg !== undefined) process.env.XDG_CACHE_HOME = prevXdg;
    }
  });
});

describe('refreshUserAgentSkill (the user-level copy must not rot)', () => {
  const userSkillDir = () => join(homedir(), '.claude', 'skills', 'codeman');

  it('reports absent and installs nothing when there is no user-level copy', async () => {
    expect(await refreshUserAgentSkill()).toBe('absent');
    expect(existsSync(userSkillDir())).toBe(false);
  });

  it('refreshes a stale Codeman-managed user copy back to the packaged content', async () => {
    await mkdir(userSkillDir(), { recursive: true });
    // An old injected version: different content, marker intact. This is the exact
    // shape that shadowed every fresh per-case injection on 2026-08-14.
    await writeFile(join(userSkillDir(), 'SKILL.md'), `old skill body\n\n${MARKER_PREFIX}: installed by Codeman -->\n`);

    expect(await refreshUserAgentSkill()).toBe('refreshed');
    const refreshed = await readFile(join(userSkillDir(), 'SKILL.md'), 'utf-8');
    expect(refreshed.startsWith('---\nname: codeman')).toBe(true);
    expect(existsSync(join(userSkillDir(), 'reference', 'endpoints.md'))).toBe(true);

    // And a second run settles to unchanged.
    expect(await refreshUserAgentSkill()).toBe('unchanged');
  });

  it("leaves a user's own (unmarked) skill alone", async () => {
    await mkdir(userSkillDir(), { recursive: true });
    await writeFile(join(userSkillDir(), 'SKILL.md'), 'my own codeman skill\n');
    expect(await refreshUserAgentSkill()).toBe('foreign');
    expect(await readFile(join(userSkillDir(), 'SKILL.md'), 'utf-8')).toBe('my own codeman skill\n');
  });
});