@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/config.unit.test.ts

@@ -0,0 +1,356 @@
+/**
+ * Tests for agent/src/runtime/config.ts
+ *
+ * Strategy: call createConfig(agentHome) factory directly with a temp dir.
+ * No mock.module() needed — the factory reads env vars at call time.
+ * Uses SHIPWRIGHT_* env vars only.
+ */
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createConfig } from "./config.ts";
+
+const AGENT_HOME = join(
+  tmpdir(),
+  `shipwright-agent-config-test-${process.pid}`,
+);
+mkdirSync(AGENT_HOME, { recursive: true });
+
+// Set env vars before calling createConfig
+process.env.ANTHROPIC_MODEL = "claude-opus-4-6";
+process.env.SHIPWRIGHT_API_URL = "https://api.shipwright.app";
+process.env.SHIPWRIGHT_AGENT_API_KEY = "key-123";
+process.env.SHIPWRIGHT_AGENT_ID = "agent-xyz";
+
+const { config } = createConfig(AGENT_HOME);
+
+afterAll(() => {
+  rmSync(AGENT_HOME, { recursive: true, force: true });
+});
+
+// ─── config.claude ────────────────────────────────────────────────────────────
+
+describe("config.claude", () => {
+  test("model from ANTHROPIC_MODEL env var", () => {
+    expect(config.claude.model).toBe("claude-opus-4-6");
+  });
+
+  test("fallbackModel from ANTHROPIC_FALLBACK_MODEL env var", () => {
+    process.env.ANTHROPIC_FALLBACK_MODEL = "claude-sonnet-4-6";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.fallbackModel).toBe("claude-sonnet-4-6");
+    delete process.env.ANTHROPIC_FALLBACK_MODEL;
+  });
+
+  test("fallbackModel is undefined when ANTHROPIC_FALLBACK_MODEL not set", () => {
+    delete process.env.ANTHROPIC_FALLBACK_MODEL;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.fallbackModel).toBeUndefined();
+  });
+
+  test("effortLevel from ANTHROPIC_EFFORT_LEVEL env var", () => {
+    process.env.ANTHROPIC_EFFORT_LEVEL = "xhigh";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.effortLevel).toBe("xhigh");
+    delete process.env.ANTHROPIC_EFFORT_LEVEL;
+  });
+
+  test("effortLevel is undefined when ANTHROPIC_EFFORT_LEVEL not set", () => {
+    delete process.env.ANTHROPIC_EFFORT_LEVEL;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.effortLevel).toBeUndefined();
+  });
+
+  test("anthropicApiKey from ANTHROPIC_API_KEY env var", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-test-key";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.anthropicApiKey).toBe("sk-ant-test-key");
+    delete process.env.ANTHROPIC_API_KEY;
+  });
+
+  test("anthropicApiKey is undefined when ANTHROPIC_API_KEY not set", () => {
+    delete process.env.ANTHROPIC_API_KEY;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.anthropicApiKey).toBeUndefined();
+  });
+
+  test("model defaults to claude-sonnet-5-5 when ANTHROPIC_MODEL not set", () => {
+    const saved = process.env.ANTHROPIC_MODEL;
+    delete process.env.ANTHROPIC_MODEL;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.model).toBe("claude-sonnet-5-5");
+    process.env.ANTHROPIC_MODEL = saved;
+  });
+
+  test("timeoutMs defaults to 1hr when SHIPWRIGHT_CLAUDE_TIMEOUT_MS not set", () => {
+    expect(config.claude.timeoutMs).toBe(3_600_000);
+  });
+
+  test("timeoutMs from SHIPWRIGHT_CLAUDE_TIMEOUT_MS env var", () => {
+    process.env.SHIPWRIGHT_CLAUDE_TIMEOUT_MS = "5400000";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.timeoutMs).toBe(5_400_000);
+    delete process.env.SHIPWRIGHT_CLAUDE_TIMEOUT_MS;
+  });
+
+  test("timeoutMs falls back to default when non-numeric", () => {
+    process.env.SHIPWRIGHT_CLAUDE_TIMEOUT_MS = "not-a-number";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.timeoutMs).toBe(3_600_000);
+    delete process.env.SHIPWRIGHT_CLAUDE_TIMEOUT_MS;
+  });
+
+  test("timeoutMs falls back to default when zero or negative", () => {
+    process.env.SHIPWRIGHT_CLAUDE_TIMEOUT_MS = "0";
+    expect(createConfig(AGENT_HOME).config.claude.timeoutMs).toBe(3_600_000);
+    process.env.SHIPWRIGHT_CLAUDE_TIMEOUT_MS = "-1000";
+    expect(createConfig(AGENT_HOME).config.claude.timeoutMs).toBe(3_600_000);
+    delete process.env.SHIPWRIGHT_CLAUDE_TIMEOUT_MS;
+  });
+
+  test("timeoutMs falls back to default when non-integer", () => {
+    process.env.SHIPWRIGHT_CLAUDE_TIMEOUT_MS = "1500.5";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.timeoutMs).toBe(3_600_000);
+    delete process.env.SHIPWRIGHT_CLAUDE_TIMEOUT_MS;
+  });
+
+  test("idleTimeoutMs defaults to 25min when SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS not set", () => {
+    expect(config.claude.idleTimeoutMs).toBe(1_500_000);
+  });
+
+  test("idleTimeoutMs from SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS env var", () => {
+    process.env.SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS = "900000";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.idleTimeoutMs).toBe(900_000);
+    delete process.env.SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS;
+  });
+
+  test("idleTimeoutMs falls back to default when non-numeric", () => {
+    process.env.SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS = "not-a-number";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.idleTimeoutMs).toBe(1_500_000);
+    delete process.env.SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS;
+  });
+
+  test("idleTimeoutMs falls back to default when zero or negative", () => {
+    process.env.SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS = "0";
+    expect(createConfig(AGENT_HOME).config.claude.idleTimeoutMs).toBe(
+      1_500_000,
+    );
+    process.env.SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS = "-1000";
+    expect(createConfig(AGENT_HOME).config.claude.idleTimeoutMs).toBe(
+      1_500_000,
+    );
+    delete process.env.SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS;
+  });
+
+  test("idleTimeoutMs falls back to default when non-integer", () => {
+    process.env.SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS = "1500.5";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.claude.idleTimeoutMs).toBe(1_500_000);
+    delete process.env.SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS;
+  });
+});
+
+// ─── config.shipwright ────────────────────────────────────────────────────────
+
+describe("config.shipwright", () => {
+  test("apiUrl from SHIPWRIGHT_API_URL", () => {
+    expect(config.shipwright.apiUrl).toBe("https://api.shipwright.app");
+  });
+
+  test("apiKey from SHIPWRIGHT_AGENT_API_KEY", () => {
+    expect(config.shipwright.apiKey).toBe("key-123");
+  });
+
+  test("agentId from SHIPWRIGHT_AGENT_ID", () => {
+    expect(config.shipwright.agentId).toBe("agent-xyz");
+  });
+
+  test("apiUrl is undefined when SHIPWRIGHT_API_URL not set", () => {
+    const saved = process.env.SHIPWRIGHT_API_URL;
+    delete process.env.SHIPWRIGHT_API_URL;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.shipwright.apiUrl).toBeUndefined();
+    process.env.SHIPWRIGHT_API_URL = saved;
+  });
+});
+
+// ─── config.paths ─────────────────────────────────────────────────────────────
+
+describe("config.paths", () => {
+  test("home is agentHome", () => {
+    expect(config.paths.home).toBe(AGENT_HOME);
+  });
+
+  test("workspace is inside agentHome", () => {
+    expect(config.paths.workspace).toContain(AGENT_HOME);
+    expect(config.paths.workspace).toContain("workspace");
+  });
+
+  test("sessions is agentHome/sessions.json", () => {
+    expect(config.paths.sessions).toBe(join(AGENT_HOME, "sessions.json"));
+  });
+});
+
+// ─── config.slack ─────────────────────────────────────────────────────────────
+
+describe("config.slack", () => {
+  test("botToken from SLACK_BOT_TOKEN", () => {
+    process.env.SLACK_BOT_TOKEN = "xoxb-test-bot";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.slack.botToken).toBe("xoxb-test-bot");
+    delete process.env.SLACK_BOT_TOKEN;
+  });
+
+  test("botToken is undefined when SLACK_BOT_TOKEN not set", () => {
+    delete process.env.SLACK_BOT_TOKEN;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.slack.botToken).toBeUndefined();
+  });
+
+  test("appToken from SLACK_APP_TOKEN", () => {
+    process.env.SLACK_APP_TOKEN = "xapp-test-token";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.slack.appToken).toBe("xapp-test-token");
+    delete process.env.SLACK_APP_TOKEN;
+  });
+
+  test("appToken is undefined when SLACK_APP_TOKEN not set", () => {
+    delete process.env.SLACK_APP_TOKEN;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.slack.appToken).toBeUndefined();
+  });
+
+  test("signingSecret from SLACK_SIGNING_SECRET", () => {
+    process.env.SLACK_SIGNING_SECRET = "abc123secret";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.slack.signingSecret).toBe("abc123secret");
+    delete process.env.SLACK_SIGNING_SECRET;
+  });
+
+  test("signingSecret is undefined when SLACK_SIGNING_SECRET not set", () => {
+    delete process.env.SLACK_SIGNING_SECRET;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.slack.signingSecret).toBeUndefined();
+  });
+
+  test("adminToken from SLACK_ADMIN_TOKEN", () => {
+    process.env.SLACK_ADMIN_TOKEN = "xoxp-admin-token";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.slack.adminToken).toBe("xoxp-admin-token");
+    delete process.env.SLACK_ADMIN_TOKEN;
+  });
+
+  test("adminToken is undefined when SLACK_ADMIN_TOKEN not set", () => {
+    delete process.env.SLACK_ADMIN_TOKEN;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.slack.adminToken).toBeUndefined();
+  });
+});
+
+// ─── config.alerts ────────────────────────────────────────────────────────────
+
+describe("config.alerts", () => {
+  test("channel from SLACK_ALERT_CHANNEL", () => {
+    process.env.SLACK_ALERT_CHANNEL = "#alerts";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.alerts.channel).toBe("#alerts");
+    delete process.env.SLACK_ALERT_CHANNEL;
+  });
+
+  test("channel is undefined when SLACK_ALERT_CHANNEL not set", () => {
+    delete process.env.SLACK_ALERT_CHANNEL;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.alerts.channel).toBeUndefined();
+  });
+});
+
+// ─── config.owner ─────────────────────────────────────────────────────────────
+
+describe("config.owner", () => {
+  test("user from SLACK_OWNER_USER", () => {
+    process.env.SLACK_OWNER_USER = "U012AB3CD";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.owner.user).toBe("U012AB3CD");
+    delete process.env.SLACK_OWNER_USER;
+  });
+
+  test("user is undefined when SLACK_OWNER_USER not set", () => {
+    delete process.env.SLACK_OWNER_USER;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.owner.user).toBeUndefined();
+  });
+});
+
+// ─── config.voice ─────────────────────────────────────────────────────────────
+
+describe("config.voice", () => {
+  test("groqApiKey from GROQ_API_KEY", () => {
+    process.env.GROQ_API_KEY = "gsk-test-key";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.voice.groqApiKey).toBe("gsk-test-key");
+    delete process.env.GROQ_API_KEY;
+  });
+
+  test("groqApiKey is undefined when GROQ_API_KEY not set", () => {
+    delete process.env.GROQ_API_KEY;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.voice.groqApiKey).toBeUndefined();
+  });
+
+  test("elevenLabsApiKey from ELEVENLABS_API_KEY", () => {
+    process.env.ELEVENLABS_API_KEY = "eleven-test-key";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.voice.elevenLabsApiKey).toBe("eleven-test-key");
+    delete process.env.ELEVENLABS_API_KEY;
+  });
+
+  test("elevenLabsApiKey is undefined when ELEVENLABS_API_KEY not set", () => {
+    delete process.env.ELEVENLABS_API_KEY;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.voice.elevenLabsApiKey).toBeUndefined();
+  });
+
+  test("voiceId from ELEVENLABS_VOICE_ID", () => {
+    process.env.ELEVENLABS_VOICE_ID = "voice-abc";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.voice.voiceId).toBe("voice-abc");
+    delete process.env.ELEVENLABS_VOICE_ID;
+  });
+
+  test("voiceId is undefined when ELEVENLABS_VOICE_ID not set", () => {
+    delete process.env.ELEVENLABS_VOICE_ID;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.voice.voiceId).toBeUndefined();
+  });
+
+  test("piperVoice from PIPER_VOICE", () => {
+    process.env.PIPER_VOICE = "en_GB-alan-medium";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.voice.piperVoice).toBe("en_GB-alan-medium");
+    delete process.env.PIPER_VOICE;
+  });
+
+  test("piperVoice is undefined when PIPER_VOICE not set", () => {
+    delete process.env.PIPER_VOICE;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.voice.piperVoice).toBeUndefined();
+  });
+
+  test("whisperServiceUrl from WHISPER_SERVICE_URL", () => {
+    process.env.WHISPER_SERVICE_URL = "http://localhost:9000";
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.voice.whisperServiceUrl).toBe("http://localhost:9000");
+    delete process.env.WHISPER_SERVICE_URL;
+  });
+
+  test("whisperServiceUrl is undefined when WHISPER_SERVICE_URL not set", () => {
+    delete process.env.WHISPER_SERVICE_URL;
+    const { config: cfg } = createConfig(AGENT_HOME);
+    expect(cfg.voice.whisperServiceUrl).toBeUndefined();
+  });
+});

