avorelo 0.1.0

package/scripts/lib/orchestration/state.js

@@ -0,0 +1,165 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { ensureCcoDirs } = require("../fsx");
+
+const ORCHESTRATION_ROOT = path.join(".claude", "cco", "orchestration");
+
+function rootPath(cwd, ...parts) {
+  return path.join(cwd, ORCHESTRATION_ROOT, ...parts);
+}
+
+function ensureOrchestrationDirs(cwd) {
+  ensureCcoDirs(cwd);
+  [
+    rootPath(cwd),
+    rootPath(cwd, "runs"),
+    rootPath(cwd, "handoffs"),
+    rootPath(cwd, "host-contracts"),
+  ].forEach((dir) => fs.mkdirSync(dir, { recursive: true }));
+}
+
+function safeReadJson(absPath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, ""));
+  } catch {
+    return fallback;
+  }
+}
+
+function safeReadJsonRel(cwd, relPath, fallback = null) {
+  return safeReadJson(path.join(cwd, relPath), fallback);
+}
+
+function writeJson(absPath, value) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(value, null, 2), "utf8");
+}
+
+function writeText(absPath, value) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, String(value || ""), "utf8");
+}
+
+function relativeFromCwd(cwd, absPath) {
+  return path.relative(cwd, absPath).replace(/\\/g, "/");
+}
+
+function createRunId() {
+  return `orch-${Date.now()}-${crypto.randomBytes(3).toString("hex")}`;
+}
+
+function getCurrentPaths(cwd) {
+  ensureOrchestrationDirs(cwd);
+  return {
+    root: rootPath(cwd),
+    inventory: rootPath(cwd, "inventory.json"),
+    inventoryRefreshLock: rootPath(cwd, "inventory-refresh.lock.json"),
+    workerFailures: rootPath(cwd, "worker-failures.json"),
+    currentTask: rootPath(cwd, "current-task.md"),
+    currentRouteJson: rootPath(cwd, "current-route.json"),
+    currentRouteMd: rootPath(cwd, "current-route.md"),
+    currentProofJson: rootPath(cwd, "current-proof.json"),
+    currentProofMd: rootPath(cwd, "current-proof.md"),
+    lock: rootPath(cwd, "run.lock.json"),
+    hostContractsDir: rootPath(cwd, "host-contracts"),
+  };
+}
+
+function getRunPaths(cwd, runId) {
+  ensureOrchestrationDirs(cwd);
+  const dir = rootPath(cwd, "runs", runId);
+  return {
+    dir,
+    task: path.join(dir, "task.json"),
+    route: path.join(dir, "route.json"),
+    executionLog: path.join(dir, "execution-log.jsonl"),
+    diffSummary: path.join(dir, "diff-summary.md"),
+    verification: path.join(dir, "verification.json"),
+    proof: path.join(dir, "proof.json"),
+  };
+}
+
+function appendJsonl(absPath, entry) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.appendFileSync(absPath, `${JSON.stringify(entry)}\n`, "utf8");
+}
+
+function readLatestRunProofs(cwd, limit = 20) {
+  const runsDir = rootPath(cwd, "runs");
+  try {
+    return fs.readdirSync(runsDir)
+      .map((name) => {
+        const proofPath = path.join(runsDir, name, "proof.json");
+        const stat = fs.existsSync(proofPath) ? fs.statSync(proofPath) : null;
+        if (!stat) return null;
+        return {
+          name,
+          proofPath,
+          mtimeMs: stat.mtimeMs,
+          proof: safeReadJson(proofPath, null),
+        };
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.mtimeMs - a.mtimeMs)
+      .slice(0, limit);
+  } catch {
+    return [];
+  }
+}
+
+function tryAcquireRunLock(cwd, metadata = {}, options = {}) {
+  const paths = getCurrentPaths(cwd);
+  const now = new Date();
+  const timeoutMs = Math.max(60_000, Number(options.timeoutMs || 20 * 60 * 1000));
+  const existing = safeReadJson(paths.lock, null);
+  if (existing && existing.acquiredAt) {
+    const ageMs = now.getTime() - Date.parse(existing.acquiredAt);
+    if (Number.isFinite(ageMs) && ageMs < timeoutMs) {
+      return {
+        ok: false,
+        reason: "concurrent_run_active",
+        lock: existing,
+      };
+    }
+  }
+
+  const lock = {
+    lockVersion: 1,
+    runId: metadata.runId || createRunId(),
+    acquiredAt: now.toISOString(),
+    task: metadata.task || null,
+    surface: metadata.surface || null,
+  };
+  writeJson(paths.lock, lock);
+  return { ok: true, lock };
+}
+
+function releaseRunLock(cwd, runId) {
+  const paths = getCurrentPaths(cwd);
+  const current = safeReadJson(paths.lock, null);
+  if (!current) return;
+  if (runId && current.runId && current.runId !== runId) return;
+  try {
+    fs.unlinkSync(paths.lock);
+  } catch {}
+}
+
+module.exports = {
+  ORCHESTRATION_ROOT,
+  ensureOrchestrationDirs,
+  safeReadJson,
+  safeReadJsonRel,
+  writeJson,
+  writeText,
+  relativeFromCwd,
+  createRunId,
+  getCurrentPaths,
+  getRunPaths,
+  appendJsonl,
+  readLatestRunProofs,
+  tryAcquireRunLock,
+  releaseRunLock,
+};

package/scripts/lib/orchestration/verification-manager.js

@@ -0,0 +1,138 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function safeReadPackageJson(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function defaultRunner(command, args, options = {}) {
+  return spawnSync(command, args, {
+    cwd: options.cwd,
+    env: options.env || process.env,
+    encoding: "utf8",
+    timeout: options.timeoutMs || 30_000,
+  });
+}
+
+function inferVerificationCommands(cwd, taskContext) {
+  const pkg = safeReadPackageJson(cwd);
+  const scripts = pkg.scripts || {};
+  const commands = [
+    {
+      id: "git_diff",
+      command: "git",
+      args: ["diff", "--stat", "--no-ext-diff"],
+      required: true,
+      purpose: "diff",
+    },
+  ];
+
+  if (taskContext.classification.taskType === "docs" && taskContext.classification.risk === "low") {
+    return commands;
+  }
+
+  if (typeof scripts.test === "string") {
+    commands.push({
+      id: "npm_test",
+      command: "npm",
+      args: ["test"],
+      required: false,
+      purpose: "tests",
+    });
+  }
+
+  if (typeof scripts.build === "string" && ["implementation", "ui", "cli", "build"].includes(taskContext.classification.taskType)) {
+    commands.push({
+      id: "npm_build",
+      command: "npm",
+      args: ["run", "build"],
+      required: false,
+      purpose: "build",
+    });
+  }
+
+  if (typeof scripts["test:brand"] === "string") {
+    commands.push({
+      id: "npm_test_brand",
+      command: "npm",
+      args: ["run", "test:brand"],
+      required: false,
+      purpose: "brand",
+    });
+  }
+
+  return commands;
+}
+
+function summarizeCommand(result) {
+  return {
+    status: result.status,
+    stdout: String(result.stdout || "").slice(0, 4000),
+    stderr: String(result.stderr || "").slice(0, 4000),
+  };
+}
+
+function verifyWorkspace(cwd, taskContext, options = {}) {
+  const commands = options.commands || inferVerificationCommands(cwd, taskContext);
+  if (!commands.length) {
+    return {
+      status: "insufficient",
+      commands: [],
+      reason: "No deterministic verification commands were inferred.",
+    };
+  }
+
+  const runner = options.commandRunner || defaultRunner;
+  const results = [];
+  let failures = 0;
+  let ranMeaningfulCheck = false;
+
+  commands.forEach((entry) => {
+    const outcome = runner(entry.command, entry.args, {
+      cwd,
+      env: options.env || process.env,
+      timeoutMs: options.timeoutMs || 30_000,
+    });
+    const summarized = summarizeCommand(outcome);
+    results.push({
+      ...entry,
+      ...summarized,
+    });
+    if (entry.id !== "git_diff") ranMeaningfulCheck = true;
+    if (Number(outcome.status) !== 0 && entry.id !== "git_diff") failures += 1;
+  });
+
+  if (failures > 0) {
+    return {
+      status: "failed",
+      commands: results,
+      reason: "One or more deterministic verification commands failed.",
+    };
+  }
+
+  if (!ranMeaningfulCheck) {
+    return {
+      status: "insufficient",
+      commands: results,
+      reason: "Only diff-level verification was available.",
+    };
+  }
+
+  return {
+    status: "passed",
+    commands: results,
+    reason: "Deterministic verification commands passed.",
+  };
+}
+
+module.exports = {
+  inferVerificationCommands,
+  verifyWorkspace,
+};

package/scripts/lib/output-profiles.js

@@ -0,0 +1,146 @@
+"use strict";
+
+/**
+ * CJS bridge for Avorelo output profiles.
+ *
+ * Mirrors src/output_profiles/ (the canonical TS module).
+ * Used by hook scripts which are CJS and cannot import TS directly.
+ *
+ * If you change rendering logic, update src/output_profiles/renderers.ts
+ * and this file together. The integration test verifies parity.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const VALID_PROFILES = ["terse", "standard", "deep"];
+
+function resolveOutputProfile(envValue) {
+  if (!envValue) return "standard";
+  const normalized = String(envValue).trim().toLowerCase();
+  if (VALID_PROFILES.includes(normalized)) return normalized;
+  return "standard";
+}
+
+function renderSessionBrief({ toolDisplayName, projectPath, nativeGuidanceSurfaces, profile, continuity, carryForwardAvailable }) {
+  // Only show continuity re-entry if carry-forward is NOT available
+  // Carry-forward provides more specific context (tool history, age, etc.)
+  const showContinuityReEntry = continuity?.hasPriorSession && !carryForwardAvailable;
+  const reEntryInfo = showContinuityReEntry ? ` (Session re-entry #${continuity.reEntryCount + 1})` : "";
+
+  if (profile === "terse") {
+    return [
+      `# Avorelo Active — ${toolDisplayName}${reEntryInfo}`,
+      "",
+      `- Project: \`${projectPath}\``,
+      `- Surfaces: ${nativeGuidanceSurfaces.join(", ")}`,
+    ].join("\n");
+  }
+
+  const reEntrySection = showContinuityReEntry ? [
+    "",
+    `> **Re-entry session** — Continuing work from earlier session. Run \`avorelo status\` to see progress and next best action.`
+  ] : [];
+
+  return [
+    `# Avorelo Is Active In This ${toolDisplayName} Session${reEntryInfo}`,
+    "",
+    `- Project path: \`${projectPath}\``,
+    `- Avorelo adds: launch context, tool-specific project guidance, beta-pack defaults, and starter guidance`,
+    `- Native guidance surfaces: ${nativeGuidanceSurfaces.join(", ")}`,
+    "- Avorelo does not keep a hidden background runtime after launch",
+    "- First move: start working in the active repo without re-explaining the Avorelo project truth",
+    ...reEntrySection,
+  ].join("\n");
+}
+
+function renderKickoffPrompt({ toolDisplayName, projectPath, nativeGuidanceSurfaces, profile }) {
+  if (profile === "terse") {
+    return [
+      `Avorelo active. ${toolDisplayName}, project: ${projectPath}.`,
+      `Prepared: ${nativeGuidanceSurfaces.join(", ")}.`,
+      "Start with one concrete first move. Ask what to do first.",
+    ].join("\n");
+  }
+
+  return [
+    `Avorelo is active for this ${toolDisplayName} session.`,
+    `Project path: ${projectPath}.`,
+    `Avorelo prepared the project context, ${nativeGuidanceSurfaces.join(", ")}, the Avorelo beta-pack defaults, and this kickoff prompt.`,
+    "Avorelo is not a hidden background runtime after launch.",
+    "Please start with a short founder handoff that says what Avorelo prepared, suggests one concrete first move in this repo, and ends with one short question asking what they want to do first.",
+  ].join("\n");
+}
+
+function renderBannerLines({ projectPath, sessionBriefPath, profile }) {
+  if (profile === "terse") {
+    return [
+      "",
+      `Avorelo active. Project: ${projectPath}`,
+      "",
+    ];
+  }
+
+  return [
+    "",
+    "Avorelo is active for this session.",
+    `Project path: ${projectPath}`,
+    "Avorelo added: launcher + project context + starter guidance",
+    "Avorelo is not running silently in the background after launch.",
+    "Start with the Avorelo kickoff already loaded below.",
+    ...(sessionBriefPath ? [`Session brief: ${sessionBriefPath}`] : []),
+    "",
+  ];
+}
+
+function renderSystemPromptProfilePolicy(profile) {
+  if (profile === "standard") return "";
+
+  if (profile === "terse") {
+    return [
+      "",
+      "Output profile: terse. Reduce filler phrasing and redundant recaps.",
+      "Preserve verbatim: code blocks, shell commands, file paths, URLs, IDs, dates, versions, env vars, canonical fields, blocked reasons, recovery steps, rollback instructions, evidence, uncertainty statements, safety warnings.",
+    ].join("\n");
+  }
+
+  return [
+    "",
+    "Output profile: deep. Provide full rationale, tradeoff analysis, and discovery context when relevant.",
+    "Preserve verbatim: code blocks, shell commands, file paths, URLs, IDs, dates, versions, env vars, canonical fields, blocked reasons, recovery steps, rollback instructions, evidence, uncertainty statements, safety warnings.",
+  ].join("\n");
+}
+
+const TELEMETRY_DIR = path.join(os.homedir(), ".wuz", "runtime", "telemetry");
+const TELEMETRY_FILE = path.join(TELEMETRY_DIR, "output-profile.log");
+
+function writeProfileTelemetry(record) {
+  try {
+    fs.mkdirSync(TELEMETRY_DIR, { recursive: true });
+    fs.appendFileSync(TELEMETRY_FILE, JSON.stringify(record) + "\n", "utf8");
+  } catch {
+    // Best-effort only. Never block launch.
+  }
+}
+
+function buildTelemetryRecord({ profile, surface, inputText, outputText }) {
+  return {
+    ts: new Date().toISOString(),
+    profile,
+    surface,
+    bytes_in: Buffer.byteLength(inputText, "utf8"),
+    bytes_out: Buffer.byteLength(outputText, "utf8"),
+  };
+}
+
+module.exports = {
+  VALID_PROFILES,
+  resolveOutputProfile,
+  renderSessionBrief,
+  renderKickoffPrompt,
+  renderBannerLines,
+  renderSystemPromptProfilePolicy,
+  writeProfileTelemetry,
+  buildTelemetryRecord,
+};