trackops 2.0.3 → 2.0.5

package/lib/control.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
-const fs = require("fs");
-const path = require("path");
-const { spawnSync } = require("child_process");
-
-const config = require("./config");
-const env = require("./env");
-const { t, setLocale, getLocale } = require("./i18n");
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const config = require("./config");
+const env = require("./env");
+const { t, setLocale, getLocale } = require("./i18n");
 
 const PRIORITY_ORDER = ["P0", "P1", "P2", "P3"];
 const STATUS_ORDER = ["in_progress", "in_review", "pending", "blocked", "completed", "cancelled"];
@@ -51,14 +51,14 @@ function statusLabel(status) {
 
 /* ── repo snapshot ── */
 
-function getRepoSnapshot(contextOrRoot) {
-  const context = config.ensureContext(contextOrRoot);
-  const repoRoot = context.workspaceRoot;
-  const branch = git(["branch", "--show-current"], repoRoot) || "detached";
-  const status = git(["status", "--short"], repoRoot) || "";
-  const lines = status.split(/\r?\n/).filter(Boolean);
-  const lastCommitRaw = git(["log", "-1", "--pretty=format:%H%n%cs%n%s"], repoRoot);
-  const divergenceRaw = git(["rev-list", "--left-right", "--count", "@{upstream}...HEAD"], repoRoot);
+function getRepoSnapshot(contextOrRoot) {
+  const context = config.ensureContext(contextOrRoot);
+  const repoRoot = context.workspaceRoot;
+  const branch = git(["branch", "--show-current"], repoRoot) || "detached";
+  const status = git(["status", "--short"], repoRoot) || "";
+  const lines = status.split(/\r?\n/).filter(Boolean);
+  const lastCommitRaw = git(["log", "-1", "--pretty=format:%H%n%cs%n%s"], repoRoot);
+  const divergenceRaw = git(["rev-list", "--left-right", "--count", "@{upstream}...HEAD"], repoRoot);
 
   let staged = 0;
   let unstaged = 0;
@@ -87,17 +87,17 @@ function getRepoSnapshot(contextOrRoot) {
   return { generatedAt: nowIso(), branch, clean: lines.length === 0, staged, unstaged, untracked, ahead, behind, lastCommit };
 }
 
-function refreshRepoRuntime(root, options = {}) {
-  const context = config.ensureContext(root);
-  const runtimeFile = config.runtimeFilePath(context);
-  fs.mkdirSync(path.dirname(runtimeFile), { recursive: true });
-  const snapshot = getRepoSnapshot(context);
-  writeJson(runtimeFile, snapshot);
-  if (!options.quiet) {
-    console.log(t("cli.runtimeUpdated", { path: path.relative(context.workspaceRoot, runtimeFile) }));
-  }
-  return snapshot;
-}
+function refreshRepoRuntime(root, options = {}) {
+  const context = config.ensureContext(root);
+  const runtimeFile = config.runtimeFilePath(context);
+  fs.mkdirSync(path.dirname(runtimeFile), { recursive: true });
+  const snapshot = getRepoSnapshot(context);
+  writeJson(runtimeFile, snapshot);
+  if (!options.quiet) {
+    console.log(t("cli.runtimeUpdated", { path: path.relative(context.workspaceRoot, runtimeFile) }));
+  }
+  return snapshot;
+}
 
 /* ── derive ── */
 
@@ -115,11 +115,11 @@ function compareTasks(a, b, phases) {
   return a.title.localeCompare(b.title, getLocale());
 }
 
-function derive(control) {
-  const phases = config.getPhases(control);
-  const tasks = [...control.tasks].sort((a, b) => compareTasks(a, b, phases));
-  const completedIds = new Set(tasks.filter((t) => t.status === "completed").map((t) => t.id));
-  const closedStatuses = new Set(["completed", "cancelled"]);
+function derive(control) {
+  const phases = config.getPhases(control);
+  const tasks = [...control.tasks].sort((a, b) => compareTasks(a, b, phases));
+  const completedIds = new Set(tasks.filter((t) => t.status === "completed").map((t) => t.id));
+  const closedStatuses = new Set(["completed", "cancelled"]);
 
   const readyTasks = tasks
     .filter((task) => {
@@ -144,12 +144,12 @@ function derive(control) {
     phases.find((p) => requiredOpenTasks.some((t) => t.phase === p.id)) ||
     phases[phases.length - 1];
 
-  const phaseStats = phases.map((phase) => {
-    const phaseTasks = tasks.filter((t) => t.phase === phase.id && t.required !== false);
-    const completed = phaseTasks.filter((t) => t.status === "completed").length;
-    const closed = phaseTasks.filter((t) => closedStatuses.has(t.status)).length;
-    return { ...phase, total: phaseTasks.length, completed, closed, remaining: phaseTasks.length - closed };
-  });
+  const phaseStats = phases.map((phase) => {
+    const phaseTasks = tasks.filter((t) => t.phase === phase.id && t.required !== false);
+    const completed = phaseTasks.filter((t) => t.status === "completed").length;
+    const closed = phaseTasks.filter((t) => closedStatuses.has(t.status)).length;
+    return { ...phase, total: phaseTasks.length, completed, closed, remaining: phaseTasks.length - closed };
+  });
 
   const nextTask = activeTasks[0] || readyTasks[0] || blockers[0] || openTasks[0] || null;
 
@@ -359,11 +359,11 @@ function buildDocMap(control) {
   return { taskPlan: renderTaskPlan(control), progress: renderProgress(control), findings: renderFindings(control) };
 }
 
-function getDocDrift(root, control) {
-  const context = config.ensureContext(root);
-  const docs = buildDocMap(control);
-  const docFiles = config.docFilePaths(context);
-  return Object.entries({ task_plan: [docFiles.taskPlan, docs.taskPlan], progress: [docFiles.progress, docs.progress], findings: [docFiles.findings, docs.findings] })
+function getDocDrift(root, control) {
+  const context = config.ensureContext(root);
+  const docs = buildDocMap(control);
+  const docFiles = config.docFilePaths(context);
+  return Object.entries({ task_plan: [docFiles.taskPlan, docs.taskPlan], progress: [docFiles.progress, docs.progress], findings: [docFiles.findings, docs.findings] })
     .filter(([, [filePath, expected]]) => {
       if (!fs.existsSync(filePath)) return true;
       return fs.readFileSync(filePath, "utf8").replace(/\r\n/g, "\n") !== `${expected}\n`;
@@ -371,21 +371,21 @@ function getDocDrift(root, control) {
     .map(([name]) => name);
 }
 
-function syncDocs(root, control) {
-  const context = config.ensureContext(root);
-  const docs = buildDocMap(control);
-  const docFiles = config.docFilePaths(context);
-  writeText(docFiles.taskPlan, `${docs.taskPlan}\n`);
-  writeText(docFiles.progress, `${docs.progress}\n`);
-  writeText(docFiles.findings, `${docs.findings}\n`);
-}
+function syncDocs(root, control) {
+  const context = config.ensureContext(root);
+  const docs = buildDocMap(control);
+  const docFiles = config.docFilePaths(context);
+  writeText(docFiles.taskPlan, `${docs.taskPlan}\n`);
+  writeText(docFiles.progress, `${docs.progress}\n`);
+  writeText(docFiles.findings, `${docs.findings}\n`);
+}
 
 /* ── task management ── */
 
-function updateTask(root, control, action, taskId, note) {
-  const context = config.ensureContext(root);
-  const task = control.tasks.find((item) => item.id === taskId);
-  if (!task) throw new Error(t("cli.taskNotFound", { taskId }));
+function updateTask(root, control, action, taskId, note) {
+  const context = config.ensureContext(root);
+  const task = control.tasks.find((item) => item.id === taskId);
+  if (!task) throw new Error(t("cli.taskNotFound", { taskId }));
 
   const actionMap = { start: "in_progress", review: "in_review", complete: "completed", done: "completed", block: "blocked", pending: "pending", cancel: "cancelled" };
 
@@ -406,49 +406,49 @@ function updateTask(root, control, action, taskId, note) {
     task.history.push({ at: nowIso(), action, note: note || "" });
   }
 
-  config.saveControl(context, control);
-  syncDocs(context, control);
-  refreshRepoRuntime(context, { quiet: true });
-}
+  config.saveControl(context, control);
+  syncDocs(context, control);
+  refreshRepoRuntime(context, { quiet: true });
+}
 
 /* ── CLI commands ── */
 
-function initLocale(root) {
-  try {
-    const control = config.loadControl(config.ensureContext(root));
-    setLocale(config.getLocale(control));
-  } catch (_err) {
-    setLocale("es");
+function initLocale(root) {
+  try {
+    const control = config.loadControl(config.ensureContext(root));
+    setLocale(config.getLocale(control));
+  } catch (_err) {
+    setLocale("es");
   }
 }
 
-function cmdStatus(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const control = config.loadControl(context);
-  const state = derive(control);
-  const phases = config.getPhases(control);
-  const repo = refreshRepoRuntime(context, { quiet: true });
-  const drift = getDocDrift(context, control);
-  const envAudit = env.auditEnvironment(context, control);
-
-  console.log(t("cli.status.title", { projectName: control.meta.projectName }));
-  console.log(t("cli.status.focus", { focus: control.meta.currentFocus }));
-  console.log(t("cli.status.activePhase", { phaseId: state.activePhase.id, phaseLabel: state.activePhase.label }));
-  console.log(`Layout: ${context.layout} | Workspace: ${context.workspaceRoot}`);
-  if (context.layout === "split") {
-    console.log(`App: ${context.appRoot}`);
-    console.log(`Ops: ${context.opsRoot}`);
-  }
-  if (control.meta?.opera?.bootstrap?.status) {
-    console.log(t("cli.status.bootstrap", { status: control.meta.opera.bootstrap.status, locale: config.getLocale(control) }));
-    if (control.meta.opera.bootstrap.mode) {
-      console.log(`Bootstrap mode: ${control.meta.opera.bootstrap.mode}`);
-    }
-    if (control.meta.opera.bootstrap.routeReason) {
-      console.log(`Bootstrap route: ${control.meta.opera.bootstrap.routeReason}`);
-    }
-  }
+function cmdStatus(root) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const control = config.loadControl(context);
+  const state = derive(control);
+  const phases = config.getPhases(control);
+  const repo = refreshRepoRuntime(context, { quiet: true });
+  const drift = getDocDrift(context, control);
+  const envAudit = env.auditEnvironment(context, control);
+
+  console.log(t("cli.status.title", { projectName: control.meta.projectName }));
+  console.log(t("cli.status.focus", { focus: control.meta.currentFocus }));
+  console.log(t("cli.status.activePhase", { phaseId: state.activePhase.id, phaseLabel: state.activePhase.label }));
+  console.log(`Layout: ${context.layout} | Workspace: ${context.workspaceRoot}`);
+  if (context.layout === "split") {
+    console.log(`App: ${context.appRoot}`);
+    console.log(`Ops: ${context.opsRoot}`);
+  }
+  if (control.meta?.opera?.bootstrap?.status) {
+    console.log(t("cli.status.bootstrap", { status: control.meta.opera.bootstrap.status, locale: config.getLocale(control) }));
+    if (control.meta.opera.bootstrap.mode) {
+      console.log(`Bootstrap mode: ${control.meta.opera.bootstrap.mode}`);
+    }
+    if (control.meta.opera.bootstrap.routeReason) {
+      console.log(`Bootstrap route: ${control.meta.opera.bootstrap.routeReason}`);
+    }
+  }
   console.log(t("cli.status.tasks", {
     completed: state.totals.completed, inProgress: state.totals.inProgress,
     inReview: state.totals.inReview, pending: state.totals.pending, blocked: state.totals.blocked,
@@ -485,22 +485,22 @@ function cmdStatus(root) {
   }
   if (repo.ahead || repo.behind) {
     console.log(`- ${t("cli.status.divergence", { ahead: repo.ahead, behind: repo.behind })}`);
-  }
-  console.log(`- ${t("cli.status.runtime", { path: path.relative(context.workspaceRoot, config.runtimeFilePath(context)) })}`);
-  console.log(`- Env present: ${envAudit.presentKeys.length ? envAudit.presentKeys.join(", ") : "none"}`);
-  console.log(`- Env missing: ${envAudit.missingKeys.length ? envAudit.missingKeys.join(", ") : "none"}`);
-  console.log("");
-  const syncStatus = drift.length
-    ? t("cli.status.docsSyncedNo", { files: drift.join(", ") })
+  }
+  console.log(`- ${t("cli.status.runtime", { path: path.relative(context.workspaceRoot, config.runtimeFilePath(context)) })}`);
+  console.log(`- Env present: ${envAudit.presentKeys.length ? envAudit.presentKeys.join(", ") : "none"}`);
+  console.log(`- Env missing: ${envAudit.missingKeys.length ? envAudit.missingKeys.join(", ") : "none"}`);
+  console.log("");
+  const syncStatus = drift.length
+    ? t("cli.status.docsSyncedNo", { files: drift.join(", ") })
     : t("cli.status.docsSyncedYes");
   console.log(t("cli.status.docsSynced", { status: syncStatus }));
 }
 
-function cmdNext(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const control = config.loadControl(context);
-  const ready = derive(control).readyTasks.slice(0, 10);
+function cmdNext(root) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const control = config.loadControl(context);
+  const ready = derive(control).readyTasks.slice(0, 10);
   if (!ready.length) {
     console.log(t("cli.noReadyTasks"));
     return;
@@ -513,114 +513,114 @@ function cmdNext(root) {
   });
 }
 
-function cmdSync(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const control = config.loadControl(context);
-  env.syncEnvironment(context, control);
-  syncDocs(context, control);
-  refreshRepoRuntime(context, { quiet: true });
-  console.log(t("cli.docsSynced"));
-}
-
-function cmdRefreshRepo(root, args) {
-  refreshRepoRuntime(config.ensureContext(root), { quiet: (args || []).includes("--quiet") });
-}
-
-function cmdTask(root, args) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const [action, taskId, ...noteParts] = args || [];
-  if (!action || !taskId) throw new Error(t("cli.mustProvideActionAndId"));
-  const control = config.loadControl(context);
-  updateTask(context, control, action, taskId, noteParts.join(" ").trim());
-  console.log(t("cli.taskUpdated", { taskId, action }));
-}
-
-function cmdInstallHooks(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const hooksPath = context.layout === "split" ? "ops/.githooks" : ".githooks";
-  const result = spawnSync("git", ["config", "core.hooksPath", hooksPath], { cwd: context.workspaceRoot, encoding: "utf8" });
-  if (result.error || result.status !== 0) throw new Error(t("cli.hooksError"));
-  console.log(t("cli.hooksInstalled"));
-}
-
-function cmdHelp() {
-  console.log(`trackops — ${t("cli.help.title")}`);
-  console.log("");
-  console.log(`${t("cli.help.usage")} trackops <command> [args]`);
-  console.log("");
-  console.log(t("cli.help.commands"));
-  console.log("  init [--with-opera] [--legacy-layout] [--locale es|en] [--name \"...\"] [--no-bootstrap]");
-  console.log("       [--bootstrap-mode auto|direct|handoff] [--technical-level low|medium|high|senior]");
-  console.log("       [--project-state idea|draft|existing_repo|advanced] [--docs-state none|notes|sos|spec_dossier|repo_docs]");
-  console.log("       [--decision-ownership user|shared|agent]");
-  console.log(`    ${t("cli.help.init.desc")}`);
-  console.log("  workspace status|migrate");
-  console.log(`    ${t("cli.help.workspace.desc")}`);
-  console.log("  env status|sync");
-  console.log(`    ${t("cli.help.env.desc")}`);
-  console.log("  release [--push]");
-  console.log(`    ${t("cli.help.release.desc")}`);
-  console.log("  version");
-  console.log(`    ${t("cli.help.version.desc")}`);
-  console.log("  status");
-  console.log(`    ${t("cli.help.status.desc")}`);
-  console.log("  next");
-  console.log(`    ${t("cli.help.next.desc")}`);
-  console.log("  sync");
-  console.log(`    ${t("cli.help.sync.desc")}`);
-  console.log("  dashboard [--port N] [--host HOST] [--public] [--strict-port]");
-  console.log(`    ${t("cli.help.dashboard.desc")}`);
-  console.log("  refresh-repo [--quiet]");
-  console.log(`    ${t("cli.help.refreshRepo.desc")}`);
-  console.log("  install-hooks");
-  console.log(`    ${t("cli.help.installHooks.desc")}`);
-  console.log("  register");
-  console.log(`    ${t("cli.help.register.desc")}`);
-  console.log("  projects");
-  console.log(`    ${t("cli.help.projects.desc")}`);
-  console.log("  task <action> <id> [note]");
-  console.log(`    ${t("cli.help.task.desc")}`);
-  console.log("  opera install|bootstrap|handoff|status|configure|upgrade");
-  console.log(`    ${t("cli.help.opera.desc")}`);
-  console.log(`    ${t("cli.help.opera.upgradeHint")}`);
-  console.log("  locale get|set [es|en]");
-  console.log(`    ${t("cli.help.locale.desc")}`);
-  console.log("  doctor locale");
-  console.log(`    ${t("cli.help.doctor.desc")}`);
-  console.log("  skill install|list|remove|catalog <name>");
-  console.log(`    ${t("cli.help.skill.desc")}`);
-  console.log("  help");
-  console.log(`    ${t("cli.help.help.desc")}`);
-  console.log("");
-  console.log(t("cli.help.globalWorkflow"));
-  console.log(`  ${t("cli.help.globalWorkflow.line1")}`);
-  console.log(`  ${t("cli.help.globalWorkflow.line2")}`);
-}
+function cmdSync(root) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const control = config.loadControl(context);
+  env.syncEnvironment(context, control);
+  syncDocs(context, control);
+  refreshRepoRuntime(context, { quiet: true });
+  console.log(t("cli.docsSynced"));
+}
+
+function cmdRefreshRepo(root, args) {
+  refreshRepoRuntime(config.ensureContext(root), { quiet: (args || []).includes("--quiet") });
+}
+
+function cmdTask(root, args) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const [action, taskId, ...noteParts] = args || [];
+  if (!action || !taskId) throw new Error(t("cli.mustProvideActionAndId"));
+  const control = config.loadControl(context);
+  updateTask(context, control, action, taskId, noteParts.join(" ").trim());
+  console.log(t("cli.taskUpdated", { taskId, action }));
+}
+
+function cmdInstallHooks(root) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const hooksPath = context.layout === "split" ? "ops/.githooks" : ".githooks";
+  const result = spawnSync("git", ["config", "core.hooksPath", hooksPath], { cwd: context.workspaceRoot, encoding: "utf8" });
+  if (result.error || result.status !== 0) throw new Error(t("cli.hooksError"));
+  console.log(t("cli.hooksInstalled"));
+}
+
+function cmdHelp() {
+  console.log(`trackops — ${t("cli.help.title")}`);
+  console.log("");
+  console.log(`${t("cli.help.usage")} trackops <command> [args]`);
+  console.log("");
+  console.log(t("cli.help.commands"));
+  console.log("  init [--with-opera] [--legacy-layout] [--locale es|en] [--name \"...\"] [--no-bootstrap]");
+  console.log("       [--bootstrap-mode auto|direct|handoff] [--technical-level low|medium|high|senior]");
+  console.log("       [--project-state idea|draft|existing_repo|advanced] [--docs-state none|notes|sos|spec_dossier|repo_docs]");
+  console.log("       [--decision-ownership user|shared|agent]");
+  console.log(`    ${t("cli.help.init.desc")}`);
+  console.log("  workspace status|migrate");
+  console.log(`    ${t("cli.help.workspace.desc")}`);
+  console.log("  env status|sync");
+  console.log(`    ${t("cli.help.env.desc")}`);
+  console.log("  release [--push]");
+  console.log(`    ${t("cli.help.release.desc")}`);
+  console.log("  version");
+  console.log(`    ${t("cli.help.version.desc")}`);
+  console.log("  status");
+  console.log(`    ${t("cli.help.status.desc")}`);
+  console.log("  next");
+  console.log(`    ${t("cli.help.next.desc")}`);
+  console.log("  sync");
+  console.log(`    ${t("cli.help.sync.desc")}`);
+  console.log("  dashboard [--port N] [--host HOST] [--public] [--strict-port]");
+  console.log(`    ${t("cli.help.dashboard.desc")}`);
+  console.log("  refresh-repo [--quiet]");
+  console.log(`    ${t("cli.help.refreshRepo.desc")}`);
+  console.log("  install-hooks");
+  console.log(`    ${t("cli.help.installHooks.desc")}`);
+  console.log("  register");
+  console.log(`    ${t("cli.help.register.desc")}`);
+  console.log("  projects");
+  console.log(`    ${t("cli.help.projects.desc")}`);
+  console.log("  task <action> <id> [note]");
+  console.log(`    ${t("cli.help.task.desc")}`);
+  console.log("  opera install|bootstrap|handoff|status|configure|upgrade");
+  console.log(`    ${t("cli.help.opera.desc")}`);
+  console.log(`    ${t("cli.help.opera.upgradeHint")}`);
+  console.log("  locale get|set [es|en]");
+  console.log(`    ${t("cli.help.locale.desc")}`);
+  console.log("  doctor locale");
+  console.log(`    ${t("cli.help.doctor.desc")}`);
+  console.log("  skill install|list|remove|catalog <name>");
+  console.log(`    ${t("cli.help.skill.desc")}`);
+  console.log("  help");
+  console.log(`    ${t("cli.help.help.desc")}`);
+  console.log("");
+  console.log(t("cli.help.globalWorkflow"));
+  console.log(`  ${t("cli.help.globalWorkflow.line1")}`);
+  console.log(`  ${t("cli.help.globalWorkflow.line2")}`);
+}
 
 /* ── project-scoped API (used by server) ── */
 
-function forProject(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  return {
-    loadControl: () => config.loadControl(context),
-    saveControl: (ctrl) => config.saveControl(context, ctrl),
-    derive,
-    buildDocMap,
-    getDocDrift: (ctrl) => getDocDrift(context, ctrl),
-    syncDocs: (ctrl) => syncDocs(context, ctrl),
-    updateTask: (ctrl, action, id, note) => updateTask(context, ctrl, action, id, note),
-    getRepoSnapshot: () => getRepoSnapshot(context),
-    refreshRepoRuntime: (opts) => refreshRepoRuntime(context, opts),
-    getPhases: (ctrl) => config.getPhases(ctrl),
-    getLocale: (ctrl) => config.getLocale(ctrl),
-    statusLabel,
-    context,
-  };
-}
+function forProject(root) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  return {
+    loadControl: () => config.loadControl(context),
+    saveControl: (ctrl) => config.saveControl(context, ctrl),
+    derive,
+    buildDocMap,
+    getDocDrift: (ctrl) => getDocDrift(context, ctrl),
+    syncDocs: (ctrl) => syncDocs(context, ctrl),
+    updateTask: (ctrl, action, id, note) => updateTask(context, ctrl, action, id, note),
+    getRepoSnapshot: () => getRepoSnapshot(context),
+    refreshRepoRuntime: (opts) => refreshRepoRuntime(context, opts),
+    getPhases: (ctrl) => config.getPhases(ctrl),
+    getLocale: (ctrl) => config.getLocale(ctrl),
+    statusLabel,
+    context,
+  };
+}
 
 module.exports = {
   buildDocMap, derive, getDocDrift, getRepoSnapshot, refreshRepoRuntime, syncDocs, updateTask,