avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/activation/repair-engine.js

@@ -0,0 +1,219 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  ensureCcoDirs,
+  ensureProjectConfig,
+  safeReadJson,
+  safeWriteJson,
+  nowIso,
+} = require("../fsx");
+const { attemptAutoRecovery } = require("../upgrade-interruption-recovery");
+
+const CONTEXT_PACK_REL = ".claude/cco/state/context-pack.json";
+const ONBOARDING_REL = ".claude/cco/state/onboarding.json";
+
+function buildDefaultOnboardingState() {
+  return {
+    status: "completed",
+    createdAt: nowIso(),
+    completedAt: nowIso(),
+    stepsCompleted: ["activation"],
+    hasSeenDashboard: false,
+    hasSeenStatus: true,
+    hasCompletedSession: false,
+  };
+}
+
+function buildContextPack(cwd, context) {
+  return {
+    version: 1,
+    generatedAt: nowIso(),
+    project: {
+      cwd: context.project.cwd,
+      gitDetected: context.project.gitDetected,
+      repoRoot: context.project.repoRoot,
+      packageJsonDetected: context.project.packageJsonDetected,
+    },
+    commands: {
+      status: "avorelo status --text",
+      audit: "avorelo audit",
+      activate: "npx avorelo@latest activate",
+    },
+    hosts: (context.detectedHosts || [])
+      .filter((host) => host.detected)
+      .map((host) => ({
+        id: host.id,
+        label: host.label,
+        depth: host.depth,
+      })),
+  };
+}
+
+function localFilesReady(cwd) {
+  return (
+    fs.existsSync(path.join(cwd, ".claude", "cco", "config.json")) &&
+    fs.existsSync(path.join(cwd, ".claude", "cco", "state", "onboarding.json")) &&
+    fs.existsSync(path.join(cwd, ".claude", "cco", "state", "context-pack.json"))
+  );
+}
+
+function runRepairEngine(cwd, context, options = {}) {
+  const repairEnabled = options.repair !== false;
+  const repairsAttempted = [];
+  const manualFixesRequired = [];
+  const issues = [];
+  let localSetupReady = false;
+
+  if (!context.environment.nodeDetected) {
+    issues.push({ id: "node_missing", classification: "blocking", reason: "Node.js is required to run Avorelo." });
+    manualFixesRequired.push({
+      id: "install_node",
+      label: "Install Node.js",
+      command: "https://nodejs.org/",
+      reason: "Avorelo activation requires Node.js in PATH.",
+      blocking: true,
+    });
+  }
+
+  if (!context.environment.npmDetected) {
+    issues.push({ id: "npm_missing", classification: "blocking", reason: "npm is required for the activation entrypoint." });
+    manualFixesRequired.push({
+      id: "install_npm",
+      label: "Restore npm in PATH",
+      command: null,
+      reason: "Avorelo activation uses npm/npx for the primary install and verification path.",
+      blocking: true,
+    });
+  }
+
+  if (repairEnabled && manualFixesRequired.every((fix) => !fix.blocking)) {
+    try {
+      ensureCcoDirs(cwd);
+      repairsAttempted.push({
+        id: "ensure_cco_dirs",
+        status: "applied",
+        reason: "Prepared local Avorelo directories.",
+      });
+    } catch (error) {
+      manualFixesRequired.push({
+        id: "fix_local_write_access",
+        label: "Restore local write access",
+        command: null,
+        reason: `Avorelo could not create project-local state: ${error.message}`,
+        blocking: true,
+      });
+      issues.push({ id: "write_access", classification: "blocking", reason: error.message });
+    }
+  }
+
+  if (repairEnabled && manualFixesRequired.every((fix) => !fix.blocking)) {
+    ensureProjectConfig(cwd);
+    repairsAttempted.push({
+      id: "ensure_project_config",
+      status: "applied",
+      reason: "Normalized project-local Avorelo config.",
+    });
+
+    const originalConsoleError = console.error;
+    let recovery;
+    try {
+      console.error = () => {};
+      recovery = attemptAutoRecovery(cwd);
+    } finally {
+      console.error = originalConsoleError;
+    }
+    if (recovery.success) {
+      repairsAttempted.push({
+        id: "upgrade_marker_repair",
+        status: "applied",
+        reason: recovery.recoveryType,
+      });
+    }
+
+    if (!safeReadJson(cwd, ONBOARDING_REL, null)) {
+      safeWriteJson(cwd, ONBOARDING_REL, buildDefaultOnboardingState());
+      repairsAttempted.push({
+        id: "create_onboarding_state",
+        status: "applied",
+        reason: "Created onboarding state for activation.",
+      });
+    }
+  } else if (!repairEnabled && !safeReadJson(cwd, ONBOARDING_REL, null)) {
+    issues.push({ id: "missing_onboarding_state", classification: "recoverable", reason: "Onboarding state is missing." });
+    manualFixesRequired.push({
+      id: "run_activation_with_repair",
+      label: "Run activation with repair enabled",
+      command: "npx avorelo@latest activate --repair",
+      reason: "Avorelo can recreate missing local state automatically when repair is enabled.",
+      blocking: false,
+    });
+  }
+
+  if (repairEnabled && manualFixesRequired.every((fix) => !fix.blocking)) {
+    const contextPack = buildContextPack(cwd, context);
+    safeWriteJson(cwd, CONTEXT_PACK_REL, contextPack);
+    repairsAttempted.push({
+      id: "generate_context_pack",
+      status: "applied",
+      reason: "Generated a reusable local context pack.",
+    });
+  }
+
+  const hostConfiguration = [];
+  if (repairEnabled && Array.isArray(context.detectedHosts)) {
+    context.detectedHosts
+      .filter((host) => host.detected && host.canAutoConfigure && typeof host.configureIfSafe === "function")
+      .forEach((host) => {
+        try {
+          const result = host.configureIfSafe(cwd, { contextPackRel: CONTEXT_PACK_REL });
+          hostConfiguration.push({
+            id: host.id,
+            applied: result?.applied === true,
+            integrationId: result?.integrationId || null,
+          });
+          if (result?.applied) {
+            repairsAttempted.push({
+              id: `configure_${host.id}`,
+              status: "applied",
+              reason: `Prepared ${host.label} project-local artifacts.`,
+            });
+          }
+        } catch (error) {
+          issues.push({
+            id: `${host.id}_configure_failed`,
+            classification: "optional",
+            reason: error.message,
+          });
+        }
+      });
+  }
+
+  localSetupReady = manualFixesRequired.every((fix) => !fix.blocking) && localFilesReady(cwd);
+
+  if (!context.project.gitDetected) {
+    issues.push({
+      id: "git_repo_not_detected",
+      classification: "optional",
+      reason: "Git repo not detected. Avorelo still runs in local mode.",
+    });
+  }
+
+  return {
+    repairEnabled,
+    localSetupReady,
+    issues,
+    repairsAttempted,
+    manualFixesRequired,
+    hostConfiguration,
+    contextPackRel: CONTEXT_PACK_REL,
+  };
+}
+
+module.exports = {
+  CONTEXT_PACK_REL,
+  buildDefaultOnboardingState,
+  buildContextPack,
+  runRepairEngine,
+};

