chainlesschain 0.162.30 → 0.162.32

package/src/lib/file-checkpoint.js

@@ -0,0 +1,300 @@
+/**
+ * file-checkpoint — manual file-state snapshot / rewind for `cc checkpoint`.
+ *
+ * Claude-Code "rewind" parity at the CLI level: snapshot a set of files (or
+ * directories) before a risky agentic run, then restore them if it goes wrong.
+ * This is the standalone store + ops; auto-snapshotting inside the agent
+ * tool-loop is a separate follow-up (it lives in the churn-prone agent-core).
+ *
+ * On-disk layout (under <home>/checkpoints, overridable via opts.root for tests):
+ *   <root>/<id>.json        manifest { id, label, createdAt, cwd, files:[...] }
+ *   <root>/<id>/<sha256>    raw bytes of each distinct file (content-addressed,
+ *                           so duplicate contents are stored once)
+ *
+ * Distinct from `cc workflow checkpoint` (which snapshots workflow EXECUTION
+ * state in the DB, not files).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { getHomeDir } from "./paths.js";
+
+/** Directories never walked into when a checkpoint path is a directory. */
+export const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".chainlesschain",
+  ".next",
+  ".cache",
+  "coverage",
+]);
+
+/** Safety cap so `checkpoint create <huge-dir>` can't snapshot the universe. */
+export const DEFAULT_MAX_FILES = 2000;
+
+function defaultRoot() {
+  return path.join(getHomeDir(), "checkpoints");
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function sha256(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+function newId() {
+  // Date.now/random are fine here (plain CLI lib, not a resumable workflow).
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `cp-${Date.now()}-${rand}`;
+}
+
+/**
+ * Recursively collect regular files under an absolute path, honoring SKIP_DIRS
+ * and a running maxFiles budget. Symlinks are not followed.
+ */
+function collectFiles(abs, { maxFiles, acc }) {
+  let stat;
+  try {
+    stat = fs.lstatSync(abs);
+  } catch {
+    return;
+  }
+  if (stat.isSymbolicLink()) return;
+  if (stat.isFile()) {
+    if (acc.length >= maxFiles) {
+      throw new Error(
+        `checkpoint exceeds ${maxFiles} files — narrow the paths or raise maxFiles`,
+      );
+    }
+    acc.push(abs);
+    return;
+  }
+  if (stat.isDirectory()) {
+    if (SKIP_DIRS.has(path.basename(abs))) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(abs);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      collectFiles(path.join(abs, name), { maxFiles, acc });
+    }
+  }
+}
+
+/**
+ * Create a checkpoint snapshotting the given paths (files and/or dirs).
+ *
+ * @param {string[]} paths
+ * @param {object} [opts] { cwd, label, root, maxFiles }
+ * @returns {{ id, label, createdAt, cwd, fileCount, files:Array }}
+ */
+export function createCheckpoint(paths, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const root = opts.root || defaultRoot();
+  const maxFiles = Number.isFinite(opts.maxFiles)
+    ? opts.maxFiles
+    : DEFAULT_MAX_FILES;
+  const list = Array.isArray(paths) ? paths : [paths];
+  if (list.filter(Boolean).length === 0) {
+    throw new Error("createCheckpoint requires at least one path");
+  }
+
+  const absFiles = [];
+  for (const p of list) {
+    if (!p) continue;
+    const abs = path.resolve(cwd, p);
+    if (!fs.existsSync(abs)) {
+      throw new Error(`no such path: ${p}`);
+    }
+    collectFiles(abs, { maxFiles, acc: absFiles });
+  }
+  // De-dupe (overlapping paths) while preserving order.
+  const uniqueAbs = [...new Set(absFiles)];
+
+  const id = opts.id || newId();
+  const blobDir = path.join(root, id);
+  ensureDir(blobDir);
+
+  const files = [];
+  for (const abs of uniqueAbs) {
+    const buf = fs.readFileSync(abs);
+    const hash = sha256(buf);
+    const blobPath = path.join(blobDir, hash);
+    if (!fs.existsSync(blobPath)) fs.writeFileSync(blobPath, buf);
+    files.push({
+      rel: path.relative(cwd, abs) || path.basename(abs),
+      abs,
+      bytes: buf.length,
+      sha256: hash,
+    });
+  }
+
+  const manifest = {
+    id,
+    label: opts.label || "",
+    createdAt: new Date().toISOString(),
+    cwd,
+    fileCount: files.length,
+    files,
+  };
+  ensureDir(root);
+  fs.writeFileSync(
+    path.join(root, `${id}.json`),
+    JSON.stringify(manifest, null, 2),
+    "utf-8",
+  );
+  return manifest;
+}
+
+/** Load a checkpoint manifest by id, or null. */
+export function getCheckpoint(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const file = path.join(root, `${id}.json`);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** List all checkpoint manifests, newest first. */
+export function listCheckpoints(opts = {}) {
+  const root = opts.root || defaultRoot();
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(root)) {
+    if (!name.endsWith(".json")) continue;
+    const m = getCheckpoint(name.slice(0, -5), { root });
+    if (m) {
+      out.push({
+        id: m.id,
+        label: m.label,
+        createdAt: m.createdAt,
+        cwd: m.cwd,
+        fileCount: m.fileCount,
+      });
+    }
+  }
+  return out.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+}
+
+/**
+ * Compare the current on-disk state against a checkpoint.
+ * @returns {{ id, modified:[], unchanged:[], deleted:[] }}
+ *   modified = content differs; deleted = file is gone now.
+ */
+export function diffCheckpoint(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const m = getCheckpoint(id, { root });
+  if (!m) throw new Error(`no such checkpoint: ${id}`);
+  const modified = [];
+  const unchanged = [];
+  const deleted = [];
+  for (const f of m.files) {
+    if (!fs.existsSync(f.abs)) {
+      deleted.push(f.rel);
+      continue;
+    }
+    const cur = sha256(fs.readFileSync(f.abs));
+    if (cur === f.sha256) unchanged.push(f.rel);
+    else modified.push(f.rel);
+  }
+  return { id, modified, unchanged, deleted };
+}
+
+/**
+ * Restore files from a checkpoint to their original paths. By default a safety
+ * checkpoint of the CURRENT contents is taken first, so a restore is itself
+ * reversible. `dryRun` reports what would change without writing.
+ *
+ * @param {string} id
+ * @param {object} [opts] { root, dryRun, skipSafety, cwd }
+ * @returns {{ id, restored:[], unchanged:[], missingBlob:[], safetyId:string|null }}
+ */
+export function restoreCheckpoint(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const m = getCheckpoint(id, { root });
+  if (!m) throw new Error(`no such checkpoint: ${id}`);
+
+  const restored = [];
+  const unchanged = [];
+  const missingBlob = [];
+  const toWrite = [];
+
+  for (const f of m.files) {
+    const blobPath = path.join(root, id, f.sha256);
+    if (!fs.existsSync(blobPath)) {
+      missingBlob.push(f.rel);
+      continue;
+    }
+    const blob = fs.readFileSync(blobPath);
+    const cur = fs.existsSync(f.abs) ? fs.readFileSync(f.abs) : null;
+    if (cur && sha256(cur) === f.sha256) {
+      unchanged.push(f.rel);
+      continue;
+    }
+    toWrite.push({ abs: f.abs, rel: f.rel, blob });
+  }
+
+  if (opts.dryRun) {
+    return {
+      id,
+      restored: toWrite.map((w) => w.rel),
+      unchanged,
+      missingBlob,
+      safetyId: null,
+      dryRun: true,
+    };
+  }
+
+  // Snapshot the current state of the files we're about to overwrite, so the
+  // restore can itself be rewound. Only the files that actually change and
+  // currently exist need protecting.
+  let safetyId = null;
+  if (!opts.skipSafety) {
+    const existing = toWrite
+      .filter((w) => fs.existsSync(w.abs))
+      .map((w) => w.abs);
+    if (existing.length > 0) {
+      const safety = createCheckpoint(existing, {
+        root,
+        cwd: m.cwd,
+        label: `auto-before-restore-${id}`,
+      });
+      safetyId = safety.id;
+    }
+  }
+
+  for (const w of toWrite) {
+    ensureDir(path.dirname(w.abs));
+    fs.writeFileSync(w.abs, w.blob);
+    restored.push(w.rel);
+  }
+
+  return { id, restored, unchanged, missingBlob, safetyId };
+}
+
+/** Delete a checkpoint (manifest + blobs). Returns true if it existed. */
+export function deleteCheckpoint(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const file = path.join(root, `${id}.json`);
+  const blobDir = path.join(root, id);
+  let existed = false;
+  if (fs.existsSync(file)) {
+    fs.rmSync(file);
+    existed = true;
+  }
+  if (fs.existsSync(blobDir)) {
+    fs.rmSync(blobDir, { recursive: true, force: true });
+    existed = true;
+  }
+  return existed;
+}

package/src/lib/goal-context.js

@@ -0,0 +1,87 @@
+/**
+ * goal-context — turn-scoped injection of the active goal into the agent loop.
+ *
+ * When a goal is bound to a run, a compact reminder of its objective + open key
+ * results is supplemented into each LLM call (via agent-core's `prepareCall`
+ * seam), so every turn is measured against the goal without polluting the
+ * persistent message history.
+ *
+ * IMPORTANT: this composes WITH the existing `defaultPrepareCall` (turn-context)
+ * rather than replacing it — both suffixes are concatenated. Keep the produced
+ * text terse: it is re-sent on every iteration and is billed each time.
+ */
+
+/** Hard cap on the open key results we list, to bound per-turn token cost. */
+const MAX_KEY_RESULTS = 8;
+
+/**
+ * Build the compact system-prompt supplement for a goal, or null when the goal
+ * is missing / not active.
+ * @param {object|null} goal
+ * @returns {string|null}
+ */
+export function buildGoalContext(goal) {
+  if (!goal || goal.status !== "active") return null;
+  const objective = String(goal.objective || "").trim();
+  if (!objective) return null;
+
+  const pct = Number.isFinite(goal.progress) ? goal.progress : 0;
+  const lines = [`Active goal (${pct}% complete): ${objective}`];
+
+  const open = (goal.keyResults || []).filter((k) => k && !k.done);
+  for (const kr of open.slice(0, MAX_KEY_RESULTS)) {
+    const target =
+      kr.target != null ? ` [${kr.current ?? 0}/${kr.target}]` : "";
+    lines.push(`- key result: ${kr.text}${target}`);
+  }
+  if (open.length > MAX_KEY_RESULTS) {
+    lines.push(`- (+${open.length - MAX_KEY_RESULTS} more key results)`);
+  }
+
+  lines.push(
+    "Each turn, prefer actions that advance these key results; if you must diverge, briefly say why.",
+  );
+  return lines.join("\n");
+}
+
+/**
+ * A `prepareCall`-shaped function bound to a goal. Defensive: never throws
+ * (agent-core swallows prepareCall errors, but we avoid relying on that).
+ * @param {object|null} goal
+ * @returns {(ctx:object) => ({systemSuffix:string}|null)}
+ */
+export function goalPrepareCall(goal) {
+  return () => {
+    try {
+      const suffix = buildGoalContext(goal);
+      return suffix ? { systemSuffix: suffix } : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+/**
+ * Compose several `prepareCall` functions into one. Each is invoked per turn
+ * and their non-empty `systemSuffix` strings are concatenated. A failing
+ * member is skipped, never fatal.
+ * @param {Array<Function|null|undefined>} fns
+ * @returns {(ctx:object) => Promise<{systemSuffix:string}|null>}
+ */
+export function composePrepareCall(fns) {
+  const list = (fns || []).filter((f) => typeof f === "function");
+  return async (ctx) => {
+    const parts = [];
+    for (const fn of list) {
+      try {
+        const r = await fn(ctx);
+        if (r && typeof r.systemSuffix === "string" && r.systemSuffix.trim()) {
+          parts.push(r.systemSuffix);
+        }
+      } catch {
+        /* a failing member must not break the turn */
+      }
+    }
+    return parts.length ? { systemSuffix: parts.join("\n\n") } : null;
+  };
+}

package/src/lib/goal-store.js

@@ -0,0 +1,308 @@
+/**
+ * goal-store — cross-session persistent goals / OKRs for `cc goal`.
+ *
+ * Unlike a session (short-lived context) or a checkpoint (file state), a goal
+ * is a long-lived objective the agent should advance toward across many
+ * sessions. This is the standalone store + ops; wiring the goal into the agent
+ * loop (so each turn is measured against it) lives in goal-context.js.
+ *
+ * On-disk layout (under <home>/goals, overridable via opts.root for tests):
+ *   <root>/<id>.json        one goal per file
+ *
+ * Distinct from:
+ *   - cc session   (short-term conversation context)
+ *   - cc memory    (durable facts, not objectives)
+ *   - cc planmode  (a single run's plan, not a cross-session objective)
+ *   - cc workflow  (execution orchestration, not intent)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getHomeDir } from "./paths.js";
+
+/** Valid goal lifecycle states. `active` goals are the ones injected. */
+export const GOAL_STATUS = Object.freeze({
+  ACTIVE: "active",
+  PAUSED: "paused",
+  DONE: "done",
+  ABANDONED: "abandoned",
+});
+
+const STATUS_VALUES = new Set(Object.values(GOAL_STATUS));
+
+function defaultRoot() {
+  return path.join(getHomeDir(), "goals");
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function newId(prefix) {
+  // Date.now/random are fine here (plain CLI lib, not a resumable workflow).
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${prefix}-${Date.now()}-${rand}`;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function goalFile(root, id) {
+  return path.join(root, `${id}.json`);
+}
+
+/** Clamp a value to a 0–100 integer percentage, or null when not a number. */
+function clampPct(v) {
+  if (v == null || v === "") return null;
+  const n = Math.round(Number(v));
+  if (!Number.isFinite(n)) return null;
+  return Math.max(0, Math.min(100, n));
+}
+
+/**
+ * Derive a 0–100 progress from completed key results. Returns null when there
+ * are no key results (caller may keep a manually-set progress instead).
+ */
+function derivedProgress(keyResults) {
+  if (!Array.isArray(keyResults) || keyResults.length === 0) return null;
+  const done = keyResults.filter((k) => k.done).length;
+  return Math.round((done / keyResults.length) * 100);
+}
+
+/**
+ * Create a goal.
+ * @param {object} input { objective, title, keyResults?: string[]|object[] }
+ * @param {object} [opts] { root }
+ * @returns {object} the persisted goal
+ */
+export function createGoal(input = {}, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const objective = String(input.objective || "").trim();
+  if (!objective) {
+    throw new Error("createGoal requires an objective");
+  }
+  const id = input.id || newId("goal");
+  const keyResults = (input.keyResults || []).map((kr) => normalizeKr(kr));
+  const goal = {
+    id,
+    title: String(input.title || objective).trim(),
+    objective,
+    keyResults,
+    status: GOAL_STATUS.ACTIVE,
+    progress: derivedProgress(keyResults) ?? 0,
+    linkedSessions: [],
+    notes: [],
+    drift: { lastProgressAt: null, flags: [] },
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  };
+  ensureDir(root);
+  fs.writeFileSync(goalFile(root, id), JSON.stringify(goal, null, 2), "utf-8");
+  return goal;
+}
+
+function normalizeKr(kr) {
+  if (typeof kr === "string") {
+    return {
+      id: newId("kr"),
+      text: kr.trim(),
+      target: null,
+      current: 0,
+      done: false,
+    };
+  }
+  return {
+    id: kr.id || newId("kr"),
+    text: String(kr.text || "").trim(),
+    target: kr.target == null ? null : Number(kr.target),
+    current: Number(kr.current) || 0,
+    done: !!kr.done,
+  };
+}
+
+/** Load a goal by id, or null. */
+export function getGoal(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const file = goalFile(root, id);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function saveGoal(goal, opts = {}) {
+  const root = opts.root || defaultRoot();
+  ensureDir(root);
+  goal.updatedAt = nowIso();
+  fs.writeFileSync(
+    goalFile(root, goal.id),
+    JSON.stringify(goal, null, 2),
+    "utf-8",
+  );
+  return goal;
+}
+
+/** List goals, newest first. Optionally filter by status. */
+export function listGoals(opts = {}) {
+  const root = opts.root || defaultRoot();
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(root)) {
+    if (!name.endsWith(".json")) continue;
+    const g = getGoal(name.slice(0, -5), { root });
+    if (!g) continue;
+    if (opts.status && g.status !== opts.status) continue;
+    out.push(g);
+  }
+  return out.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+}
+
+/** Mutate a goal via `fn(goal)`; throws if not found. */
+function mutate(id, fn, opts = {}) {
+  const goal = getGoal(id, opts);
+  if (!goal) throw new Error(`no such goal: ${id}`);
+  fn(goal);
+  return saveGoal(goal, opts);
+}
+
+/** Add a key result to a goal. */
+export function addKeyResult(id, text, krOpts = {}, opts = {}) {
+  return mutate(
+    id,
+    (g) => {
+      g.keyResults.push(normalizeKr({ text, target: krOpts.target }));
+      const dp = derivedProgress(g.keyResults);
+      if (dp != null) g.progress = dp;
+    },
+    opts,
+  );
+}
+
+/** Update a key result (current value and/or done flag). */
+export function setKeyResult(id, krId, patch = {}, opts = {}) {
+  return mutate(
+    id,
+    (g) => {
+      const kr = g.keyResults.find((k) => k.id === krId);
+      if (!kr) throw new Error(`no such key result: ${krId}`);
+      if (patch.current != null) kr.current = Number(patch.current);
+      if (patch.done != null) kr.done = !!patch.done;
+      if (
+        kr.target != null &&
+        patch.current != null &&
+        Number(patch.current) >= kr.target
+      ) {
+        kr.done = true;
+      }
+      const dp = derivedProgress(g.keyResults);
+      if (dp != null) g.progress = dp;
+      g.drift.lastProgressAt = nowIso();
+    },
+    opts,
+  );
+}
+
+/**
+ * Record progress: set an explicit percentage and/or append a note.
+ * @param {object} input { pct?, note?, by? }
+ */
+export function recordProgress(id, input = {}, opts = {}) {
+  return mutate(
+    id,
+    (g) => {
+      const pct = clampPct(input.pct);
+      if (pct != null) g.progress = pct;
+      if (input.note) {
+        g.notes.push({
+          at: nowIso(),
+          text: String(input.note),
+          by: input.by === "agent" ? "agent" : "user",
+        });
+      }
+      g.drift.lastProgressAt = nowIso();
+    },
+    opts,
+  );
+}
+
+/** Attach a session id to a goal (idempotent). */
+export function linkSession(id, sessionId, opts = {}) {
+  if (!sessionId) throw new Error("linkSession requires a sessionId");
+  return mutate(
+    id,
+    (g) => {
+      if (!g.linkedSessions.includes(sessionId)) {
+        g.linkedSessions.push(sessionId);
+      }
+    },
+    opts,
+  );
+}
+
+/** Detach a session id from a goal. */
+export function unlinkSession(id, sessionId, opts = {}) {
+  return mutate(
+    id,
+    (g) => {
+      g.linkedSessions = g.linkedSessions.filter((s) => s !== sessionId);
+    },
+    opts,
+  );
+}
+
+/** Set a goal's status (active/paused/done/abandoned). */
+export function setStatus(id, status, opts = {}) {
+  if (!STATUS_VALUES.has(status)) {
+    throw new Error(
+      `invalid status "${status}" — expected one of: ${[...STATUS_VALUES].join(", ")}`,
+    );
+  }
+  return mutate(
+    id,
+    (g) => {
+      g.status = status;
+      if (status === GOAL_STATUS.DONE && g.progress < 100) g.progress = 100;
+    },
+    opts,
+  );
+}
+
+/** Delete a goal. Returns true if it existed. */
+export function deleteGoal(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const file = goalFile(root, id);
+  if (!fs.existsSync(file)) return false;
+  fs.rmSync(file);
+  return true;
+}
+
+/**
+ * Resolve the goal that should be bound to the current run, in priority order:
+ *   1. explicit id (--goal <id>)
+ *   2. an active goal linked to the current session
+ *   3. when exactly one active goal exists, that one
+ *   4. null
+ *
+ * Only `active` goals are ever auto-resolved (steps 2–3); an explicit id is
+ * honored regardless of status so a user can re-inspect a paused goal.
+ *
+ * @param {object} [sel] { explicitId, sessionId }
+ * @param {object} [opts] { root }
+ */
+export function resolveActiveGoal(sel = {}, opts = {}) {
+  if (sel.explicitId) {
+    return getGoal(sel.explicitId, opts);
+  }
+  const active = listGoals({ ...opts, status: GOAL_STATUS.ACTIVE });
+  if (active.length === 0) return null;
+  if (sel.sessionId) {
+    const linked = active.find((g) => g.linkedSessions.includes(sel.sessionId));
+    if (linked) return linked;
+  }
+  if (active.length === 1) return active[0];
+  // Ambiguous (multiple active, none linked) — caller must pick explicitly.
+  return null;
+}