avorelo 0.1.0

package/scripts/lib/hook-baseline.js

@@ -0,0 +1,310 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const CONTRACT = "avorelo.hookBaseline.v1";
+const SCHEMA_VERSION = 1;
+
+const BASELINE_DIR_REL = ".claude/cco/orchestration/hook-baseline";
+const LATEST_BASELINE_REL = `${BASELINE_DIR_REL}/latest-baseline.json`;
+
+const LIFECYCLE_EVENTS = Object.freeze([
+  "SessionStart",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PostToolUse",
+  "Stop",
+  "SessionEnd",
+]);
+
+// Blocking: PreToolUse (guard/packet enforcement), Stop (proof gate)
+// UserPromptSubmit: blocking only when prohibited/destructive intent detected
+// SessionStart, PostToolUse, SessionEnd: non-blocking
+const BLOCKING_EVENTS = Object.freeze(["PreToolUse", "Stop"]);
+const CONDITIONALLY_BLOCKING_EVENTS = Object.freeze(["UserPromptSubmit"]);
+const NON_BLOCKING_EVENTS = Object.freeze(["SessionStart", "PostToolUse", "SessionEnd"]);
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function safeWriteJson(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function getBaselineHookDefinitions() {
+  return [
+    {
+      hookId: "session-start",
+      event: "SessionStart",
+      blocking: false,
+      purpose: "Prepare project/workspace state for the session. Load project profile, run workspace hygiene summary, and prepare run/session state.",
+      defaultMode: "automatic",
+      capabilities: [
+        "ai_coding_readiness",
+        "ai_workspace_hygiene_basic",
+        "project_profile_basic",
+      ],
+      inputs: ["cwd", "session_context"],
+      outputs: ["session_state", "profile_summary", "workspace_status"],
+      command: "node bin/avorelo lifecycle-hook session-start --json",
+      writesLedger: true,
+      writesProof: false,
+      customerVisible: false,
+      debugVisible: true,
+      safeDefault: true,
+      reasonCodes: [
+        "NON_BLOCKING_PHASE",
+        "SESSION_STATE_PREPARATION",
+        "PROFILE_LOADED",
+      ],
+      redacted: true,
+    },
+    {
+      hookId: "user-prompt-submit",
+      event: "UserPromptSubmit",
+      blocking: false,
+      blockingCondition: "Blocking only when prompt explicitly asks for prohibited/destructive/secrets/deploy/prod action.",
+      purpose: "Classify the task, prepare/update execution packet, smart-route, and build a safe run plan. Non-blocking by default; blocking if the prompt is prohibited.",
+      defaultMode: "automatic",
+      capabilities: [
+        "smart_route_hook_binding_basic",
+        "execution_packet_hook_binding_basic",
+        "safe_run_hook_binding_basic",
+        "hook_baseline_registry_basic",
+      ],
+      inputs: ["prompt_text", "session_context", "cwd"],
+      outputs: ["execution_packet", "safe_run_plan", "route_decision", "blocking_decision"],
+      command: "node bin/avorelo lifecycle-hook user-prompt-submit --json",
+      writesLedger: true,
+      writesProof: false,
+      customerVisible: false,
+      debugVisible: true,
+      safeDefault: true,
+      reasonCodes: [
+        "TASK_CLASSIFICATION",
+        "EXECUTION_PACKET_PREPARED",
+        "SMART_ROUTE_DECIDED",
+        "SAFE_RUN_PLAN_BUILT",
+        "BLOCKING_ONLY_FOR_PROHIBITED_PROMPTS",
+      ],
+      redacted: true,
+    },
+    {
+      hookId: "pre-tool-use",
+      event: "PreToolUse",
+      blocking: true,
+      purpose: "Enforce packet boundaries, run guard/safe-path for tool/action/target. Block destructive/secrets/deploy/prod actions. Return structured decision: allow|warn|approval_required|block.",
+      defaultMode: "automatic",
+      capabilities: [
+        "pre_tool_use_guard_mapping_basic",
+        "execution_packet_hook_binding_basic",
+        "safe_run_hook_binding_basic",
+      ],
+      inputs: ["tool_name", "tool_input", "execution_packet", "cwd"],
+      outputs: ["decision", "safeNextAction", "reasonCodes", "ledger_receipt"],
+      command: "node bin/avorelo lifecycle-hook pre-tool-use --json",
+      writesLedger: true,
+      writesProof: false,
+      customerVisible: false,
+      debugVisible: true,
+      safeDefault: true,
+      reasonCodes: [
+        "BLOCKING_HOOK",
+        "PACKET_BOUNDARY_ENFORCED",
+        "GUARD_SAFE_PATH_APPLIED",
+        "DESTRUCTIVE_BLOCKED",
+        "SECRETS_BLOCKED",
+        "DEPLOY_PROD_BLOCKED",
+      ],
+      redacted: true,
+    },
+    {
+      hookId: "post-tool-use",
+      event: "PostToolUse",
+      blocking: false,
+      purpose: "Record tool/action result summary, write ledger entry and product-learning event. No raw output dump.",
+      defaultMode: "automatic",
+      capabilities: [
+        "post_tool_use_ledger_mapping_basic",
+      ],
+      inputs: ["tool_name", "tool_result_summary", "execution_packet", "cwd"],
+      outputs: ["ledger_entry", "product_learning_event"],
+      command: "node bin/avorelo lifecycle-hook post-tool-use --json",
+      writesLedger: true,
+      writesProof: false,
+      customerVisible: false,
+      debugVisible: true,
+      safeDefault: true,
+      reasonCodes: [
+        "NON_BLOCKING_PHASE",
+        "LEDGER_UPDATED",
+        "PRODUCT_LEARNING_RECORDED",
+        "NO_RAW_OUTPUT_DUMP",
+      ],
+      redacted: true,
+    },
+    {
+      hookId: "stop",
+      event: "Stop",
+      blocking: true,
+      purpose: "Check whether proof is required from execution packet/safe-run. If proof required and missing, block and require continuation. If proof exists or not required, allow.",
+      defaultMode: "automatic",
+      capabilities: [
+        "stop_proof_gate_mapping_basic",
+      ],
+      inputs: ["execution_packet", "safe_run_result", "cwd"],
+      outputs: ["proof_status", "blocking_decision", "safeNextAction"],
+      command: "node bin/avorelo lifecycle-hook stop --json",
+      writesLedger: true,
+      writesProof: true,
+      customerVisible: false,
+      debugVisible: true,
+      safeDefault: true,
+      reasonCodes: [
+        "BLOCKING_HOOK",
+        "PROOF_GATE_APPLIED",
+        "PROOF_REQUIRED_IF_CODE_CHANGE",
+        "SAFE_NEXT_ACTION_PROVIDED",
+      ],
+      redacted: true,
+    },
+    {
+      hookId: "session-end",
+      event: "SessionEnd",
+      blocking: false,
+      purpose: "Run outcome summary, update ledger, run company-loop, prepare handoff summary. Non-blocking. Compact output.",
+      defaultMode: "automatic",
+      capabilities: [
+        "session_end_summary_handoff_mapping_basic",
+      ],
+      inputs: ["session_context", "ledger_state", "cwd"],
+      outputs: ["outcome_summary", "ledger_update", "company_loop_update", "handoff_summary"],
+      command: "node bin/avorelo lifecycle-hook session-end --json",
+      writesLedger: true,
+      writesProof: false,
+      customerVisible: false,
+      debugVisible: true,
+      safeDefault: true,
+      reasonCodes: [
+        "NON_BLOCKING_PHASE",
+        "OUTCOME_WRITTEN",
+        "LEDGER_UPDATED",
+        "COMPANY_LOOP_UPDATED",
+        "HANDOFF_PREPARED",
+      ],
+      redacted: true,
+    },
+  ];
+}
+
+function buildHookBindingMap(cwd, options = {}) {
+  const defs = getBaselineHookDefinitions();
+  const map = {};
+  for (const def of defs) {
+    map[def.event] = {
+      hookId: def.hookId,
+      blocking: def.blocking,
+      blockingCondition: def.blockingCondition || null,
+      command: def.command,
+      capabilities: def.capabilities,
+      writesLedger: def.writesLedger,
+      writesProof: def.writesProof,
+      safeDefault: def.safeDefault,
+      reasonCodes: def.reasonCodes,
+      redacted: true,
+    };
+  }
+  return map;
+}
+
+function buildHookBaseline(cwd, options = {}) {
+  const defs = getBaselineHookDefinitions();
+  const bindingMap = buildHookBindingMap(cwd, options);
+
+  const blockingEvents = defs.filter((d) => d.blocking).map((d) => d.event);
+  const nonBlockingEvents = defs.filter((d) => !d.blocking).map((d) => d.event);
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status: "ready",
+    hookCount: defs.length,
+    eventsRegistered: LIFECYCLE_EVENTS.slice(),
+    blockingEvents,
+    nonBlockingEvents,
+    conditionallyBlockingEvents: CONDITIONALLY_BLOCKING_EVENTS.slice(),
+    hooks: defs,
+    bindingMap,
+    installStatus: "preview_only",
+    installNote: "No user config has been modified. Hooks are preview/readiness only. Apply requires explicit user approval.",
+    approvalRequiredBeforeApply: true,
+    redacted: true,
+  };
+}
+
+function writeHookBaseline(cwd, baseline) {
+  const absPath = path.join(cwd, LATEST_BASELINE_REL);
+  ensureDir(path.dirname(absPath));
+  safeWriteJson(absPath, baseline);
+  return { path: LATEST_BASELINE_REL, written: true };
+}
+
+function buildHookBaselineSurface(cwd, options = {}) {
+  const baseline = buildHookBaseline(cwd, options);
+  const writeResult = writeHookBaseline(cwd, baseline);
+  return { baseline, writeResult };
+}
+
+function formatHookBaselineText(baseline, options = {}) {
+  const debug = options.debug || false;
+
+  const lines = [
+    "Avorelo hook baseline: ready.",
+    "",
+    `Events registered: ${baseline.eventsRegistered.join(", ")}`,
+    `Blocking: ${baseline.blockingEvents.join(", ")}`,
+    `Non-blocking: ${baseline.nonBlockingEvents.join(", ")}`,
+    `Conditionally blocking: ${baseline.conditionallyBlockingEvents.join(", ")} (prohibited/destructive prompts only)`,
+    "",
+    "Status: preview only. No user config has been modified.",
+    `Hooks: ${baseline.hookCount} defined. Apply requires explicit user approval.`,
+  ];
+
+  if (debug) {
+    lines.push("", "Hook commands:");
+    for (const hook of baseline.hooks) {
+      lines.push(`  [${hook.event}] ${hook.blocking ? "blocking" : "non-blocking"} — ${hook.command}`);
+      lines.push(`    Purpose: ${hook.purpose}`);
+      lines.push(`    Capabilities: ${hook.capabilities.join(", ")}`);
+      if (hook.blockingCondition) {
+        lines.push(`    Blocking condition: ${hook.blockingCondition}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  LATEST_BASELINE_REL,
+  LIFECYCLE_EVENTS,
+  BLOCKING_EVENTS,
+  CONDITIONALLY_BLOCKING_EVENTS,
+  NON_BLOCKING_EVENTS,
+  getBaselineHookDefinitions,
+  buildHookBindingMap,
+  buildHookBaseline,
+  writeHookBaseline,
+  buildHookBaselineSurface,
+  formatHookBaselineText,
+};

package/scripts/lib/hook-config-preview.js

@@ -0,0 +1,275 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const CONTRACT = "avorelo.hookConfigPreview.v1";
+const SCHEMA_VERSION = 1;
+
+const PREVIEW_DIR_REL = ".claude/cco/orchestration/hook-baseline";
+const LATEST_PREVIEW_JSON_REL = `${PREVIEW_DIR_REL}/latest-preview.json`;
+const LATEST_PREVIEW_MD_REL = `${PREVIEW_DIR_REL}/latest-preview.md`;
+
+// The lifecycle-hook commands that would be wired up
+const LIFECYCLE_HOOK_COMMANDS = Object.freeze([
+  { event: "SessionStart", command: "node bin/avorelo lifecycle-hook session-start --json", blocking: false },
+  { event: "UserPromptSubmit", command: "node bin/avorelo lifecycle-hook user-prompt-submit --json", blocking: false },
+  { event: "PreToolUse", command: "node bin/avorelo lifecycle-hook pre-tool-use --json", blocking: true },
+  { event: "PostToolUse", command: "node bin/avorelo lifecycle-hook post-tool-use --json", blocking: false },
+  { event: "Stop", command: "node bin/avorelo lifecycle-hook stop --json", blocking: true },
+  { event: "SessionEnd", command: "node bin/avorelo lifecycle-hook session-end --json", blocking: false },
+]);
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function safeWriteJson(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+function safeWriteText(filePath, text) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, text, "utf8");
+}
+
+function buildHostPreview(host) {
+  if (host === "claude_code") {
+    return {
+      host,
+      label: "Claude Code",
+      configPath: ".claude/settings.json",
+      wouldAddFormat: "hooks array in settings.json",
+      note: "Preview only. settings.json will NOT be modified without explicit user approval.",
+      exampleStructure: {
+        hooks: LIFECYCLE_HOOK_COMMANDS.map((lh) => ({
+          event: lh.event,
+          command: lh.command,
+          blocking: lh.blocking,
+        })),
+      },
+    };
+  }
+  if (host === "openhands") {
+    return {
+      host,
+      label: "OpenHands",
+      configPath: ".openhands/hooks.json",
+      wouldAddFormat: "hooks.json entries",
+      note: "Preview only. hooks.json will NOT be modified without explicit user approval.",
+      exampleStructure: {
+        hooks: LIFECYCLE_HOOK_COMMANDS.map((lh) => ({
+          event: lh.event,
+          command: lh.command,
+          blocking: lh.blocking,
+        })),
+      },
+    };
+  }
+  // generic_cli
+  return {
+    host: "generic_cli",
+    label: "Generic CLI",
+    configPath: null,
+    wouldAddFormat: "manual shell integration",
+    note: "Generic CLI mode. No config file to modify. Commands can be run manually.",
+    exampleStructure: {
+      commands: LIFECYCLE_HOOK_COMMANDS.map((lh) => ({
+        event: lh.event,
+        command: lh.command,
+        blocking: lh.blocking,
+        usage: `Run before/after ${lh.event}`,
+      })),
+    },
+  };
+}
+
+function buildHookConfigPreview(cwd, options = {}) {
+  const { buildAdapterReadiness } = require("./adapter-readiness");
+  const readiness = buildAdapterReadiness(cwd, options);
+
+  const detectedHosts = readiness.hosts.filter((h) => h.detected || h.fallback).map((h) => h.host);
+  const previewHosts = detectedHosts.length > 0 ? detectedHosts : ["generic_cli"];
+
+  const hosts = previewHosts.map(buildHostPreview);
+
+  const wouldAdd = {};
+  for (const lh of LIFECYCLE_HOOK_COMMANDS) {
+    wouldAdd[lh.event] = {
+      command: lh.command,
+      blocking: lh.blocking,
+      note: lh.blocking ? "Blocking hook — will pause execution until handler completes." : "Non-blocking hook.",
+    };
+  }
+
+  const configPaths = hosts.filter((h) => h.configPath).map((h) => h.configPath);
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    mode: "preview_only",
+    hosts,
+    wouldAdd,
+    wouldNotModify: configPaths,
+    approvalRequiredBeforeApply: true,
+    caveats: [
+      "This is a preview only. No user config has been modified.",
+      "Applying hooks requires explicit user approval in a future PR.",
+      "No global hook installation.",
+      "No full Claude plugin.",
+      "No full OpenHands adapter.",
+    ],
+    configPaths,
+    adapterReadinessStatus: readiness.status,
+    redacted: true,
+  };
+}
+
+function buildPreviewMarkdown(preview) {
+  const lines = [
+    "# Avorelo Hook Config Preview",
+    "",
+    "> **Preview only.** No user config has been modified. Applying hooks requires explicit user approval.",
+    "",
+    `Generated: ${preview.createdAt}`,
+    `Mode: ${preview.mode}`,
+    `Adapter readiness: ${preview.adapterReadinessStatus}`,
+    "",
+    "## What Would Be Added",
+    "",
+    "If hooks were applied, the following lifecycle commands would be registered:",
+    "",
+    "| Event | Command | Blocking |",
+    "|-------|---------|----------|",
+  ];
+
+  for (const [event, info] of Object.entries(preview.wouldAdd || {})) {
+    lines.push(`| ${event} | \`${info.command}\` | ${info.blocking ? "Yes" : "No"} |`);
+  }
+
+  lines.push(
+    "",
+    "## Would NOT Modify",
+    "",
+    "The following files would NOT be modified without explicit approval:",
+    "",
+  );
+  for (const p of preview.wouldNotModify || []) {
+    lines.push(`- \`${p}\``);
+  }
+
+  lines.push(
+    "",
+    "## Hosts",
+    "",
+  );
+  for (const host of preview.hosts || []) {
+    lines.push(`### ${host.label}`);
+    if (host.configPath) {
+      lines.push(`- Config path: \`${host.configPath}\``);
+    }
+    lines.push(`- Format: ${host.wouldAddFormat}`);
+    lines.push(`- ${host.note}`);
+    lines.push("");
+  }
+
+  lines.push(
+    "## Caveats",
+    "",
+  );
+  for (const caveat of preview.caveats || []) {
+    lines.push(`- ${caveat}`);
+  }
+
+  lines.push(
+    "",
+    "## Next Steps",
+    "",
+    "1. Review this preview.",
+    "2. If satisfied, request hook application in a future PR.",
+    "3. Hook application will require explicit approval and will be a separate, scoped change.",
+  );
+
+  return lines.join("\n");
+}
+
+function writeHookConfigPreview(cwd, preview) {
+  const jsonPath = path.join(cwd, LATEST_PREVIEW_JSON_REL);
+  const mdPath = path.join(cwd, LATEST_PREVIEW_MD_REL);
+
+  safeWriteJson(jsonPath, preview);
+  safeWriteText(mdPath, buildPreviewMarkdown(preview));
+
+  return {
+    jsonPath: LATEST_PREVIEW_JSON_REL,
+    mdPath: LATEST_PREVIEW_MD_REL,
+    written: true,
+  };
+}
+
+function buildHookConfigPreviewSurface(cwd, options = {}) {
+  const preview = buildHookConfigPreview(cwd, options);
+  const writeResult = writeHookConfigPreview(cwd, preview);
+  return { preview, writeResult };
+}
+
+function formatHookConfigPreviewText(preview, options = {}) {
+  const debug = options.debug || false;
+  const lines = [
+    "Avorelo hook config preview: ready.",
+    "",
+    "Mode: preview_only",
+    "No user config has been modified.",
+    `Adapter readiness: ${preview.adapterReadinessStatus}`,
+    "",
+    "What would be added (pending user approval):",
+  ];
+
+  for (const [event, info] of Object.entries(preview.wouldAdd || {})) {
+    lines.push(`  ${event}: ${info.command}`);
+  }
+
+  lines.push(
+    "",
+    "Would NOT modify:",
+  );
+  for (const p of preview.wouldNotModify || []) {
+    lines.push(`  - ${p}`);
+  }
+
+  lines.push(
+    "",
+    "Approval required before any config change: true",
+  );
+
+  if (debug) {
+    lines.push("", "Hosts:");
+    for (const h of preview.hosts || []) {
+      lines.push(`  [${h.host}] config: ${h.configPath || "none"}`);
+    }
+    lines.push("", "Caveats:");
+    for (const c of preview.caveats || []) {
+      lines.push(`  - ${c}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  LATEST_PREVIEW_JSON_REL,
+  LATEST_PREVIEW_MD_REL,
+  LIFECYCLE_HOOK_COMMANDS,
+  buildHookConfigPreview,
+  writeHookConfigPreview,
+  buildHookConfigPreviewSurface,
+  formatHookConfigPreviewText,
+};