taskchef 7.29.0 → 8.1.0

package/src/cli.js

@@ -7,6 +7,7 @@ import { resolveWorkspacePath } from "./workspace-path.js";
 
 import {
   addProject,
+  createWorkspaceBackup,
   buildCopilotBrief,
   buildTaskSummary,
   doctorWorkspace,
@@ -14,12 +15,19 @@ import {
   importProjects,
   initializeWorkspace,
   listProjects,
+  listWorkspaceBackups,
+  pruneWorkspaceBackups,
+  readProjectIndex,
+  readWorkspaceMaintenance,
   listTasks,
   migrateTaskLog,
   prepareDispatch,
   recordTask,
   removeProject,
+  restoreWorkspaceBackup,
   requireSafeId,
+  updateProject,
+  verifyWorkspaceBackup,
 } from "./workspace.js";
 
 const BLANK_TABLE_CELL = Symbol("blank table cell");
@@ -111,6 +119,30 @@ function print(value, args, human) {
   process.stdout.write(`${human ? human(value) : JSON.stringify(value, null, 2)}\n`);
 }
 
+async function mutationOptions(args) {
+  const confirmedPath = option(args, "--confirm-removed", null);
+  let confirmRemoved;
+  if (confirmedPath !== null) {
+    confirmRemoved = JSON.parse(await readFile(path.resolve(confirmedPath), "utf8"));
+  }
+  const numberOption = (name) => {
+    const value = option(args, name, null);
+    if (value === null) return undefined;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 0) throw new Error(`${name} must be a non-negative integer`);
+    return parsed;
+  };
+  return {
+    dryRun: args.includes("--dry-run"),
+    expectedConfigHash: option(args, "--expect-config-hash", undefined),
+    expectedProjectCount: numberOption("--expect-project-count"),
+    expectedAfterCount: numberOption("--expect-after-count"),
+    confirmPlan: option(args, "--confirm-plan", undefined),
+    confirmRemoved,
+    confirmCountCollapse: option(args, "--confirm-count-collapse", undefined),
+  };
+}
+
 function table(headers, rows) {
   const display = (value) => {
     if (value === BLANK_TABLE_CELL) return "";
@@ -300,7 +332,7 @@ async function projectAdd(args) {
   if (!args[2] || args[2].startsWith("--")) throw new Error("project add requires a path");
   validateCommandArgs(args, 3, {
     values: ["--workspace", "--name", "--description", "--github-repo"],
-    switches: ["--json", "--no-github"],
+    switches: ["--json", "--no-github", "--dry-run"],
     repeatable: ["--github-repo"],
   });
   if (args.includes("--no-github") && args.includes("--github-repo")) {
@@ -313,8 +345,13 @@ async function projectAdd(args) {
   if (description !== null) input.description = description;
   if (args.includes("--no-github")) input.githubRepos = [];
   else if (args.includes("--github-repo")) input.githubRepos = options(args, "--github-repo");
-  const project = await addProject(workspaceRoot(args), input);
-  print(project, args, (value) => `Added ${value.name}: ${value.path}`);
+  const result = await addProject(workspaceRoot(args), input, {
+    dryRun: args.includes("--dry-run"),
+  });
+  print(result, args, (value) => {
+    const project = value.project ?? value;
+    return `${args.includes("--dry-run") ? "Would add" : "Added"} ${project.name}: ${project.path}`;
+  });
   return 0;
 }
 
@@ -322,8 +359,11 @@ async function projectImport(args) {
   const hasSource = Boolean(args[2] && !args[2].startsWith("--"));
   const source = hasSource ? args[2] : "-";
   validateCommandArgs(args, hasSource ? 3 : 2, {
-    values: ["--workspace"],
-    switches: ["--json", "--replace"],
+    values: [
+      "--workspace", "--expect-config-hash", "--expect-project-count", "--expect-after-count",
+      "--confirm-plan", "--confirm-removed", "--confirm-count-collapse",
+    ],
+    switches: ["--json", "--replace", "--dry-run"],
   });
   const content = source === "-"
     ? await readStdin()
@@ -331,6 +371,7 @@ async function projectImport(args) {
   if (content.trim().length === 0) throw new Error("project import input is empty");
   const result = await importProjects(workspaceRoot(args), JSON.parse(content), {
     replace: args.includes("--replace"),
+    ...(await mutationOptions(args)),
   });
   print(result, args, (value) =>
     `Imported ${value.importedCount} project(s); ${value.projectCount} configured (${value.mode}).`);
@@ -338,9 +379,14 @@ async function projectImport(args) {
 }
 
 async function projectList(args) {
-  validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
-  const projects = await listProjects(workspaceRoot(args));
-  print({ projectCount: projects.length, projects }, args, (value) => table(
+  validateCommandArgs(args, 2, {
+    values: ["--workspace"],
+    switches: ["--json", "--allow-missing-paths"],
+  });
+  const result = await readProjectIndex(workspaceRoot(args), {
+    checkPaths: !args.includes("--allow-missing-paths"),
+  });
+  print(result, args, (value) => table(
     ["NAME", "KIND", "GITHUB REPOSITORY", "PATH"],
     projectRows(value.projects),
   ));
@@ -364,14 +410,128 @@ async function dispatchPrepare(args) {
 async function projectRemove(args) {
   if (!args[2] || args[2].startsWith("--")) throw new Error("project remove requires a name");
   validateCommandArgs(args, 3, {
-    values: ["--workspace"],
-    switches: ["--json"],
+    values: [
+      "--workspace", "--expect-config-hash", "--expect-project-count", "--expect-after-count",
+      "--confirm-plan", "--confirm-removed", "--confirm-count-collapse",
+    ],
+    switches: ["--json", "--dry-run"],
   });
-  const result = await removeProject(workspaceRoot(args), args[2]);
-  print(result, args, (value) => `Removed ${value.project.name}: ${value.project.path}`);
+  const result = await removeProject(workspaceRoot(args), args[2], await mutationOptions(args));
+  print(result, args, (value) =>
+    `${args.includes("--dry-run") ? "Would remove" : "Removed"} ${value.project.name}: ${value.project.path}`);
   return 0;
 }
 
+async function projectUpdate(args) {
+  const hasName = Boolean(args[2] && !args[2].startsWith("--"));
+  validateCommandArgs(args, hasName ? 3 : 2, {
+    values: [
+      "--workspace", "--path", "--name", "--description", "--github-repo",
+      "--expect-config-hash",
+    ],
+    switches: ["--json", "--clear-description", "--no-github", "--refresh-git", "--dry-run"],
+    repeatable: ["--github-repo"],
+  });
+  const selectedPath = option(args, "--path", null);
+  if (hasName === Boolean(selectedPath)) throw new Error("project update requires exactly one name or --path selector");
+  if (args.includes("--description") && args.includes("--clear-description")) {
+    throw new Error("--description and --clear-description cannot be combined");
+  }
+  if (args.includes("--no-github") && args.includes("--github-repo")) {
+    throw new Error("--no-github and --github-repo cannot be combined");
+  }
+  const input = {};
+  if (args.includes("--name")) input.name = option(args, "--name", null);
+  if (args.includes("--description")) input.description = option(args, "--description", null);
+  if (args.includes("--clear-description")) input.clearDescription = true;
+  if (args.includes("--no-github")) input.githubRepos = [];
+  else if (args.includes("--github-repo")) input.githubRepos = options(args, "--github-repo");
+  if (args.includes("--refresh-git")) input.refreshGit = true;
+  const result = await updateProject(
+    workspaceRoot(args),
+    selectedPath ? { path: selectedPath } : { name: args[2] },
+    input,
+    await mutationOptions(args),
+  );
+  print(result, args, (value) => value.changed
+    ? `Updated ${value.project.name}: ${value.project.path}`
+    : `Unchanged ${value.project.name}: ${value.project.path}`);
+  return 0;
+}
+
+async function backupCommand(args) {
+  const action = args[1];
+  if (action === "list") {
+    validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
+    const result = await listWorkspaceBackups(workspaceRoot(args));
+    print(result, args, (value) => value.backups.map((item) =>
+      `${item.id}  ${item.usable ? "usable" : item.integrityValid ? "forensic" : "corrupt"}`)
+      .join("\n") || "No backups.");
+    return 0;
+  }
+  if (action === "create") {
+    validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
+    const result = await createWorkspaceBackup(workspaceRoot(args), { reason: "manual" });
+    print(result, args, (value) => `Created backup ${value.id}.`);
+    return 0;
+  }
+  if (action === "verify" && args[2]) {
+    validateCommandArgs(args, 3, { values: ["--workspace"], switches: ["--json"] });
+    const result = await verifyWorkspaceBackup(workspaceRoot(args), args[2]);
+    print(result, args, (value) => `${value.id}: ${value.usable ? "usable" : value.error}`);
+    return result.usable ? 0 : 1;
+  }
+  if (action === "prune") {
+    validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json", "--apply", "--dry-run"] });
+    if (args.includes("--apply") && args.includes("--dry-run")) throw new Error("--apply and --dry-run conflict");
+    const result = await pruneWorkspaceBackups(workspaceRoot(args), { apply: args.includes("--apply") });
+    print(result, args, (value) => `${value.apply ? "Pruned" : "Would prune"} ${value.removed.length} backup(s).`);
+    return 0;
+  }
+  if (action === "restore") {
+    const hasBackupId = Boolean(args[2] && !args[2].startsWith("--"));
+    validateCommandArgs(args, hasBackupId ? 3 : 2, {
+      values: [
+        "--workspace", "--scope", "--expect-config-hash", "--expect-project-count",
+        "--expect-after-count", "--confirm-plan", "--confirm-removed", "--confirm-count-collapse",
+        "--resume", "--rollback",
+      ],
+      switches: [
+        "--json", "--dry-run", "--approve-restore", "--confirm-offline",
+        "--confirm-unreadable-current",
+      ],
+    });
+    const resume = option(args, "--resume", null);
+    const rollback = option(args, "--rollback", null);
+    if ([hasBackupId, resume !== null, rollback !== null].filter(Boolean).length !== 1) {
+      throw new Error("backup restore requires exactly one backup ID, --resume ID, or --rollback ID");
+    }
+    let backupId = hasBackupId ? args[2] : null;
+    let maintenanceTransaction = null;
+    if (resume !== null || rollback !== null) {
+      const maintenance = await readWorkspaceMaintenance(workspaceRoot(args));
+      maintenanceTransaction = resume ?? rollback;
+      if (!maintenance.active || maintenance.transactionId !== maintenanceTransaction) {
+        throw new Error("maintenance transaction not found");
+      }
+      backupId = resume !== null ? maintenance.backupId : maintenance.safetyBackupId;
+    }
+    const result = await restoreWorkspaceBackup(workspaceRoot(args), backupId, {
+      ...(await mutationOptions(args)),
+      scope: resume !== null || rollback !== null ? "state" : option(args, "--scope", "projects"),
+      approveRestore: args.includes("--approve-restore"),
+      confirmOffline: args.includes("--confirm-offline"),
+      confirmUnreadableCurrent: args.includes("--confirm-unreadable-current"),
+      maintenanceTransaction,
+    });
+    print(result, args, (value) => value.dryRun
+      ? `Restore preview ${value.beforeCount} -> ${value.afterCount}.`
+      : `Restored backup ${value.backupId} (${value.scope}).`);
+    return 0;
+  }
+  throw new Error("backup command requires list, create, verify, prune, or restore");
+}
+
 async function taskRecord(args) {
   validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
   const dispatch = await recordTask(workspaceRoot(args), await readJsonStdin());
@@ -520,8 +680,10 @@ Usage:
   taskchef workspace migrate [--json] [--workspace <path>]
   taskchef project add <path> [--name <name>] [--description <text>] [--github-repo <url> ... | --no-github] [--json] [--workspace <path>]
   taskchef project import [<file> | -] [--replace] [--json] [--workspace <path>]
-  taskchef project list [--json] [--workspace <path>]
-  taskchef project remove <name> [--json] [--workspace <path>]
+  taskchef project list [--allow-missing-paths] [--json] [--workspace <path>]
+  taskchef project update <name> [fields] [--dry-run] [--expect-config-hash <sha256>] [--json]
+  taskchef project remove <name> --dry-run [--json] [--workspace <path>]
+  taskchef backup list|create|verify|restore|prune [options]
   taskchef dispatch prepare [--json] [--workspace <path>]
   taskchef task record [--json] [--workspace <path>]
   taskchef task brief [<task-id-or-8-character-prefix> | --project <name-or-path>] [--all] [--json] [--workspace <path>]
@@ -536,8 +698,8 @@ Project import reads a JSON
 array from a file, or from standard input when the source is '-' or omitted.
 Workspace resolution precedence is --workspace, TASKCHEF_WORKSPACE, then
 ~/.agents/taskchef.
-The foreground dashboard binds to 127.0.0.1 and reads the canonical task log
-without modifying dispatcher-workspace files. The dispatcher MCP may reuse a
+The foreground dashboard binds to 127.0.0.1 and creates one verified startup
+snapshot before reading the canonical task log. The dispatcher MCP may reuse a
 compatible foreground server on port 3210; neither mode terminates a listener
 that already occupies its requested port.
 `);
@@ -556,7 +718,9 @@ export async function runCli(args) {
   if (args[0] === "project" && args[1] === "add") return projectAdd(args);
   if (args[0] === "project" && args[1] === "import") return projectImport(args);
   if (args[0] === "project" && args[1] === "list") return projectList(args);
+  if (args[0] === "project" && args[1] === "update") return projectUpdate(args);
   if (args[0] === "project" && args[1] === "remove") return projectRemove(args);
+  if (args[0] === "backup") return backupCommand(args);
   if (args[0] === "dispatch" && args[1] === "prepare") return dispatchPrepare(args);
   if (args[0] === "task" && args[1] === "record") return taskRecord(args);
   if (args[0] === "task" && args[1] === "brief") return taskBrief(args);

package/src/config-audit.js

@@ -0,0 +1,99 @@
+import { open, readFile, readdir, rename, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+import { taskChefError } from "./state-store.js";
+
+export async function appendAuditUnlocked(workspace, record) {
+  const filePath = path.join(workspace, "config-audit.jsonl");
+  const size = await stat(filePath).then((details) => details.size).catch((error) => {
+    if (error.code === "ENOENT") return 0;
+    throw error;
+  });
+  if (size >= 10 * 1024 * 1024) {
+    const timestamp = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+    await rename(filePath, path.join(workspace, `config-audit.${timestamp}.jsonl`));
+    const archives = (await readdir(workspace))
+      .filter((name) => /^config-audit\..+\.jsonl$/.test(name))
+      .sort()
+      .reverse();
+    for (const name of archives.slice(10)) await unlink(path.join(workspace, name));
+  }
+  const handle = await open(filePath, "a", 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify({ schemaVersion: 1, ...record })}\n`);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function readLatestAuditRecordsUnlocked(workspace) {
+  const filePath = path.join(workspace, "config-audit.jsonl");
+  const content = await readFile(filePath, "utf8").catch((error) => {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  });
+  const latest = new Map();
+  for (const [index, line] of content.trimEnd().split("\n").entries()) {
+    if (line.length === 0) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      throw taskChefError(
+        "STATE_RECOVERY_REQUIRED",
+        `configuration audit is malformed at line ${index + 1}`,
+      );
+    }
+    if (record.transactionId) latest.set(record.transactionId, record);
+  }
+  return latest;
+}
+
+export async function validateAuditUnlocked(workspace) {
+  await readLatestAuditRecordsUnlocked(workspace);
+}
+
+export async function reconcileAuditUnlocked(workspace, currentHash) {
+  const latest = await readLatestAuditRecordsUnlocked(workspace);
+  for (const record of latest.values()) {
+    if (record.phase !== "prepared" && record.phase !== "recovery-required") continue;
+    if (currentHash === record.beforeHash) {
+      await appendAuditUnlocked(workspace, {
+        ...record,
+        timestamp: new Date().toISOString(),
+        phase: "aborted",
+        reconciliation: "matched-before",
+      });
+    } else if (currentHash === record.afterHash) {
+      await appendAuditUnlocked(workspace, {
+        ...record,
+        timestamp: new Date().toISOString(),
+        phase: "committed",
+        reconciliation: "matched-after",
+      });
+    } else {
+      throw taskChefError(
+        "STATE_RECOVERY_REQUIRED",
+        `configuration does not match either side of transaction ${record.transactionId}`,
+        { transactionId: record.transactionId },
+      );
+    }
+  }
+}
+
+export async function supersedeAuditTransactionsUnlocked(workspace, recoveryTransactionId) {
+  const latest = await readLatestAuditRecordsUnlocked(workspace);
+  const superseded = [];
+  for (const record of latest.values()) {
+    if (record.transactionId === recoveryTransactionId
+        || !new Set(["prepared", "recovery-required"]).has(record.phase)) continue;
+    await appendAuditUnlocked(workspace, {
+      ...record,
+      timestamp: new Date().toISOString(),
+      phase: "superseded",
+      supersededBy: recoveryTransactionId,
+    });
+    superseded.push(record.transactionId);
+  }
+  return superseded;
+}

package/src/config-mutations.js

@@ -0,0 +1,98 @@
+import { semanticHash, taskChefError } from "./state-store.js";
+
+function fieldsChanged(before, after) {
+  const fields = {};
+  for (const key of ["name", "description", "isGitRepository", "githubRepos"]) {
+    if (JSON.stringify(before[key]) !== JSON.stringify(after[key])) {
+      fields[key] = { before: before[key] ?? null, after: after[key] ?? null };
+    }
+  }
+  return fields;
+}
+
+export function projectSetHash(projects) {
+  return semanticHash({ schemaVersion: 1, projects }, "taskchef-project-set-v1");
+}
+
+export function configHash(config) {
+  return semanticHash(config, "taskchef-config-v1");
+}
+
+export function projectDiff(beforeProjects, afterProjects) {
+  const before = new Map(beforeProjects.map((project) => [project.path, project]));
+  const after = new Map(afterProjects.map((project) => [project.path, project]));
+  const added = [];
+  const changed = [];
+  const removed = [];
+  for (const project of afterProjects) {
+    const prior = before.get(project.path);
+    if (!prior) added.push(project);
+    else {
+      const fields = fieldsChanged(prior, project);
+      if (Object.keys(fields).length) changed.push({ path: project.path, before: prior, after: project, fields });
+    }
+  }
+  for (const project of beforeProjects) {
+    if (!after.has(project.path)) removed.push(project);
+  }
+  return { added, changed, removed };
+}
+
+export function mutationPreview(workspace, operation, beforeConfig, afterConfig) {
+  const diff = projectDiff(beforeConfig.projects, afterConfig.projects);
+  const preview = {
+    schemaVersion: 1,
+    operation,
+    beforeConfigHash: configHash(beforeConfig),
+    afterConfigHash: configHash(afterConfig),
+    beforeProjectSetHash: projectSetHash(beforeConfig.projects),
+    afterProjectSetHash: projectSetHash(afterConfig.projects),
+    beforeCount: beforeConfig.projects.length,
+    afterCount: afterConfig.projects.length,
+    diff,
+    projects: afterConfig.projects,
+  };
+  return {
+    ...preview,
+    planHash: semanticHash({
+      schemaVersion: 1,
+      workspace,
+      operation,
+      beforeConfigHash: preview.beforeConfigHash,
+      afterConfigHash: preview.afterConfigHash,
+      diff,
+    }, "taskchef-mutation-plan-v1"),
+  };
+}
+
+function exactStringSet(actual, expected) {
+  if (!Array.isArray(actual) || new Set(actual).size !== actual.length) return false;
+  return actual.length === expected.length
+    && [...actual].sort().every((value, index) => value === [...expected].sort()[index]);
+}
+
+export function assertMutationAuthorization(preview, authorization = {}, {
+  destructive = preview.diff.removed.length > 0,
+  replacement = false,
+} = {}) {
+  if (authorization.expectConfigHash !== preview.beforeConfigHash) {
+    throw taskChefError("STALE_PREVIEW", "configuration changed or --expect-config-hash is missing", preview);
+  }
+  if (!destructive && !replacement) return;
+  const removedNames = preview.diff.removed.map((project) => project.name);
+  if (authorization.expectProjectCount !== preview.beforeCount
+    || authorization.expectAfterCount !== preview.afterCount
+    || authorization.confirmPlan !== preview.planHash
+    || !exactStringSet(authorization.confirmRemoved, removedNames)) {
+    throw taskChefError(
+      "CONFIRMATION_REQUIRED",
+      "destructive project mutation requires exact preview-bound count, hash, plan, and removed-name confirmation",
+      preview,
+    );
+  }
+  const collapses = preview.beforeCount > 0
+    && (preview.afterCount === 0 || preview.afterCount / preview.beforeCount <= 0.5);
+  if (collapses && authorization.confirmCountCollapse !== `${preview.beforeCount}:${preview.afterCount}`) {
+    throw taskChefError("CONFIRMATION_REQUIRED", "project-count collapse requires exact before:after confirmation", preview);
+  }
+}