chainlesschain 0.162.161 → 0.162.163

package/src/lib/context-breakdown.js

@@ -0,0 +1,116 @@
+/**
+ * Per-source token attribution for `cc context --sources` — the P1
+ * large-monorepo "/context 按来源分解" lever. The base `cc context` view buckets
+ * a session's stored messages by ROLE; this adds a BY-SOURCE view that also
+ * attributes the project-memory instruction files (cc.md / CLAUDE.md / rules /
+ * @imports) that would be loaded for the current working directory, each with
+ * its own token cost and provenance — so a user can see WHICH instruction file
+ * (or message class) fills the context window.
+ *
+ * Pure: token counting for instruction files is delegated to the injected
+ * estimator (the same CJK-aware `estimateTokens` the window sizing uses);
+ * message-role buckets already arrive pre-counted. No I/O.
+ *
+ * Scope note: skills and MCP tool schemas are runtime tool definitions loaded
+ * when an agent actually runs — they are NOT part of a persisted transcript nor
+ * of the project-instruction set, so they are intentionally not attributed here.
+ */
+
+import path from "path";
+
+/**
+ * Display path for an instruction source: relative-to-cwd when the file lives
+ * inside cwd, else the absolute path (a `~/.claude/…` user-scope file, or an
+ * @import that escaped the tree, is clearer shown in full).
+ */
+export function relativizeInstructionPath(absPath, cwd) {
+  if (!absPath) return "";
+  if (!cwd) return absPath;
+  try {
+    const rel = path.relative(cwd, absPath);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return absPath;
+    return rel.split(path.sep).join("/");
+  } catch {
+    return absPath;
+  }
+}
+
+/**
+ * Per-file instruction sources from `loadProjectInstructions().files`.
+ *
+ * @param {Array<{path,scope,content,truncated}>} files
+ * @param {(t:string)=>number} estimateTokens
+ * @param {string} [cwd]
+ * @returns {{ sources: Array<{scope,source,path,tokens,truncated}>, total:number }}
+ */
+export function breakdownInstructionSources(files, estimateTokens, cwd) {
+  const est = typeof estimateTokens === "function" ? estimateTokens : () => 0;
+  const list = Array.isArray(files) ? files : [];
+  const sources = list.map((f) => ({
+    scope: f?.scope || "project",
+    source: relativizeInstructionPath(f?.path, cwd),
+    path: f?.path || "",
+    tokens: est(typeof f?.content === "string" ? f.content : ""),
+    truncated: Boolean(f?.truncated),
+  }));
+  const total = sources.reduce((s, x) => s + x.tokens, 0);
+  return { sources, total };
+}
+
+// role bucket key → { label, kind } for the ranked source list.
+const MESSAGE_SOURCE_ROWS = [
+  ["system", "system messages", "message"],
+  ["user", "user messages", "message"],
+  ["assistant", "assistant messages", "message"],
+  ["tool", "tool results", "message"],
+  ["toolCalls", "tool calls", "tool_calls"],
+];
+
+/**
+ * Merge the project-memory instruction total with the per-role message buckets
+ * into ONE ranked source list (largest first) with each source's share of the
+ * combined by-source total. The message buckets are the same ones
+ * `categorizeContext` produces; instructions are folded in as a single group so
+ * the ranked view stays readable (per-file detail lives in the instructions
+ * breakdown).
+ *
+ * @param {object} args
+ * @param {number} [args.instructionTotal=0]  Σ instruction-file tokens
+ * @param {object} [args.buckets={}]           categorizeContext buckets
+ * @param {object} [args.counts={}]            categorizeContext counts
+ * @returns {{ sources: Array<{kind,source,tokens,count,share}>, total:number }}
+ */
+export function rankContextSources({
+  instructionTotal = 0,
+  buckets = {},
+  counts = {},
+} = {}) {
+  const rows = [];
+  if (instructionTotal > 0) {
+    rows.push({
+      kind: "instructions",
+      source: "project memory (instructions)",
+      tokens: instructionTotal,
+      count: null,
+    });
+  }
+  for (const [key, label, kind] of MESSAGE_SOURCE_ROWS) {
+    const tok = buckets[key] || 0;
+    if (tok > 0) {
+      rows.push({
+        kind,
+        source: label,
+        tokens: tok,
+        count: counts[key] ?? null,
+      });
+    }
+  }
+  const total = rows.reduce((s, x) => s + x.tokens, 0);
+  // Stable sort: tokens desc, then source name for deterministic ties.
+  rows.sort((a, b) => b.tokens - a.tokens || a.source.localeCompare(b.source));
+  const sources = rows.map((r) => ({
+    ...r,
+    share: total ? r.tokens / total : 0,
+  }));
+  return { sources, total };
+}