package/scripts/lib/activation/run-entry.js

@@ -0,0 +1,346 @@
+"use strict";
+
+// ── Activation Always-On Run Entry v1 ─────────────────────────────────────────
+//
+// Contract: avorelo.runEntry.v1
+//
+// Installs a durable, local-first "run entry" contract into a project when it is
+// activated, so future supported AI coding sessions know to start with Avorelo
+// (Session Collision Guard before edits/pushes, Workstream Preflight before new
+// work) without the user repeating those instructions every session.
+//
+// What it installs into the TARGET project (cwd):
+//   1. A marker-bracketed "Avorelo Run Entry" block in AGENTS.md (created if
+//      missing; the block is upserted in place; all user content outside the
+//      markers is preserved).
+//   2. A machine-readable contract record at
+//      .claude/cco/run-entry/run-entry.json (for verify/repair/idempotency).
+//   3. run-entry metadata on the canonical activation state
+//      .claude/cco/state/activation.json (runEntry.*).
+//
+// Honesty boundary: this makes Avorelo the default starting layer for SUPPORTED
+// local sessions that read project instruction files. It does NOT and cannot
+// force arbitrary external AI tools to obey unless they read these instructions
+// or run through an Avorelo entrypoint. No runtime enforcement is added here.
+//
+// Safety: only local files under the target project are written. No git
+// mutations, no push/merge, no deploy/publish, no package-lock writes, no hooks.
+
+const fs = require("fs");
+const path = require("path");
+const { safeReadJson, safeWriteJson, safeWriteText, nowIso } = require("../fsx");
+const {
+  ACTIVATION_STATE_REL,
+  readActivationState,
+  writeActivationState,
+} = require("./activation-state");
+
+const RUN_ENTRY_CONTRACT = "avorelo.runEntry.v1";
+const RUN_ENTRY_SCHEMA_VERSION = 1;
+const BLOCK_SCHEMA_VERSION = 1;
+
+const RUN_ENTRY_DIR_REL = ".claude/cco/run-entry";
+const RUN_ENTRY_CONTRACT_REL = `${RUN_ENTRY_DIR_REL}/run-entry.json`;
+const INSTRUCTION_SURFACE_REL = "AGENTS.md";
+
+const GUARD_SCRIPT_REL = "scripts/avorelo-session-collision-guard.js";
+const PREFLIGHT_SCRIPT_REL = "scripts/avorelo-workstream-preflight.js";
+
+const BLOCK_START = `<!-- AVORELO:RUN-ENTRY:START schemaVersion=${BLOCK_SCHEMA_VERSION} (managed by Avorelo; edit only outside these markers) -->`;
+const BLOCK_END = "<!-- AVORELO:RUN-ENTRY:END -->";
+// Version-agnostic matcher so an older managed block is detected and upgraded.
+const BLOCK_RE = /<!-- AVORELO:RUN-ENTRY:START[\s\S]*?<!-- AVORELO:RUN-ENTRY:END -->/;
+
+// The Avorelo installation root (where scripts/lib lives) — used only to read
+// the Avorelo package version, never written to.
+const AVORELO_ROOT = path.resolve(__dirname, "../../..");
+
+function readAvoreloVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(AVORELO_ROOT, "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+// ── Instruction block ─────────────────────────────────────────────────────────
+
+function buildInstructionBlock() {
+  return [
+    BLOCK_START,
+    "## Avorelo Run Entry (v1)",
+    "",
+    "This project is activated with Avorelo. Supported AI coding sessions should start here.",
+    "Avorelo manages the content between these markers; put your own notes outside them.",
+    "",
+    "1. Before editing files, run:",
+    "   `node scripts/avorelo-session-collision-guard.js`",
+    "2. If the result is not `safe_to_continue`, stop and report. Do not edit or push.",
+    "3. Before starting a new workstream, run:",
+    "   `node scripts/avorelo-workstream-preflight.js \"<workstream>\"`",
+    "4. If the shared clone is dirty, work in a clean isolated git worktree.",
+    "5. Do not push, force-push, or merge without explicit user approval.",
+    "6. Do not claim deploy / publish / production unless it actually happened.",
+    "7. Use Avorelo validators and dogfood artifacts for proof.",
+    "",
+    "Fail open when advisory data is missing; stop and report on dirty or collision risk.",
+    "Note: external tools that ignore project instructions may still need manual routing.",
+    "(If Avorelo is installed as a package, run the guard/preflight via the packaged scripts.)",
+    BLOCK_END,
+  ].join("\n");
+}
+
+// ── Guard / preflight availability (advisory) ─────────────────────────────────
+
+function detectScript(cwd, relPath) {
+  const local = path.join(cwd, relPath);
+  if (fs.existsSync(local)) return { available: true, path: relPath };
+  const packaged = path.join(cwd, "node_modules", "avorelo", relPath);
+  if (fs.existsSync(packaged)) return { available: true, path: `node_modules/avorelo/${relPath}` };
+  return { available: false, path: null };
+}
+
+function detectGuardPreflight(cwd) {
+  return {
+    guard: detectScript(cwd, GUARD_SCRIPT_REL),
+    preflight: detectScript(cwd, PREFLIGHT_SCRIPT_REL),
+  };
+}
+
+// ── Instruction surface upsert (preserves user content) ───────────────────────
+
+function safeReadText(absPath) {
+  try {
+    return fs.existsSync(absPath) ? fs.readFileSync(absPath, "utf8") : null;
+  } catch {
+    return null;
+  }
+}
+
+function upsertInstructionSurface(cwd) {
+  const absPath = path.join(cwd, INSTRUCTION_SURFACE_REL);
+  const desiredBlock = buildInstructionBlock();
+  const existing = safeReadText(absPath);
+
+  if (existing === null) {
+    const content = `# AGENTS\n\n${desiredBlock}\n`;
+    safeWriteText(cwd, INSTRUCTION_SURFACE_REL, content);
+    return { surface: INSTRUCTION_SURFACE_REL, action: "created" };
+  }
+
+  if (BLOCK_RE.test(existing)) {
+    const current = existing.match(BLOCK_RE)[0];
+    if (current === desiredBlock) {
+      return { surface: INSTRUCTION_SURFACE_REL, action: "unchanged" };
+    }
+    // Upgrade the managed block in place; everything else is preserved verbatim.
+    const updated = existing.replace(BLOCK_RE, desiredBlock);
+    safeWriteText(cwd, INSTRUCTION_SURFACE_REL, updated);
+    return { surface: INSTRUCTION_SURFACE_REL, action: "updated" };
+  }
+
+  // File exists but has no managed block: append it, preserving user content.
+  const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+  safeWriteText(cwd, INSTRUCTION_SURFACE_REL, `${existing}${sep}${desiredBlock}\n`);
+  return { surface: INSTRUCTION_SURFACE_REL, action: "installed" };
+}
+
+function instructionSurfaceHasBlock(cwd) {
+  const existing = safeReadText(path.join(cwd, INSTRUCTION_SURFACE_REL));
+  if (existing === null) return { exists: false, hasBlock: false, current: false };
+  const match = existing.match(BLOCK_RE);
+  return {
+    exists: true,
+    hasBlock: Boolean(match),
+    current: Boolean(match) && match[0] === buildInstructionBlock(),
+  };
+}
+
+// ── Contract record ───────────────────────────────────────────────────────────
+
+function writeContractRecord(cwd, availability) {
+  const existing = safeReadJson(cwd, RUN_ENTRY_CONTRACT_REL, null);
+  const installedAt = existing && existing.installedAt ? existing.installedAt : nowIso();
+
+  // Meaningful (timestamp-independent) content, used to decide if a write is needed
+  // so re-activation is truly idempotent and does not report a phantom repair.
+  const meaningful = {
+    schemaVersion: RUN_ENTRY_SCHEMA_VERSION,
+    contract: RUN_ENTRY_CONTRACT,
+    blockSchemaVersion: BLOCK_SCHEMA_VERSION,
+    instructionSurfaces: [INSTRUCTION_SURFACE_REL],
+    guardScript: GUARD_SCRIPT_REL,
+    preflightScript: PREFLIGHT_SCRIPT_REL,
+    guardAvailable: availability.guard.available,
+    preflightAvailable: availability.preflight.available,
+  };
+
+  if (existing) {
+    const existingMeaningful = {
+      schemaVersion: existing.schemaVersion,
+      contract: existing.contract,
+      blockSchemaVersion: existing.blockSchemaVersion,
+      instructionSurfaces: existing.instructionSurfaces,
+      guardScript: existing.guardScript,
+      preflightScript: existing.preflightScript,
+      guardAvailable: existing.guardAvailable,
+      preflightAvailable: existing.preflightAvailable,
+    };
+    if (JSON.stringify(existingMeaningful) === JSON.stringify(meaningful)) {
+      return { file: RUN_ENTRY_CONTRACT_REL, action: "unchanged", record: existing };
+    }
+  }
+
+  const record = { ...meaningful, contract: RUN_ENTRY_CONTRACT, installedAt, updatedAt: nowIso() };
+  const action = !existing
+    ? "created"
+    : existing.schemaVersion !== RUN_ENTRY_SCHEMA_VERSION
+      ? "upgraded"
+      : "updated";
+  safeWriteJson(cwd, RUN_ENTRY_CONTRACT_REL, record);
+  return { file: RUN_ENTRY_CONTRACT_REL, action, record };
+}
+
+// ── Activation state run-entry metadata ───────────────────────────────────────
+
+function updateActivationStateRunEntry(cwd, info) {
+  // Only annotate an existing state file; never fabricate full activation state
+  // here (that is owned by the activation flow). If no state exists yet, a
+  // minimal record is still written so verify/repair has something to read.
+  const state = readActivationState(cwd);
+  state.runEntry = {
+    installed: true,
+    schemaVersion: RUN_ENTRY_SCHEMA_VERSION,
+    installedAt: state.runEntry && state.runEntry.installedAt ? state.runEntry.installedAt : nowIso(),
+    updatedAt: nowIso(),
+    activationSource: info.activationSource || "unknown",
+    avoreloVersion: info.avoreloVersion || null,
+    installedRunEntryContract: true,
+    installedInstructionSurfaces: [INSTRUCTION_SURFACE_REL],
+    lastVerificationResult: info.lastVerificationResult || null,
+  };
+  state.updatedAt = nowIso();
+  writeActivationState(cwd, state);
+  return state.runEntry;
+}
+
+// ── Install / repair (idempotent) ─────────────────────────────────────────────
+
+function installRunEntry(cwd, options = {}) {
+  const availability = detectGuardPreflight(cwd);
+  const surface = upsertInstructionSurface(cwd);
+  const contract = writeContractRecord(cwd, availability);
+
+  const verification = verifyRunEntry(cwd, { availability });
+
+  const runEntryState = updateActivationStateRunEntry(cwd, {
+    activationSource: options.activationSource || "cli",
+    avoreloVersion: readAvoreloVersion(),
+    lastVerificationResult: verification.ok ? "pass" : "repaired",
+  });
+
+  // Classify per-file actions for a compact, honest summary.
+  const created = [];
+  const updated = [];
+  const unchanged = [];
+  for (const item of [surface, { surface: contract.file, action: contract.action }]) {
+    if (item.action === "created") created.push(item.surface);
+    else if (item.action === "installed" || item.action === "updated" || item.action === "upgraded") updated.push(item.surface);
+    else unchanged.push(item.surface);
+  }
+
+  return {
+    contract: RUN_ENTRY_CONTRACT,
+    schemaVersion: RUN_ENTRY_SCHEMA_VERSION,
+    installedInstructionSurfaces: [INSTRUCTION_SURFACE_REL],
+    contractPath: RUN_ENTRY_CONTRACT_REL,
+    created,
+    updated,
+    unchanged,
+    guardAvailable: availability.guard.available,
+    preflightAvailable: availability.preflight.available,
+    verification,
+    runEntryState,
+  };
+}
+
+// ── Verify ────────────────────────────────────────────────────────────────────
+//
+// Required local contract files: the instruction surface block + the contract
+// record. These fail/repair if missing. Guard/preflight availability is
+// ADVISORY (fail open) because a package-installed project may expose them at a
+// different path or not at all.
+
+function verifyRunEntry(cwd, options = {}) {
+  const availability = options.availability || detectGuardPreflight(cwd);
+  const surfaceState = instructionSurfaceHasBlock(cwd);
+  const contractExists = safeReadJson(cwd, RUN_ENTRY_CONTRACT_REL, null) !== null;
+  const stateExists = fs.existsSync(path.join(cwd, ACTIVATION_STATE_REL));
+
+  const checks = {
+    activationStateExists: stateExists,
+    runEntryContractExists: contractExists,
+    instructionSurfaceExists: surfaceState.exists,
+    instructionSurfaceHasBlock: surfaceState.hasBlock,
+    instructionSurfaceCurrent: surfaceState.current,
+    guardAvailable: availability.guard.available, // advisory
+    preflightAvailable: availability.preflight.available, // advisory
+  };
+
+  // Only required local contract files gate ok; advisory availability does not.
+  const missingRequired = [];
+  if (!checks.runEntryContractExists) missingRequired.push(RUN_ENTRY_CONTRACT_REL);
+  if (!checks.instructionSurfaceHasBlock) missingRequired.push(`${INSTRUCTION_SURFACE_REL} (run-entry block)`);
+
+  const advisory = [];
+  if (!checks.guardAvailable) advisory.push(GUARD_SCRIPT_REL);
+  if (!checks.preflightAvailable) advisory.push(PREFLIGHT_SCRIPT_REL);
+
+  return {
+    ok: missingRequired.length === 0,
+    checks,
+    missingRequired,
+    advisoryMissing: advisory,
+    repairCommand: "npx avorelo@latest activate",
+  };
+}
+
+// ── Compact summary line(s) for activation output ─────────────────────────────
+
+function formatRunEntrySummary(result) {
+  const lines = [];
+  lines.push("Run entry:");
+  lines.push(`  + Instruction surface: ${result.installedInstructionSurfaces.join(", ")}`);
+  lines.push(`  + Contract: ${result.contractPath}`);
+  const changed = [...result.created, ...result.updated];
+  if (changed.length) {
+    lines.push(`  + Installed/repaired: ${changed.join(", ")}`);
+  } else {
+    lines.push("  + Already up to date (idempotent)");
+  }
+  lines.push(`  + Session Collision Guard available: ${result.guardAvailable ? "yes" : "no (advisory)"}`);
+  lines.push(`  + Workstream Preflight available: ${result.preflightAvailable ? "yes" : "no (advisory)"}`);
+  return lines.join("\n");
+}
+
+module.exports = {
+  RUN_ENTRY_CONTRACT,
+  RUN_ENTRY_SCHEMA_VERSION,
+  BLOCK_SCHEMA_VERSION,
+  RUN_ENTRY_DIR_REL,
+  RUN_ENTRY_CONTRACT_REL,
+  INSTRUCTION_SURFACE_REL,
+  GUARD_SCRIPT_REL,
+  PREFLIGHT_SCRIPT_REL,
+  BLOCK_START,
+  BLOCK_END,
+  buildInstructionBlock,
+  detectGuardPreflight,
+  upsertInstructionSurface,
+  instructionSurfaceHasBlock,
+  writeContractRecord,
+  installRunEntry,
+  verifyRunEntry,
+  formatRunEntrySummary,
+};