trackops 2.0.5 → 2.1.0

package/lib/opera.js

@@ -10,19 +10,52 @@ const { promptForLocale, maybePromptForLocale, resolveLocale } = require("./loca
 const { resolveLocalizedFile, resolveLocalizedDir, resolveSkillFile } = require("./resources");
 const bootstrap = require("./opera-bootstrap");
 const runtimeState = require("./runtime-state");
+const fmt = require("./cli-format");
 
 const TEMPLATES_DIR = path.join(__dirname, "..", "templates", "opera");
 const SKILLS_TEMPLATES_DIR = path.join(__dirname, "..", "templates", "skills");
 const OPERA_VERSION = require("../package.json").version;
-const AUXILIARY_SKILLS = ["opera-skill", "project-starter-skill", "opera-contract-auditor", "opera-policy-guard"];
+const AUXILIARY_SKILLS = ["opera-skill", "opera-quality-guard", "project-starter-skill", "opera-contract-auditor", "opera-policy-guard"];
 
 function nowIso() {
   return new Date().toISOString();
 }
 
-function formatLocaleSource(source) {
-  return t(`locale.source.${String(source || "").trim()}`) || source || t("locale.none");
-}
+function formatLocaleSource(source) {
+  return t(`locale.source.${String(source || "").trim()}`) || source || t("locale.none");
+}
+
+function formatBootstrapStatus(status) {
+  return t(`bootstrap.status.${String(status || "").trim()}`) || status || t("locale.none");
+}
+
+function formatBootstrapMode(mode) {
+  return t(`bootstrap.mode.${String(mode || "").trim()}`) || mode || t("locale.none");
+}
+
+function formatBootstrapReason(reason) {
+  return t(`bootstrap.reason.${String(reason || "").trim()}`) || reason || t("locale.none");
+}
+
+function formatDecisionOwnership(value) {
+  return t(`bootstrap.ownership.${String(value || "").trim()}`) || value || t("locale.none");
+}
+
+function formatContractReadiness(value) {
+  return t(`bootstrap.readiness.${String(value || "").trim()}`) || value || t("locale.none");
+}
+
+function formatLegacyStatus(value) {
+  return t(`bootstrap.legacy.${String(value || "").trim()}`) || value || t("locale.none");
+}
+
+function formatMissingFields(fields) {
+  return (fields || []).map((field) => t(`bootstrap.field.${field}`) || field).join(", ");
+}
+
+function relativePathExists(context, relativePath) {
+  return Boolean(relativePath) && fs.existsSync(path.join(context.workspaceRoot, relativePath));
+}
 
 function readText(filePath) {
   return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
@@ -88,7 +121,10 @@ function resolveOperaLocale(control, options = {}) {
 
 function seedAuxiliarySkill(skillName, locale, skillsDir, options = {}) {
   const templateDir = path.join(SKILLS_TEMPLATES_DIR, skillName);
-  if (!fs.existsSync(templateDir)) return;
+  if (!fs.existsSync(templateDir)) {
+    process.stderr.write(`[opera] Warning: skill template not found: ${skillName} (${templateDir})\n`);
+    return;
+  }
   const targetDir = path.join(skillsDir, skillName);
   seedDirRecursive(templateDir, targetDir, {
     overwrite: options.rewriteLocalizedTemplates === true,
@@ -222,22 +258,36 @@ async function install(root, options = {}) {
   config.saveControl(context, control);
   env.syncEnvironment(context, control);
 
+  fmt.blank();
   if (!alreadyInstalled) {
-    console.log(t("opera.installed", { version: OPERA_VERSION }));
+    fmt.success(t("opera.installed", { version: OPERA_VERSION }));
   } else {
-    console.log(t("opera.alreadyInstalled", { version: config.getOperaVersion(control) || OPERA_VERSION }));
+    fmt.info(t("opera.alreadyInstalled", { version: config.getOperaVersion(control) || OPERA_VERSION }));
   }
 
   const skills = require("./skills");
   for (const skillName of ["commiter", "changelog-updater"]) {
     try {
       skills.installSkill(context, skillName, { locale });
-    } catch (_error) {
-      // ignore
+    } catch (error) {
+      fmt.warn(t("skill.installError", { name: skillName, error: error.message }));
     }
   }
   skills.updateRegistry(context);
 
+  if (options.bootstrap !== false && options.interactive !== false) {
+    const readline = require("readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+      rl.question(`  ${t("opera.install.bootstrapConfirm")} `, (ans) => { rl.close(); resolve(ans); });
+    });
+    const normalizedAnswer = String(answer || "").trim().toLowerCase();
+    if (!["y", "yes", "s", "si"].includes(normalizedAnswer)) {
+      fmt.info(t("opera.install.bootstrapSkipped"));
+      fmt.blank();
+      return;
+    }
+  }
   if (options.bootstrap !== false) {
     await runBootstrap(context, {
       locale,
@@ -302,37 +352,85 @@ async function runBootstrap(root, options = {}) {
   if ((options.resume || options.forceResume) && control.meta?.opera?.bootstrap) {
     const resumed = bootstrap.resumeBootstrap(context, control);
     if (resumed.resumed) {
-      const updatedControl = bootstrap.applyBootstrap(context, control, resumed.profile);
+      const profile = resumed.profile;
+      const updatedControl = bootstrap.applyBootstrap(context, control, profile);
       env.syncEnvironment(context, updatedControl, { requiredKeys: env.inferRequiredKeys(updatedControl, context) });
       const ops = require("./control");
       ops.syncDocs(context, updatedControl);
       ops.refreshRepoRuntime(context, { quiet: true });
-      console.log(t("bootstrap.completed"));
-      return resumed.profile;
+      fmt.blank();
+
+      if (profile.status === "completed") {
+        fmt.success(t("bootstrap.completed"));
+        fmt.blank();
+        fmt.step(t("bootstrap.next.label"));
+        fmt.hint(t("bootstrap.next.directCompleted"));
+      } else if (profile.status === "blocked") {
+        fmt.warn(t("bootstrap.resumeBlocked"));
+        for (const field of profile.missingFields || []) {
+          fmt.bullet(t(`bootstrap.field.${field}`) || field);
+        }
+        fmt.blank();
+        fmt.hint(t("bootstrap.next.directPending"));
+      } else if (profile.status === "needs_review") {
+        fmt.info(t("bootstrap.resumeNeedsReview"));
+        for (const field of profile.missingFields || []) {
+          fmt.bullet(t(`bootstrap.field.${field}`) || field);
+        }
+        fmt.blank();
+        fmt.hint(t("bootstrap.next.directPending"));
+      }
+
+      fmt.blank();
+      return profile;
+    }
+    fmt.blank();
+    if (resumed.reason === "missing_agent_artifacts") {
+      fmt.warn(t("bootstrap.resumeAwaitingArtifacts"));
+    } else if (resumed.reason === "empty_intake_and_spec") {
+      fmt.warn(t("bootstrap.resumeEmptyArtifacts"));
+    } else {
+      fmt.info(t("bootstrap.awaitingAgent"));
     }
-    console.log(t("bootstrap.awaitingAgent"));
+    fmt.hint(t("bootstrap.next.handoff"));
+    fmt.blank();
     return control.meta.opera.bootstrap;
   }
 
-  const profile = await bootstrap.collectBootstrapProfile(context, control, options);
+  const profile = await bootstrap.collectBootstrapProfile(context, control, options);
+  if (profile.mode && profile.routeReason) {
+    fmt.blank();
+    fmt.info(t("bootstrap.routingMode", {
+      mode: formatBootstrapMode(profile.mode),
+      reason: formatBootstrapReason(profile.routeReason),
+    }));
+  }
   const updatedControl = bootstrap.applyBootstrap(context, control, profile);
   env.syncEnvironment(context, updatedControl, { requiredKeys: env.inferRequiredKeys(updatedControl, context) });
   const ops = require("./control");
   ops.syncDocs(context, updatedControl);
   ops.refreshRepoRuntime(context, { quiet: true });
 
+  fmt.header(t("bootstrap.resultHeader"));
+
   if (profile.mode === "agent_handoff") {
-    console.log(t("bootstrap.awaitingAgent"));
-    console.log(`${t("bootstrap.handoffFile")}: ${profile.handoffFiles?.markdown || bootstrap.bootstrapRelativePaths(context).markdown}`);
-    console.log(t("bootstrap.next.handoff"));
+    fmt.info(t("bootstrap.awaitingAgent"));
+    fmt.blank();
+    fmt.step(t("bootstrap.handoffFile"), profile.handoffFiles?.markdown || bootstrap.bootstrapRelativePaths(context).markdown);
+    fmt.blank();
+    fmt.step(t("bootstrap.next.label"));
+    fmt.hint(t("bootstrap.next.handoff"));
   } else {
-    console.log(profile.status === "completed" ? t("bootstrap.completed") : t("bootstrap.pending"));
-    console.log(
+    fmt.success(profile.status === "completed" ? t("bootstrap.completed") : t("bootstrap.pending"));
+    fmt.blank();
+    fmt.step(t("bootstrap.next.label"));
+    fmt.hint(
       profile.status === "completed"
         ? t("bootstrap.next.directCompleted")
         : t("bootstrap.next.directPending"),
     );
   }
+  fmt.blank();
   return profile;
 }
 
@@ -346,39 +444,59 @@ function status(root) {
     return;
   }
 
-  const opera = control.meta.opera;
-  const bootstrapState = opera.bootstrap || bootstrap.detectLegacyBootstrap(context, control);
-  const localeDoctor = runtimeState.doctorLocale(control.meta?.locale || null);
-  console.log(t("opera.status.version", { version: opera.version }));
-  console.log(t("opera.status.installed", { value: opera.installedAt }));
-  console.log(t("opera.status.skills", { value: (opera.skills || []).join(", ") || t("locale.none") }));
-  console.log(t("opera.status.locale", { locale: config.getLocale(control), source: formatLocaleSource(localeDoctor.source) }));
-  console.log(t("opera.status.legacy", { value: opera.legacyStatus || bootstrapState?.status || "supported" }));
-  console.log(t("opera.status.contractVersion", { value: opera.contractVersion || t("locale.none") }));
-  console.log(t("opera.status.contractReadiness", { value: opera.contractReadiness || "hypothesis" }));
-
-  if (bootstrapState) {
-    console.log(t("opera.status.bootstrap", { value: bootstrapState.status }));
-    if (bootstrapState.mode) {
-      console.log(t("opera.status.mode", { value: bootstrapState.mode }));
-    }
-    if (bootstrapState.routeReason) {
-      console.log(t("opera.status.route", { value: bootstrapState.routeReason }));
-    }
-    if (bootstrapState.decisionOwnership) {
-      console.log(t("opera.status.ownership", { value: bootstrapState.decisionOwnership }));
-    }
-    if ((bootstrapState.missingFields || []).length) {
-      console.log(t("opera.status.missing", { value: bootstrapState.missingFields.join(", ") }));
-      console.log(t("opera.status.resume"));
-    }
-    if (bootstrapState.handoffFiles?.markdown) {
-      console.log(t("opera.status.handoff", { value: bootstrapState.handoffFiles.markdown }));
-    }
-    if (bootstrapState.reviewFiles?.qualityReport) {
-      console.log(t("opera.status.qualityReport", { value: bootstrapState.reviewFiles.qualityReport }));
-    }
-  }
+  const opera = control.meta.opera;
+  const bootstrapState = opera.bootstrap || bootstrap.detectLegacyBootstrap(context, control);
+  const localeDoctor = runtimeState.doctorLocale(control.meta?.locale || null);
+  console.log(t("opera.status.version", { version: opera.version }));
+  console.log(t("opera.status.installed", { value: opera.installedAt }));
+  console.log(t("opera.status.skills", { value: (opera.skills || []).join(", ") || t("locale.none") }));
+  console.log(t("opera.status.locale", { locale: config.getLocale(control), source: formatLocaleSource(localeDoctor.source) }));
+  console.log(t("opera.status.legacy", { value: formatLegacyStatus(opera.legacyStatus || bootstrapState?.status || "supported") }));
+  console.log(t("opera.status.contractVersion", { value: opera.contractVersion || t("locale.none") }));
+  console.log(t("opera.status.contractReadiness", { value: formatContractReadiness(opera.contractReadiness || "hypothesis") }));
+
+  if (bootstrapState) {
+    console.log(t("opera.status.bootstrap", { value: formatBootstrapStatus(bootstrapState.status) }));
+    if (bootstrapState.mode) {
+      console.log(t("opera.status.mode", { value: formatBootstrapMode(bootstrapState.mode) }));
+    }
+    if (bootstrapState.routeReason) {
+      console.log(t("opera.status.route", { value: formatBootstrapReason(bootstrapState.routeReason) }));
+    }
+    if (bootstrapState.decisionOwnership) {
+      console.log(t("opera.status.ownership", { value: formatDecisionOwnership(bootstrapState.decisionOwnership) }));
+    }
+    if ((bootstrapState.missingFields || []).length) {
+      console.log(t("opera.status.missing", { value: formatMissingFields(bootstrapState.missingFields) }));
+      if (bootstrapState.mode === "agent_handoff") {
+        console.log(t("opera.status.awaitingAgentExplanation"));
+        console.log(t("opera.status.awaitingAgentAction"));
+      } else {
+        console.log(t("opera.status.directExplanation"));
+        console.log(t("opera.status.directAction", {
+          intake: bootstrapState.intakeFiles?.json || bootstrap.bootstrapRelativePaths(context).intakeJson,
+          spec: bootstrapState.intakeFiles?.specDossier || bootstrap.bootstrapRelativePaths(context).specDossier,
+        }));
+      }
+      console.log(t("opera.status.contractNotGenerated"));
+      console.log(t("opera.status.resume"));
+    }
+    if (bootstrapState.mode === "agent_handoff" && relativePathExists(context, bootstrapState.handoffFiles?.markdown)) {
+      console.log(t("opera.status.handoff", { value: bootstrapState.handoffFiles.markdown }));
+    }
+    if (relativePathExists(context, bootstrapState.intakeFiles?.json)) {
+      console.log(t("opera.status.intake", { value: bootstrapState.intakeFiles.json }));
+    }
+    if (relativePathExists(context, bootstrapState.intakeFiles?.specDossier)) {
+      console.log(t("opera.status.specDossier", { value: bootstrapState.intakeFiles.specDossier }));
+    }
+    if (relativePathExists(context, bootstrapState.reviewFiles?.openQuestions)) {
+      console.log(t("opera.status.openQuestions", { value: bootstrapState.reviewFiles.openQuestions }));
+    }
+    if (relativePathExists(context, bootstrapState.reviewFiles?.qualityReport)) {
+      console.log(t("opera.status.qualityReport", { value: bootstrapState.reviewFiles.qualityReport }));
+    }
+  }
 
   const checks = [
     [context.layout === "split" ? "ops/.agent/hub/agent.md" : ".agent/hub/agent.md", fs.existsSync(path.join(context.paths.agentHubDir, "agent.md"))],
@@ -389,11 +507,11 @@ function status(root) {
     [context.layout === "split" ? "ops/policy/autonomy.json" : "policy/autonomy.json", fs.existsSync(context.paths.autonomyPolicyFile)],
   ];
 
-  console.log(t("opera.status.structure"));
-  for (const [file, exists] of checks) {
-    console.log(`    ${exists ? "\u2705" : "\u274C"} ${file}`);
-  }
-}
+  console.log(t("opera.status.structure"));
+  for (const [file, exists] of checks) {
+    console.log(`    ${fmt.boolToken(exists)} ${file}`);
+  }
+}
 
 function configure(root, args) {
   const context = config.ensureContext(root);
@@ -467,10 +585,13 @@ function upgrade(root, args = []) {
     removePath(context.paths.bootstrapDir);
   }
 
-  installStructure(context, control, locale, { rewriteLocalizedTemplates: true });
-  control.meta.opera = {
-    ...(control.meta.opera || {}),
-    installed: true,
+  installStructure(context, control, locale, { rewriteLocalizedTemplates: true });
+  require("./quality").backfillBootstrapMetadata(context, control, {
+    persist: true,
+  });
+  control.meta.opera = {
+    ...(control.meta.opera || {}),
+    installed: true,
     model: "v3",
     stableTag: "stable",
     version: OPERA_VERSION,
@@ -574,33 +695,77 @@ async function cmdBootstrap(root, args) {
   return runBootstrap(root, options);
 }
 
-function cmdHandoff(root, args) {
+function cmdHandoff(root, args) {
   const context = config.ensureContext(root);
   const control = config.loadControl(context);
   const state = bootstrap.getBootstrapState(control, context) || bootstrap.detectLegacyBootstrap(context, control);
   if (!state) {
     throw new Error("OPERA bootstrap is not initialized.");
   }
-  const files = bootstrap.bootstrapFilePaths(context);
-  const printMode = (args || []).includes("--print");
-  const jsonMode = (args || []).includes("--json");
-  if (jsonMode) {
-    const payload = readText(files.json);
-    process.stdout.write(payload || "{}\n");
-    return;
-  }
+  const files = bootstrap.bootstrapFilePaths(context);
+  const printMode = (args || []).includes("--print");
+  const jsonMode = (args || []).includes("--json");
+  if (state.mode !== "agent_handoff") {
+    const payload = {
+      mode: state.mode,
+      status: state.status,
+      files: {
+        intakeJson: state.intakeFiles?.json || bootstrap.bootstrapRelativePaths(context).intakeJson,
+        specDossier: state.intakeFiles?.specDossier || bootstrap.bootstrapRelativePaths(context).specDossier,
+        openQuestions: state.reviewFiles?.openQuestions || bootstrap.bootstrapRelativePaths(context).openQuestions,
+        qualityReport: state.reviewFiles?.qualityReport || bootstrap.bootstrapRelativePaths(context).qualityReport,
+      },
+      nextStep: t("opera.handoff.directNext"),
+    };
+    if (jsonMode) {
+      process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+      return;
+    }
+    if (printMode) {
+      process.stdout.write([
+        `# ${t("opera.handoff.directTitle")}`,
+        "",
+        `- ${t("opera.handoff.directStatus")}: ${formatBootstrapStatus(state.status)}`,
+        `- ${t("opera.handoff.directIntake")}: ${payload.files.intakeJson}`,
+        `- ${t("opera.handoff.directSpec")}: ${payload.files.specDossier}`,
+        `- ${t("opera.handoff.directQuestions")}: ${payload.files.openQuestions}`,
+        `- ${t("opera.handoff.directQuality")}: ${payload.files.qualityReport}`,
+        "",
+        t("opera.handoff.directNext"),
+        "",
+      ].join("\n"));
+      return;
+    }
+    console.log(t("opera.handoff.directSummary", { status: formatBootstrapStatus(state.status) }));
+    console.log(t("opera.status.intake", { value: payload.files.intakeJson }));
+    console.log(t("opera.status.specDossier", { value: payload.files.specDossier }));
+    if (relativePathExists(context, payload.files.openQuestions)) {
+      console.log(t("opera.status.openQuestions", { value: payload.files.openQuestions }));
+    }
+    if (relativePathExists(context, payload.files.qualityReport)) {
+      console.log(t("opera.status.qualityReport", { value: payload.files.qualityReport }));
+    }
+    console.log(t("opera.status.resume"));
+    console.log(t("opera.handoff.directNext"));
+    return;
+  }
+  if (jsonMode) {
+    const payload = readText(files.json);
+    process.stdout.write(payload || "{}\n");
+    return;
+  }
   if (printMode) {
     process.stdout.write(readText(files.markdown) || "");
     return;
   }
-  console.log(`Bootstrap: ${state.status}`);
-  console.log(`Mode: ${state.mode}`);
-  console.log(`Markdown handoff: ${state.handoffFiles?.markdown || bootstrap.bootstrapRelativePaths(context).markdown}`);
-  console.log(`JSON handoff: ${state.handoffFiles?.json || bootstrap.bootstrapRelativePaths(context).json}`);
-  if (state.reviewFiles?.openQuestions) {
-    console.log(`Open questions: ${state.reviewFiles.openQuestions}`);
-  }
-}
+  console.log(t("opera.handoff.summary", { status: formatBootstrapStatus(state.status) }));
+  console.log(t("opera.handoff.mode", { mode: formatBootstrapMode(state.mode) }));
+  console.log(t("opera.handoff.markdown", { value: state.handoffFiles?.markdown || bootstrap.bootstrapRelativePaths(context).markdown }));
+  console.log(t("opera.handoff.json", { value: state.handoffFiles?.json || bootstrap.bootstrapRelativePaths(context).json }));
+  if (relativePathExists(context, state.reviewFiles?.openQuestions)) {
+    console.log(t("opera.status.openQuestions", { value: state.reviewFiles.openQuestions }));
+  }
+}
 
 module.exports = {
   installStructure,