package/context-stamp.ts

@@ -0,0 +1,189 @@
+/**
+ * agent/src/runtime/context-stamp.ts
+ *
+ * Fingerprints the markdown Claude Code loads into every session from the
+ * agent's workspace — the workspace `CLAUDE.md`, the files it `@`-imports,
+ * and every `.claude/rules/*.md` without a `paths:` frontmatter (path-scoped
+ * rules load on demand and are excluded) — plus the plugin version, since
+ * the plugin's skill listing is also part of the always-loaded context.
+ *
+ * The resulting `contextFingerprint` is stamped onto each cron run so token
+ * and outcome series can be grouped by *what the model was given*, not by
+ * when a change merged. Two runs with the same fingerprint saw the same
+ * always-loaded text; a CLAUDE.md edit produces a new fingerprint and the
+ * prompt-audit patrol reads the before/after series by that key.
+ *
+ * Pure core (`computeContextStamp`) with injected file access; the
+ * production reader (`createContextStampReader`) wraps `node:fs` and is
+ * cheap enough to call once per run — the always-loaded set is a handful of
+ * small files.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export interface RunContextStamp {
+  /** First 12 hex chars of sha256 over the always-loaded set + plugin version. */
+  contextFingerprint: string;
+  pluginVersion: string | null;
+  claudeCodeVersion: string | null;
+}
+
+export interface ContextStampDeps {
+  /** Workspace root — the cwd Claude Code is spawned in. */
+  workspace: string;
+  /** Returns file contents, or null when the file is missing/unreadable. */
+  readFile: (absPath: string) => string | null;
+  /** Lists `.md` files (absolute paths) under `<workspace>/.claude/rules`, recursively. */
+  listRuleFiles: () => string[];
+  pluginVersion: () => string | null;
+  claudeCodeVersion: () => string | null;
+}
+
+/** Fenced code blocks and inline code spans are skipped by Claude Code's import parser. */
+const FENCE_RE = /```[\s\S]*?```/g;
+const INLINE_CODE_RE = /`[^`\n]*`/g;
+const IMPORT_RE = /(?:^|\s)@((?:\\ |[^\s`])+)/g;
+
+/** Extracts `@path` imports the way Claude Code resolves them (one hop, relative to the file). */
+export function extractImports(content: string): string[] {
+  const stripped = content.replace(FENCE_RE, "").replace(INLINE_CODE_RE, "");
+  const out: string[] = [];
+  for (const m of stripped.matchAll(IMPORT_RE)) {
+    const raw = m[1];
+    if (!raw) continue;
+    // Email-ish tokens ("user@host") never match because the regex requires
+    // whitespace or line start before the "@"; strip trailing punctuation.
+    const cleaned = raw.replace(/\\ /g, " ").replace(/[.,;:)]+$/, "");
+    if (cleaned.length > 0) out.push(cleaned);
+  }
+  return out;
+}
+
+/** True when the rule file's YAML frontmatter declares a `paths:` key (on-demand rule). */
+export function hasPathsFrontmatter(content: string): boolean {
+  if (!content.startsWith("---")) return false;
+  const end = content.indexOf("\n---", 3);
+  if (end === -1) return false;
+  const frontmatter = content.slice(3, end);
+  return /^\s*paths\s*:/m.test(frontmatter);
+}
+
+export function computeContextStamp(deps: ContextStampDeps): RunContextStamp {
+  const hash = createHash("sha256");
+  const claudeMdPath = join(deps.workspace, "CLAUDE.md");
+  const claudeMd = deps.readFile(claudeMdPath);
+  hash.update("CLAUDE.md\0");
+  hash.update(claudeMd ?? "");
+  hash.update("\0");
+
+  if (claudeMd !== null) {
+    for (const rel of extractImports(claudeMd)) {
+      const abs = resolve(deps.workspace, rel);
+      hash.update(`import:${rel}\0`);
+      hash.update(deps.readFile(abs) ?? "");
+      hash.update("\0");
+    }
+  }
+
+  const rules = deps
+    .listRuleFiles()
+    .map((abs) => ({ abs, content: deps.readFile(abs) }))
+    .filter(
+      (r): r is { abs: string; content: string } =>
+        r.content !== null && !hasPathsFrontmatter(r.content),
+    )
+    .sort((a, b) => (a.abs < b.abs ? -1 : a.abs > b.abs ? 1 : 0));
+  for (const rule of rules) {
+    hash.update(`rule:${rule.abs.slice(deps.workspace.length)}\0`);
+    hash.update(rule.content);
+    hash.update("\0");
+  }
+
+  const pluginVersion = deps.pluginVersion();
+  hash.update(`plugin:${pluginVersion ?? ""}\0`);
+
+  return {
+    contextFingerprint: hash.digest("hex").slice(0, 12),
+    pluginVersion,
+    claudeCodeVersion: deps.claudeCodeVersion(),
+  };
+}
+
+/**
+ * Fail-soft wrapper: any error from the injected deps (unreadable rules dir,
+ * throwing version probe) yields `null` — an unstamped run — never a throw.
+ */
+export function tryComputeContextStamp(
+  deps: ContextStampDeps,
+): RunContextStamp | null {
+  try {
+    return computeContextStamp(deps);
+  } catch {
+    return null;
+  }
+}
+
+function listMarkdownRecursive(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry);
+    let isDir = false;
+    try {
+      isDir = statSync(abs).isDirectory();
+    } catch {
+      continue;
+    }
+    if (isDir) out.push(...listMarkdownRecursive(abs));
+    else if (entry.endsWith(".md")) out.push(abs);
+  }
+  return out;
+}
+
+function readFileOrNull(absPath: string): string | null {
+  try {
+    return readFileSync(absPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** Reads `version` from a plugin.json / package.json-shaped file, or null. */
+function readVersionFile(absPath: string): string | null {
+  const raw = readFileOrNull(absPath);
+  if (raw === null) return null;
+  try {
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    return typeof parsed.version === "string" ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+interface ContextStampReaderOptions {
+  workspace: string;
+  /** Path to the shipwright plugin's `plugin.json` (its `version` is the plugin version). */
+  pluginJsonPath: string;
+  claudeCodeVersion: () => string | null;
+}
+
+/**
+ * Production reader: `node:fs`-backed `computeContextStamp`. Never throws —
+ * a missing workspace or plugin manifest just fingerprints as empty, and any
+ * unexpected read error yields `null` (unstamped).
+ */
+export function createContextStampReader(
+  opts: ContextStampReaderOptions,
+): () => RunContextStamp | null {
+  return () =>
+    tryComputeContextStamp({
+      workspace: opts.workspace,
+      readFile: readFileOrNull,
+      listRuleFiles: () =>
+        listMarkdownRecursive(join(opts.workspace, ".claude", "rules")),
+      pluginVersion: () => readVersionFile(opts.pluginJsonPath),
+      claudeCodeVersion: opts.claudeCodeVersion,
+    });
+}

package/context-stamp.unit.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type ContextStampDeps,
+  computeContextStamp,
+  extractImports,
+  hasPathsFrontmatter,
+  tryComputeContextStamp,
+} from "./context-stamp.ts";
+
+const WORKSPACE = "/ws";
+
+function makeDeps(
+  files: Record<string, string>,
+  overrides: Partial<ContextStampDeps> = {},
+): ContextStampDeps {
+  return {
+    workspace: WORKSPACE,
+    readFile: (abs) => files[abs] ?? null,
+    listRuleFiles: () =>
+      Object.keys(files).filter((p) =>
+        p.startsWith(`${WORKSPACE}/.claude/rules/`),
+      ),
+    pluginVersion: () => "1.363.0",
+    claudeCodeVersion: () => "2.1.285",
+    ...overrides,
+  };
+}
+
+describe("extractImports", () => {
+  test("finds @path imports and ignores code spans, fences, and emails", () => {
+    const content = [
+      "# Title",
+      "@SOUL.md",
+      "- identity @IDENTITY.md and voice @VOICE.md.",
+      "Mention `@README` literally.",
+      "```",
+      "@NOT_IMPORTED.md",
+      "```",
+      "Contact ops@example.com",
+      "@Design\\ Docs/api.md",
+    ].join("\n");
+    expect(extractImports(content)).toEqual([
+      "SOUL.md",
+      "IDENTITY.md",
+      "VOICE.md",
+      "Design Docs/api.md",
+    ]);
+  });
+});
+
+describe("hasPathsFrontmatter", () => {
+  test("detects a paths key in frontmatter only", () => {
+    expect(hasPathsFrontmatter("---\npaths:\n  - src/**\n---\nbody")).toBe(
+      true,
+    );
+    expect(hasPathsFrontmatter("---\ndescription: x\n---\npaths: not fm")).toBe(
+      false,
+    );
+    expect(hasPathsFrontmatter("no frontmatter\npaths:")).toBe(false);
+  });
+});
+
+describe("computeContextStamp", () => {
+  const base = {
+    [`${WORKSPACE}/CLAUDE.md`]: "# Agent\n@SOUL.md\n",
+    [`${WORKSPACE}/SOUL.md`]: "be kind",
+    [`${WORKSPACE}/.claude/rules/always.md`]: "always rule",
+    [`${WORKSPACE}/.claude/rules/scoped.md`]:
+      "---\npaths:\n  - x/**\n---\nscoped",
+  };
+
+  test("is stable for identical inputs and 12 hex chars long", () => {
+    const a = computeContextStamp(makeDeps(base));
+    const b = computeContextStamp(makeDeps(base));
+    expect(a.contextFingerprint).toMatch(/^[0-9a-f]{12}$/);
+    expect(a).toEqual(b);
+    expect(a.pluginVersion).toBe("1.363.0");
+    expect(a.claudeCodeVersion).toBe("2.1.285");
+  });
+
+  test("changes when CLAUDE.md, an import, an always-rule, or the plugin version changes", () => {
+    const ref = computeContextStamp(makeDeps(base)).contextFingerprint;
+    const edits: Array<Record<string, string>> = [
+      { [`${WORKSPACE}/CLAUDE.md`]: "# Agent v2\n@SOUL.md\n" },
+      { [`${WORKSPACE}/SOUL.md`]: "be kinder" },
+      { [`${WORKSPACE}/.claude/rules/always.md`]: "always rule v2" },
+    ];
+    for (const edit of edits) {
+      const fp = computeContextStamp(
+        makeDeps({ ...base, ...edit }),
+      ).contextFingerprint;
+      expect(fp).not.toBe(ref);
+    }
+    const bumped = computeContextStamp(
+      makeDeps(base, { pluginVersion: () => "1.364.0" }),
+    ).contextFingerprint;
+    expect(bumped).not.toBe(ref);
+  });
+
+  test("ignores path-scoped rules, which load on demand", () => {
+    const ref = computeContextStamp(makeDeps(base)).contextFingerprint;
+    const edited = computeContextStamp(
+      makeDeps({
+        ...base,
+        [`${WORKSPACE}/.claude/rules/scoped.md`]:
+          "---\npaths:\n  - x/**\n---\nscoped v2",
+      }),
+    ).contextFingerprint;
+    expect(edited).toBe(ref);
+  });
+
+  test("rule order does not affect the fingerprint", () => {
+    const files = {
+      ...base,
+      [`${WORKSPACE}/.claude/rules/b.md`]: "b",
+      [`${WORKSPACE}/.claude/rules/a.md`]: "a",
+    };
+    const forward = computeContextStamp(makeDeps(files)).contextFingerprint;
+    const reversed = computeContextStamp(
+      makeDeps(files, {
+        listRuleFiles: () =>
+          Object.keys(files)
+            .filter((p) => p.includes("/.claude/rules/"))
+            .reverse(),
+      }),
+    ).contextFingerprint;
+    expect(reversed).toBe(forward);
+  });
+
+  test("a workspace with no CLAUDE.md still produces a stamp", () => {
+    const stamp = computeContextStamp(
+      makeDeps(
+        {},
+        { pluginVersion: () => null, claudeCodeVersion: () => null },
+      ),
+    );
+    expect(stamp.contextFingerprint).toMatch(/^[0-9a-f]{12}$/);
+    expect(stamp.pluginVersion).toBeNull();
+    expect(stamp.claudeCodeVersion).toBeNull();
+  });
+
+  test("read errors yield an unstamped result instead of throwing", () => {
+    const throwing = () => {
+      throw new Error("EACCES");
+    };
+    expect(
+      tryComputeContextStamp(makeDeps({}, { listRuleFiles: throwing })),
+    ).toBeNull();
+    expect(
+      tryComputeContextStamp(makeDeps({}, { readFile: throwing })),
+    ).toBeNull();
+    expect(
+      tryComputeContextStamp(makeDeps({}, { claudeCodeVersion: throwing })),
+    ).toBeNull();
+    expect(tryComputeContextStamp(makeDeps({}))?.contextFingerprint).toMatch(
+      /^[0-9a-f]{12}$/,
+    );
+  });
+});