@abelxiaoxing/cadence 1.8.4 → 2.0.1

package/src/task-store.ts

@@ -0,0 +1,479 @@
+import { spawnSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readSync,
+  realpathSync,
+  renameSync,
+  type Stats,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, hostname } from "node:os";
+import {
+  dirname,
+  isAbsolute,
+  join,
+  parse,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
+import {
+  decodeCheck,
+  decodeTask,
+  MAX_RECORD_BYTES,
+  object,
+  type TaskRecord,
+  validId,
+} from "./task-types.ts";
+import { diagnosticText } from "./verification-diagnostics.ts";
+
+function parseRecord(data: Buffer): unknown {
+  try {
+    return JSON.parse(data.toString("utf8"));
+  } catch {
+    throw new Error("Corrupt JSON state; preserved without reset");
+  }
+}
+function absent(error: unknown): boolean {
+  return object(error) && error.code === "ENOENT";
+}
+/** Reject links in every existing ancestor. Missing observation never creates paths.
+ * The readonly hook inspects each existing directory synchronously, including
+ * the root, before visiting its child. It must not await, mutate or retain state
+ * as authority for a later call/effect. Legacy/default traversal is unchanged.
+ */
+export function safeDirectory(path: string, create?: boolean): boolean;
+export function safeDirectory(
+  path: string,
+  create: false,
+  inspectExisting: (path: string, stat: Stats) => void,
+): boolean;
+export function safeDirectory(
+  path: string,
+  create = false,
+  inspectExisting?: (path: string, stat: Stats) => void,
+): boolean {
+  const full = resolve(path);
+  const root = parse(full).root;
+  if (inspectExisting) {
+    const st = lstatSync(root);
+    if (!st.isDirectory() || st.isSymbolicLink())
+      throw new Error("Unsafe directory");
+    inspectExisting(root, st);
+  }
+  let at = root;
+  for (const part of full.slice(root.length).split(sep).filter(Boolean)) {
+    at = join(at, part);
+    let existing: Stats | undefined;
+    try {
+      const st = lstatSync(at);
+      if (!st.isDirectory()) throw new Error("Unsafe directory");
+      const checked = lstatSync(at);
+      if (
+        checked.isSymbolicLink() ||
+        (inspectExisting && !checked.isDirectory())
+      )
+        throw new Error("Unsafe directory");
+      // Inspect the latest observation, not an earlier stat whose mode/uid
+      // may already have changed. No extra IO or cross-call authority cache.
+      existing = checked;
+    } catch (error) {
+      if (!absent(error)) throw error;
+      if (!create) return false;
+      try {
+        mkdirSync(at, { mode: 0o700 });
+      } catch (mkdirError) {
+        if (!object(mkdirError) || mkdirError.code !== "EEXIST")
+          throw mkdirError;
+      }
+      if (!lstatSync(at).isDirectory() || lstatSync(at).isSymbolicLink())
+        throw new Error("Unsafe directory");
+    }
+    // Outside the ENOENT handler: an inspection refusal is never absence and
+    // must not authorize creation, even if its error happens to carry ENOENT.
+    if (existing) inspectExisting?.(at, existing);
+  }
+  return true;
+}
+export function readBounded(path: string, max: number): Buffer | undefined {
+  if (!safeDirectory(dirname(path))) return undefined;
+  let fd: number;
+  try {
+    const st = lstatSync(path);
+    if (!st.isFile() || st.isSymbolicLink() || st.nlink !== 1 || st.size > max)
+      throw new Error("Unsafe or oversized file");
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  } catch (error) {
+    if (absent(error)) return undefined;
+    throw error;
+  }
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile() || st.nlink !== 1 || st.size > max)
+      throw new Error("Unsafe or oversized file");
+    // Read at most max+1 even if another editor grows the file after stat.
+    const buffer = Buffer.alloc(max + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const n = readSync(fd, buffer, size, buffer.length - size, null);
+      if (!n) break;
+      size += n;
+    }
+    if (size > max) throw new Error("Oversized file");
+    return buffer.subarray(0, size);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Git observations must describe the physical cwd, not inherited alternate index/worktree overrides. */
+export function gitEnvironment(): NodeJS.ProcessEnv {
+  return {
+    ...Object.fromEntries(
+      Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")),
+    ),
+    GIT_OPTIONAL_LOCKS: "0",
+    LC_ALL: "C",
+  };
+}
+export function resolveWorkspace(cwd: string): { root: string; cwd: string } {
+  const actual = realpathSync(cwd);
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: actual,
+    env: gitEnvironment(),
+    encoding: "utf8",
+    timeout: 3000,
+    maxBuffer: 8192,
+    windowsHide: true,
+  });
+  // Remove only Git's record terminator, not valid whitespace in a path.
+  const topLevel = result.stdout?.replace(
+    process.platform === "win32" ? /\r?\n$/ : /\n$/,
+    "",
+  );
+  if (result.status === 0 && topLevel)
+    return { root: realpathSync(topLevel), cwd: actual };
+  if (result.error && !object(result.error))
+    throw new Error("Cannot resolve workspace");
+  if (result.error && object(result.error) && result.error.code !== "ENOENT")
+    throw new Error("Workspace lookup failed");
+  // A missing Git executable or a confirmed non-repository is an honest non-Git workspace.
+  if (!result.error && !result.stderr.includes("not a git repository"))
+    throw new Error("Git workspace lookup refused");
+  return { root: actual, cwd: actual };
+}
+export function defaultStateHome(): string {
+  const candidate =
+    process.platform === "win32"
+      ? process.env.LOCALAPPDATA
+      : process.env.XDG_STATE_HOME;
+  if (candidate && !isAbsolute(candidate))
+    throw new Error("State home must be absolute");
+  return (
+    candidate ??
+    join(
+      homedir(),
+      process.platform === "win32" ? "AppData/Local" : ".local/state",
+    )
+  );
+}
+/** Canonical bytes written by save; identity is optimistic record concurrency, not consent. */
+function recordText(record: TaskRecord): string {
+  return `${JSON.stringify(record, null, 2)}\n`;
+}
+function contentIdentity(text: string | Buffer): string {
+  return createHash("sha256").update(text).digest("hex");
+}
+export function savedRecordIdentity(record: TaskRecord): string {
+  return contentIdentity(recordText(record));
+}
+/** Resolve ambient aliases, including a missing tail, without creating anything. */
+function canonicalAmbientRoot(path: string): string {
+  const full = resolve(path);
+  try {
+    return realpathSync(full);
+  } catch (error) {
+    if (!absent(error)) throw error;
+    // A dangling alias is not a missing ambient directory.
+    try {
+      lstatSync(full);
+      throw new Error("Dangling ambient root");
+    } catch (statError) {
+      if (!absent(statError)) throw statError;
+    }
+    const parent = dirname(full);
+    if (parent === full) throw error;
+    return join(canonicalAmbientRoot(parent), full.slice(parent.length));
+  }
+}
+export interface CheckoutLock {
+  schema: "cadence-assistant-lock/1";
+  token: string;
+  pid: number;
+  host: string;
+  runId: string;
+  root: string;
+}
+export class TaskStore {
+  readonly root: string;
+  readonly tasks: string;
+  readonly privateRoot: string;
+  constructor(root: string, stateHome = defaultStateHome()) {
+    this.root = realpathSync(root);
+    this.tasks = join(this.root, ".cadence", "assistant", "tasks");
+    this.privateRoot = join(
+      canonicalAmbientRoot(stateHome),
+      "cadence-assistant-v1",
+      createHash("sha256").update(this.root).digest("hex"),
+    );
+    const within = relative(this.root, resolve(this.privateRoot));
+    if (
+      !within ||
+      (!within.startsWith(`..${sep}`) && within !== ".." && !isAbsolute(within))
+    )
+      throw new Error("Private state home must be outside the working copy");
+  }
+  get lockPath(): string {
+    return join(this.privateRoot, "checkout.lock");
+  }
+  private inspectPrivate(): void {
+    const namespace = dirname(this.privateRoot);
+    for (const path of [namespace, this.privateRoot]) {
+      if (!safeDirectory(path)) continue;
+      const st = lstatSync(path);
+      if (
+        process.platform !== "win32" &&
+        ((st.mode & 0o077) !== 0 ||
+          (process.getuid && st.uid !== process.getuid()))
+      )
+        throw new Error("Private state permissions refused");
+    }
+  }
+  private inspectPrivateFile(path: string, max: number): void {
+    this.inspectPrivate();
+    if (!safeDirectory(this.privateRoot)) return;
+    try {
+      const st = lstatSync(path);
+      if (
+        !st.isFile() ||
+        st.isSymbolicLink() ||
+        st.nlink !== 1 ||
+        st.size > max ||
+        (process.platform !== "win32" &&
+          ((st.mode & 0o077) !== 0 ||
+            (process.getuid && st.uid !== process.getuid())))
+      )
+        throw new Error("Unsafe private state file");
+    } catch (error) {
+      if (!absent(error)) throw error;
+    }
+  }
+  inspectLock(): CheckoutLock | undefined {
+    this.inspectPrivateFile(this.lockPath, 8192);
+    const data = readBounded(this.lockPath, 8192);
+    if (!data) return undefined;
+    const lock: unknown = parseRecord(data);
+    if (
+      !object(lock) ||
+      lock.schema !== "cadence-assistant-lock/1" ||
+      lock.root !== this.root ||
+      typeof lock.token !== "string" ||
+      !validId(lock.token) ||
+      typeof lock.runId !== "string" ||
+      !validId(lock.runId) ||
+      typeof lock.host !== "string" ||
+      !Number.isInteger(lock.pid) ||
+      Number(lock.pid) < 1
+    )
+      throw new Error("Unknown or corrupt coordination lock");
+    return lock as unknown as CheckoutLock;
+  }
+  acquire(): CheckoutLock {
+    this.inspectPrivate();
+    safeDirectory(this.privateRoot, true);
+    const lock: CheckoutLock = {
+      schema: "cadence-assistant-lock/1",
+      token: randomUUID(),
+      runId: randomUUID(),
+      pid: process.pid,
+      host: hostname(),
+      root: this.root,
+    };
+    let fd: number;
+    try {
+      fd = openSync(this.lockPath, "wx", 0o600);
+    } catch {
+      throw new Error(
+        "Checkout busy or unresolved lock; inspect and explicitly recover only a dead owner",
+      );
+    }
+    try {
+      writeFileSync(fd, JSON.stringify(lock));
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    return lock;
+  }
+  assertOwner(lock: CheckoutLock): void {
+    if (JSON.stringify(this.inspectLock()) !== JSON.stringify(lock))
+      throw new Error("Coordination lock changed");
+  }
+  release(lock: CheckoutLock): void {
+    if (lock.pid !== process.pid || lock.host !== hostname())
+      throw new Error("Only the owning process may release a lock");
+    this.assertOwner(lock);
+    unlinkSync(this.lockPath);
+  }
+  recover(expected: CheckoutLock, acknowledgeEscapedProcesses: boolean): void {
+    if (!acknowledgeEscapedProcesses || expected.host !== hostname())
+      throw new Error("Recovery requires informed local-owner confirmation");
+    this.assertOwner(expected);
+    try {
+      process.kill(expected.pid, 0);
+    } catch (error) {
+      if (!object(error) || error.code !== "ESRCH")
+        throw new Error("Owner status unknown");
+      this.assertOwner(expected);
+      unlinkSync(this.lockPath);
+      return;
+    }
+    throw new Error("Owner is live; stop it first");
+  }
+  load(id: string): TaskRecord | undefined {
+    return this.loadSnapshot(id)?.record;
+  }
+  loadSnapshot(
+    id: string,
+  ): { record: TaskRecord; identity: string } | undefined {
+    if (!validId(id)) throw new Error("Invalid task id");
+    const directory = join(this.tasks, id);
+    if (
+      safeDirectory(directory) &&
+      readdirSync(directory).some((name) => name !== "task.json")
+    )
+      throw new Error(
+        "Unknown task directory content; preserved without reset",
+      );
+    const data = readBounded(
+      join(this.tasks, id, "task.json"),
+      MAX_RECORD_BYTES,
+    );
+    if (!data) return undefined;
+    const record = decodeTask(parseRecord(data));
+    if (record.id !== id) throw new Error("Task identity mismatch");
+    return { record, identity: contentIdentity(data) };
+  }
+  list(): TaskRecord[] {
+    if (!safeDirectory(this.tasks)) return [];
+    const entries = readdirSync(this.tasks);
+    if (entries.length > 1000) throw new Error("Task listing limit exceeded");
+    return entries.map((id) => {
+      const task = this.load(id);
+      if (!task) throw new Error("Unknown task directory");
+      return task;
+    });
+  }
+  save(
+    record: TaskRecord,
+    expectedRevision: number,
+    held?: CheckoutLock,
+    expectedIdentity?: string,
+  ): TaskRecord {
+    const next = decodeTask(record);
+    if (next.revision !== expectedRevision + 1)
+      throw new Error("Revision conflict");
+    const text = recordText(next);
+    if (Buffer.byteLength(text) > MAX_RECORD_BYTES)
+      throw new Error("Task record limit");
+    const lock = held ?? this.acquire();
+    if (lock.pid !== process.pid || lock.host !== hostname())
+      throw new Error("Not the lock owner");
+    try {
+      this.assertOwner(lock);
+      const current = this.loadSnapshot(next.id);
+      if ((current?.record.revision ?? 0) !== expectedRevision)
+        throw new Error("Revision conflict");
+      if (current?.identity !== expectedIdentity)
+        throw new Error("Task content changed; reopen it");
+      const dir = join(this.tasks, next.id);
+      safeDirectory(dir, true);
+      // Unknown sibling state is not overwritten or cleaned.
+      if (!current && readdirSync(dir).length)
+        throw new Error("Unknown task directory");
+      const temporary = join(dir, `task.${randomUUID()}.tmp`);
+      const fd = openSync(temporary, "wx", 0o600);
+      try {
+        writeFileSync(fd, text);
+        fsyncSync(fd);
+      } finally {
+        closeSync(fd);
+      }
+      this.assertOwner(lock);
+      // Check again after preparing the replacement. External editors do not share our lock;
+      // this detects observed conflicts, not an atomic filesystem CAS against hostile writers.
+      const latest = readBounded(join(dir, "task.json"), MAX_RECORD_BYTES);
+      if ((latest ? contentIdentity(latest) : undefined) !== expectedIdentity)
+        throw new Error(
+          "Task content changed; replacement preserved without overwrite",
+        );
+      renameSync(temporary, join(dir, "task.json"));
+      return next;
+    } finally {
+      if (!held) this.release(lock);
+    }
+  }
+  checks() {
+    const data = readBounded(
+      join(this.root, ".cadence", "assistant", "config.json"),
+      32768,
+    );
+    if (!data) return [];
+    const value: unknown = parseRecord(data);
+    if (
+      !object(value) ||
+      value.schema !== TASK_CONFIG_SCHEMA ||
+      !Array.isArray(value.checks) ||
+      value.checks.length > 32 ||
+      Object.keys(value).some((key) => !["schema", "checks"].includes(key))
+    )
+      throw new Error("Unknown check configuration");
+    const checks = value.checks.map(decodeCheck);
+    if (
+      new Set(checks.map((check) => check.name)).size !== checks.length ||
+      checks.some((check) => check.name === "Manual command")
+    )
+      throw new Error("Duplicate or reserved check name");
+    return checks;
+  }
+  readLog(name: string): string {
+    if (!/^[a-f0-9-]{36}\.log$/.test(name))
+      throw new Error("Invalid diagnostic name");
+    this.inspectPrivateFile(join(this.privateRoot, name), 65536);
+    const data = readBounded(join(this.privateRoot, name), 65536);
+    return data
+      ? diagnosticText(data.toString("utf8"), 65536)
+      : "Private diagnostic unavailable";
+  }
+  writeLog(lock: CheckoutLock, output: string): string {
+    if (lock.pid !== process.pid || lock.host !== hostname())
+      throw new Error("Not the lock owner");
+    this.assertOwner(lock);
+    const name = `${randomUUID()}.log`;
+    writeFileSync(join(this.privateRoot, name), diagnosticText(output, 65536), {
+      flag: "wx",
+      mode: 0o600,
+    });
+    return name;
+  }
+}
+export const TASK_CONFIG_SCHEMA = "cadence-assistant-checks/1";

package/src/task-types.ts

@@ -0,0 +1,184 @@
+/** Plain workflow context, not executable approvals or certified evidence. */
+export const TASK_SCHEMA = "cadence-workflow-assistant/1";
+export const MAX_RECORD_BYTES = 128 * 1024;
+export type TaskKind = "code" | "research" | "diagnosis";
+export type TaskPhase =
+  | "planning"
+  | "running"
+  | "review"
+  | "interrupted"
+  | "failed"
+  | "done";
+export interface CheckDefinition {
+  name: string;
+  command: string;
+  timeoutMs: number;
+}
+export interface CheckRecord extends CheckDefinition {
+  cwd: string;
+  exitCode: number | null;
+  durationMs: number;
+  status: "passed" | "failed" | "canceled" | "stale";
+  fingerprint: string;
+  log?: string;
+}
+export interface TaskRecord {
+  schema: typeof TASK_SCHEMA;
+  id: string;
+  revision: number;
+  kind: TaskKind;
+  goal: string;
+  plan: string;
+  cwd: string;
+  phase: TaskPhase;
+  result: string;
+  baseline: string;
+  checks: CheckRecord[];
+  review?: {
+    fingerprint: string;
+    outcome: "reviewed" | "reviewed-with-issues";
+  };
+  activity: { at: string; text: string }[];
+}
+export interface ChangeView {
+  fingerprint: string;
+  text: string;
+  complete: boolean;
+  git: boolean;
+}
+export interface RunResult {
+  outcome: "completed" | "failed" | "canceled" | "timeout" | "unknown";
+  closed: boolean;
+  exitCode: number | null;
+  signal: string | null;
+  durationMs: number;
+  text: string;
+  output: string;
+  truncated: boolean;
+}
+export function object(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function boundedString(value: unknown, max: number): value is string {
+  return (
+    typeof value === "string" &&
+    Buffer.byteLength(value) <= max &&
+    !value.includes("\0")
+  );
+}
+export function validId(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(
+    value,
+  );
+}
+export function decodeCheck(value: unknown): CheckDefinition {
+  if (
+    !object(value) ||
+    !boundedString(value.name, 128) ||
+    !value.name.trim() ||
+    !boundedString(value.command, 4096) ||
+    !value.command.trim() ||
+    !Number.isInteger(value.timeoutMs) ||
+    Number(value.timeoutMs) < 100 ||
+    Number(value.timeoutMs) > 1_200_000
+  )
+    throw new Error("Invalid check definition");
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: reject invisible terminal controls in executable confirmations
+  const controls = /[\x00-\x08\x0b-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u;
+  if (
+    controls.test(value.command) ||
+    controls.test(value.name) ||
+    /[\n\t]/u.test(value.name)
+  )
+    throw new Error(
+      "Check commands/names must be visibly representable in the terminal",
+    );
+  return {
+    name: value.name,
+    command: value.command,
+    timeoutMs: Number(value.timeoutMs),
+  };
+}
+export function decodeTask(value: unknown): TaskRecord {
+  if (
+    !object(value) ||
+    value.schema !== TASK_SCHEMA ||
+    typeof value.id !== "string" ||
+    !validId(value.id) ||
+    !Number.isSafeInteger(value.revision) ||
+    Number(value.revision) < 1 ||
+    typeof value.kind !== "string" ||
+    !["code", "research", "diagnosis"].includes(value.kind) ||
+    typeof value.phase !== "string" ||
+    ![
+      "planning",
+      "running",
+      "review",
+      "interrupted",
+      "failed",
+      "done",
+    ].includes(value.phase) ||
+    !boundedString(value.goal, 8192) ||
+    !value.goal.trim() ||
+    !boundedString(value.plan, 32768) ||
+    !boundedString(value.cwd, 4096) ||
+    !boundedString(value.result, 16384) ||
+    !boundedString(value.baseline, 16384) ||
+    !Array.isArray(value.checks) ||
+    value.checks.length > 32 ||
+    !Array.isArray(value.activity) ||
+    value.activity.length > 64
+  )
+    throw new Error("Unknown or corrupt task record");
+  for (const check of value.checks) {
+    decodeCheck(check);
+    if (
+      !object(check) ||
+      !boundedString(check.cwd, 4096) ||
+      !(check.exitCode === null || Number.isInteger(check.exitCode)) ||
+      typeof check.durationMs !== "number" ||
+      !Number.isFinite(check.durationMs) ||
+      check.durationMs < 0 ||
+      typeof check.status !== "string" ||
+      !["passed", "failed", "canceled", "stale"].includes(check.status) ||
+      !boundedString(check.fingerprint, 128) ||
+      (check.log !== undefined &&
+        (typeof check.log !== "string" || !/^[a-f0-9-]+\.log$/.test(check.log)))
+    )
+      throw new Error("Corrupt check record");
+  }
+  for (const entry of value.activity) {
+    if (
+      !object(entry) ||
+      !boundedString(entry.at, 64) ||
+      !boundedString(entry.text, 512)
+    )
+      throw new Error("Corrupt activity");
+  }
+  if (
+    value.review !== undefined &&
+    (!object(value.review) ||
+      !boundedString(value.review.fingerprint, 128) ||
+      typeof value.review.outcome !== "string" ||
+      !["reviewed", "reviewed-with-issues"].includes(value.review.outcome))
+  )
+    throw new Error("Corrupt review");
+  const allowed = new Set([
+    "schema",
+    "id",
+    "revision",
+    "kind",
+    "goal",
+    "plan",
+    "cwd",
+    "phase",
+    "result",
+    "baseline",
+    "checks",
+    "review",
+    "activity",
+  ]);
+  if (Object.keys(value).some((key) => !allowed.has(key)))
+    throw new Error("Unknown task fields");
+  return structuredClone(value) as unknown as TaskRecord;
+}