package/src/lib/docs-drift.js

@@ -0,0 +1,166 @@
+/**
+ * Auto-generated CLI reference + doc-drift detection (P2 "文档").
+ *
+ * The gap: commands, agent tools, flags, exit codes, and protocol fields are
+ * documented by hand and silently drift from the code. `command-manifest.json`
+ * (regenerated + CI-guarded) and the `AGENT_TOOLS` registry are the authoritative
+ * data sources; nothing turns them into a reference doc or checks a hand-written
+ * doc against them.
+ *
+ * This is the PURE core: build a canonical reference from the manifest + tool
+ * list, render it, and diff a documentation surface against the authoritative
+ * sets to catch drift in BOTH directions (documented-but-gone / present-but-
+ * undocumented). No I/O — the caller reads the manifest, tool names, and doc text.
+ */
+
+/** Normalize the command-manifest.json commands into a stable reference list. */
+export function extractCommands(manifest = {}) {
+  const commands = Array.isArray(manifest.commands) ? manifest.commands : [];
+  return commands
+    .map((c) => ({
+      name: String(c?.name || "").trim(),
+      aliases: Array.isArray(c?.aliases)
+        ? c.aliases.map((a) => String(a).trim()).filter(Boolean)
+        : [],
+      summary: String(c?.summary || "").trim(),
+    }))
+    .filter((c) => c.name)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Normalize the AGENT_TOOLS registry into a sorted, de-duped name list. Accepts
+ * plain strings, `{ name }` contracts, and OpenAI-style `{ function: { name } }`
+ * function-tool definitions.
+ */
+export function extractToolNames(tools = []) {
+  const names = (Array.isArray(tools) ? tools : [])
+    .map((t) => {
+      if (typeof t === "string") return t.trim();
+      const n = t?.name ?? t?.function?.name;
+      return String(n || "").trim();
+    })
+    .filter(Boolean);
+  return [...new Set(names)].sort();
+}
+
+/** Every command token a user can invoke: primary names + aliases. */
+export function commandTokens(commands) {
+  const set = new Set();
+  for (const c of commands) {
+    set.add(c.name);
+    for (const a of c.aliases) set.add(a);
+  }
+  return set;
+}
+
+/**
+ * Build the canonical reference object from the authoritative sources. This is
+ * the data a generator serializes; `renderReferenceMarkdown` renders it.
+ */
+export function buildCliReference({ manifest = {}, tools = [] } = {}) {
+  const commands = extractCommands(manifest);
+  const toolNames = extractToolNames(tools);
+  return {
+    commandCount: commands.length,
+    toolCount: toolNames.length,
+    commands,
+    tools: toolNames,
+  };
+}
+
+/** Deterministic markdown render of the reference (stable output for diffing). */
+export function renderReferenceMarkdown(reference) {
+  const lines = [];
+  lines.push("# CLI Reference (generated)");
+  lines.push("");
+  lines.push(
+    "<!-- Generated from command-manifest.json + AGENT_TOOLS. Do not edit by hand. -->",
+  );
+  lines.push("");
+  lines.push(`## Commands (${reference.commandCount})`);
+  lines.push("");
+  for (const c of reference.commands) {
+    const alias = c.aliases.length ? ` (aliases: ${c.aliases.join(", ")})` : "";
+    lines.push(`- \`${c.name}\`${alias}${c.summary ? ` — ${c.summary}` : ""}`);
+  }
+  lines.push("");
+  lines.push(`## Agent tools (${reference.toolCount})`);
+  lines.push("");
+  for (const name of reference.tools) lines.push(`- \`${name}\``);
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Which authoritative command/tool tokens appear as literal `cc <token>` /
+ * backticked `<token>` mentions in the doc text. We look for word-boundary
+ * mentions; a token is "documented" if it appears anywhere in the doc.
+ */
+function isMentioned(doc, token) {
+  if (!token) return false;
+  const esc = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(^|[^\\w-])${esc}([^\\w-]|$)`).test(doc);
+}
+
+/**
+ * Diff a documentation surface against the authoritative sets. Reports drift both
+ * ways so neither a NEW undocumented command nor a REMOVED-but-still-documented
+ * one slips through.
+ *
+ * @param {object} args
+ *   manifest — command-manifest.json object
+ *   tools    — AGENT_TOOLS array
+ *   doc      — the documentation text to check
+ *   knownTokens — optional extra tokens to treat as authoritative (e.g. flags,
+ *                 exit codes, protocol fields) to catch their drift too
+ * @returns {{ undocumentedCommands, undocumentedTools, staleCommandMentions,
+ *             ok, counts }}
+ */
+export function detectDocDrift({
+  manifest = {},
+  tools = [],
+  doc = "",
+  knownTokens = [],
+} = {}) {
+  const commands = extractCommands(manifest);
+  const toolNames = extractToolNames(tools);
+  const text = String(doc || "");
+
+  const undocumentedCommands = commands
+    .filter((c) => !isMentioned(text, c.name))
+    .map((c) => c.name);
+  const undocumentedTools = toolNames.filter((n) => !isMentioned(text, n));
+
+  // Tokens the doc claims as commands (in a `cc <token>` construct) that are not
+  // in the manifest → stale references to removed/renamed commands.
+  const known = commandTokens(commands);
+  for (const t of knownTokens) known.add(String(t));
+  const staleCommandMentions = [];
+  const seen = new Set();
+  const ccRe = /\bcc\s+([a-z][a-z0-9-]*)\b/g;
+  let m;
+  while ((m = ccRe.exec(text)) !== null) {
+    const tok = m[1];
+    if (!known.has(tok) && !seen.has(tok)) {
+      seen.add(tok);
+      staleCommandMentions.push(tok);
+    }
+  }
+
+  const counts = {
+    undocumentedCommands: undocumentedCommands.length,
+    undocumentedTools: undocumentedTools.length,
+    staleCommandMentions: staleCommandMentions.length,
+  };
+  return {
+    undocumentedCommands,
+    undocumentedTools,
+    staleCommandMentions,
+    counts,
+    ok:
+      counts.undocumentedCommands === 0 &&
+      counts.undocumentedTools === 0 &&
+      counts.staleCommandMentions === 0,
+  };
+}

package/src/lib/doctor-checkup.js

@@ -26,6 +26,7 @@ import {
 import { execSync } from "node:child_process";
 import { join, basename } from "node:path";
 import { getHomeDir, getConfigPath } from "./paths.js";
+import { checkAgenda, checkInstructionFiles } from "./runtime-checkup.js";
 
 export const CHECK_LEVELS = Object.freeze({
   OK: "ok",
@@ -314,6 +315,58 @@ async function pluginSection(opts, _deps2) {
   } catch (err) {
     checks.push(failedCheck("plugins", "Installed plugins", err));
   }
+
+  // Broken manifests + un-consented capabilities (Phase 3 capability gap).
+  // Distinct from the signature-lock check above: re-discover to get each
+  // plugin's parsed manifest (listInstalled drops it) so we can flag an invalid
+  // manifest and any DECLARED capability set the user has not consented to.
+  try {
+    const { discoverPlugins } = await import("./plugin-runtime/scopes.js");
+    const { isPluginCapabilityConsented } =
+      await import("./plugin-runtime/capability-consent.js");
+    const { checkPluginsAndLsp } = await import("./runtime-checkup.js");
+    const discovered =
+      discoverPlugins({ cwd: opts.cwd || process.cwd(), skipPolicy: true }) ||
+      [];
+    // Broken manifests → warn (shared runtime-checkup evaluator).
+    for (const f of checkPluginsAndLsp(
+      discovered.map((p) => ({
+        id: p.name,
+        healthy: p.manifest?.ok !== false,
+        kind: "plugin",
+      })),
+    )) {
+      checks.push(
+        check(
+          f.id,
+          `plugin ${f.ref}`,
+          CHECK_LEVELS.WARN,
+          `${f.message} — ${f.remediation}`,
+        ),
+      );
+    }
+    // Declared capabilities not yet consented → warn.
+    for (const p of discovered) {
+      if (!p.manifest?.capabilitiesDeclared) continue;
+      const consented = isPluginCapabilityConsented(
+        { name: p.name, scope: p.scope, version: p.version },
+        p.manifest.capabilities,
+      );
+      if (!consented) {
+        checks.push(
+          check(
+            "plugin-capability-unconsented",
+            `plugin ${p.name}`,
+            CHECK_LEVELS.WARN,
+            `declares capabilities not yet consented — run \`cc plugin consent ${p.name}\``,
+          ),
+        );
+      }
+    }
+  } catch (err) {
+    checks.push(failedCheck("plugin-capabilities", "plugin capabilities", err));
+  }
+
   return { id: "plugins", title: "Plugin trust", checks };
 }
 
@@ -540,6 +593,80 @@ async function worktreeSection(opts, deps) {
   return { id: "worktrees", title: "Git worktrees", checks };
 }
 
+// ── runtime checkup: agenda expiry + verbose instruction files ──────────────
+// Only the gaps the OTHER sections don't already cover. Stale sessions,
+// worktrees, orphan processes and lost background agents are handled by
+// transcriptSection / worktreeSection / backgroundSection — surfacing them here
+// too would double-report, so this section deliberately covers just the agenda
+// schedule store and the instruction files (cc.md / AGENTS.md / CLAUDE.md).
+const SEVERITY_TO_LEVEL = {
+  error: CHECK_LEVELS.ERR,
+  warn: CHECK_LEVELS.WARN,
+  info: CHECK_LEVELS.INFO,
+};
+
+async function runtimeSection(opts, deps) {
+  const checks = [];
+  const now = deps.now();
+
+  // Agenda schedule store — overdue/never-fired wakeups, retirable leftovers.
+  try {
+    const { AgentScheduleStore } = await import("./agent-schedule-store.js");
+    const store = new AgentScheduleStore();
+    const entries = store.list().map((e) => ({
+      id: e.id,
+      dueAt: e.kind === "wakeup" ? e.dueAt : e.nextAt,
+      recurring: e.kind !== "wakeup",
+    }));
+    for (const f of checkAgenda(entries, now)) {
+      checks.push(
+        check(
+          f.id,
+          `agenda ${f.ref}`,
+          SEVERITY_TO_LEVEL[f.severity] || CHECK_LEVELS.INFO,
+          `${f.message} — ${f.remediation}`,
+        ),
+      );
+    }
+  } catch (err) {
+    checks.push(failedCheck("agenda", "agenda schedule store", err));
+  }
+
+  // Instruction files — flag verbose ones (byte size only; a derivability
+  // heuristic would need code analysis and isn't computed here).
+  try {
+    const cwd = opts.cwd || process.cwd();
+    const files = [];
+    for (const name of ["cc.md", "AGENTS.md", "CLAUDE.md"]) {
+      const p = join(cwd, name);
+      if (deps.existsSync(p)) {
+        try {
+          files.push({ path: name, bytes: deps.statSync(p).size });
+        } catch {
+          // raced/unreadable — skip
+        }
+      }
+    }
+    for (const f of checkInstructionFiles(files)) {
+      checks.push(
+        check(
+          f.id,
+          f.ref,
+          SEVERITY_TO_LEVEL[f.severity] || CHECK_LEVELS.INFO,
+          `${f.message} — ${f.remediation}`,
+        ),
+      );
+    }
+  } catch (err) {
+    checks.push(failedCheck("instructions", "instruction files", err));
+  }
+
+  if (checks.length === 0) {
+    checks.push(check("runtime-clean", "runtime hygiene", CHECK_LEVELS.OK, ""));
+  }
+  return { id: "runtime", title: "Runtime checkup", checks };
+}
+
 /**
  * Collect all checkup sections. Never throws — a failing subsystem becomes an
  * `err` check inside its section.
@@ -557,6 +684,7 @@ export async function collectCheckupSections(opts = {}) {
     transcriptSection,
     backgroundSection,
     worktreeSection,
+    runtimeSection,
   ]) {
     try {
       sections.push(await build(opts, deps));

package/src/lib/hook-event-log.cjs

@@ -0,0 +1,193 @@
+"use strict";
+
+/**
+ * hook-event-log — a persistent, hash-chained, replay-safe log of the hook
+ * delivery envelopes produced by the unified event bus ([[hook-event-bus.cjs]]).
+ *
+ * The event bus already stamps every settings-hook delivery with a stable
+ * `event_id` (see [[settings-hook-events.cjs]] `withDeliveryId`), but until now
+ * the full envelope was discarded — so there was nothing to look up when a user
+ * wants `cc hook replay <event-id>`. This store persists each envelope to a
+ * tamper-evident JSONL log so the replay command has a real source.
+ *
+ * Design:
+ * - OPT-IN: recording only happens when `CC_HOOK_EVENT_LOG` is enabled, so the
+ *   default hook-firing path is byte-for-byte unchanged (no new IO per turn).
+ * - Hash chain: each line is `{envelope, prevHash, hash}` where
+ *   `hash = sha256(prevHash + stableStringify(envelope))`. Editing / deleting /
+ *   reordering any recorded line breaks the chain (mirrors the session
+ *   transcript integrity design), which `verifyHookEventChain` detects.
+ * - Size guard: the log rotates to `<file>.1` once it exceeds MAX_LOG_BYTES so
+ *   an always-on session can't grow it without bound.
+ * - Pure over injected IO (`_deps.fs` / `_deps.os`) so it is fully unit-testable
+ *   without touching the real home directory.
+ */
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+const { stableStringify } = require("./hook-event-bus.cjs");
+
+const _deps = { fs, os };
+
+/** Cap the always-on log at 5 MiB, then rotate to `<file>.1`. */
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+
+/** Default log location: `~/.chainlesschain/hook-events.jsonl`. */
+function hookEventLogPath(homedir) {
+  const home = homedir || _deps.os.homedir();
+  return path.join(home, ".chainlesschain", "hook-events.jsonl");
+}
+
+/** Recording is opt-in — `CC_HOOK_EVENT_LOG=1` (or `true`) turns it on. */
+function isHookEventLogEnabled(env = process.env) {
+  const v = String(env.CC_HOOK_EVENT_LOG || "").toLowerCase();
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+
+/** Hash one envelope against the previous chain hash (deterministic). */
+function computeChainHash(prevHash, envelope) {
+  return crypto
+    .createHash("sha256")
+    .update(`${prevHash || "genesis"}\n${stableStringify(envelope)}`, "utf-8")
+    .digest("hex");
+}
+
+/** The hash the NEXT record must chain from (last parseable line's `hash`). */
+function latestChainHash(text) {
+  const lines = String(text || "").split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].trim()) continue;
+    try {
+      const rec = JSON.parse(lines[i]);
+      return typeof rec?.hash === "string" ? rec.hash : null;
+    } catch {
+      // half-written tail line — chain from the previous intact record
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Append a hook envelope to the chained log. Best-effort: never throws — a
+ * failure to record must not break the turn that fired the hook.
+ *
+ * @param {object} envelope   a full envelope from buildHookEnvelope
+ * @param {object} [opts]     { filePath, homedir }
+ * @returns {{ok:boolean, event_id?:string, hash?:string, reason?:string}}
+ */
+function appendHookEvent(envelope, { filePath, homedir } = {}) {
+  if (!envelope || typeof envelope !== "object" || !envelope.event_id) {
+    return { ok: false, reason: "invalid envelope (no event_id)" };
+  }
+  const f = _deps.fs;
+  const fp = filePath || hookEventLogPath(homedir);
+  try {
+    const dir = path.dirname(fp);
+    if (!f.existsSync(dir)) f.mkdirSync(dir, { recursive: true });
+    let prevHash = null;
+    if (f.existsSync(fp)) {
+      let rotated = false;
+      try {
+        if (f.statSync(fp).size > MAX_LOG_BYTES) {
+          f.renameSync(fp, `${fp}.1`);
+          rotated = true;
+        }
+      } catch {
+        /* stat/rename best-effort */
+      }
+      if (!rotated) prevHash = latestChainHash(f.readFileSync(fp, "utf-8"));
+    }
+    const hash = computeChainHash(prevHash, envelope);
+    const line = `${JSON.stringify({ envelope, prevHash, hash })}\n`;
+    f.appendFileSync(fp, line, "utf-8");
+    return { ok: true, event_id: envelope.event_id, hash };
+  } catch (e) {
+    return { ok: false, reason: e.message };
+  }
+}
+
+/** Read every recorded record (skips malformed / half-written lines). */
+function readHookEventRecords({ filePath, homedir } = {}) {
+  const f = _deps.fs;
+  const fp = filePath || hookEventLogPath(homedir);
+  if (!f.existsSync(fp)) return [];
+  const out = [];
+  for (const line of f.readFileSync(fp, "utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      /* skip malformed / partial line */
+    }
+  }
+  return out;
+}
+
+/**
+ * Look up the envelope for a delivery id. The LATEST matching record wins (an
+ * event_id can recur across processes; the most recent delivery is what a user
+ * replaying "the last one" means).
+ */
+function findHookEvent(eventId, { filePath, homedir } = {}) {
+  if (!eventId) return null;
+  const records = readHookEventRecords({ filePath, homedir });
+  for (let i = records.length - 1; i >= 0; i--) {
+    if (records[i]?.envelope?.event_id === eventId) return records[i].envelope;
+  }
+  return null;
+}
+
+/** The most recent `limit` envelopes (newest last), for `cc hook events-log`. */
+function listHookEvents({ limit = 20, filePath, homedir } = {}) {
+  const records = readHookEventRecords({ filePath, homedir });
+  const n = Math.max(0, Number(limit) || 0);
+  return records.slice(n ? -n : 0).map((r) => r.envelope);
+}
+
+/**
+ * Recompute the chain and report the first break, if any.
+ * @returns {{ok:boolean, length:number, brokenAt:number, reason?:string}}
+ */
+function verifyHookEventChain({ filePath, homedir } = {}) {
+  const records = readHookEventRecords({ filePath, homedir });
+  let prev = null;
+  for (let i = 0; i < records.length; i++) {
+    const { envelope, prevHash, hash } = records[i] || {};
+    if ((prevHash ?? null) !== prev) {
+      return {
+        ok: false,
+        length: records.length,
+        brokenAt: i,
+        reason: "prevHash does not match the previous record's hash",
+      };
+    }
+    const expect = computeChainHash(prev, envelope);
+    if (expect !== hash) {
+      return {
+        ok: false,
+        length: records.length,
+        brokenAt: i,
+        reason: "record hash does not match its envelope (tampered)",
+      };
+    }
+    prev = hash;
+  }
+  return { ok: true, length: records.length, brokenAt: -1 };
+}
+
+module.exports = {
+  MAX_LOG_BYTES,
+  hookEventLogPath,
+  isHookEventLogEnabled,
+  computeChainHash,
+  latestChainHash,
+  appendHookEvent,
+  readHookEventRecords,
+  findHookEvent,
+  listHookEvents,
+  verifyHookEventChain,
+  _deps,
+};