avorelo 0.1.0

package/scripts/lib/ai-install-prompt.js

@@ -0,0 +1,288 @@
+"use strict";
+
+// ── AI Install Prompt ─────────────────────────────────────────────────────────
+//
+// Contract: avorelo.aiInstallPrompt.v1
+//
+// Generates a safe, copy-pasteable one-prompt AI install experience.
+// Inspired by PostHog install-with-AI pattern, adapted for Avorelo's
+// approval-boundary requirements (hooks/MCP/tool governance require
+// explicit user approval — never auto-applied).
+//
+// Rules:
+// - Prompt never includes raw secrets, repo-specific sensitive data, or PII
+// - Hook apply always requires explicit --yes approval from user
+// - MCP config is never auto-modified
+// - Global config is never modified
+// - AI must stop on blockers and request explicit approval for config changes
+// - Default output is compact; debug exposes internals
+
+const fs = require("fs");
+const path = require("path");
+const { ensureCcoDirs, nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.aiInstallPrompt.v1";
+const SCHEMA_VERSION = 1;
+
+const PROMPT_DIR_REL = ".claude/cco/orchestration/ai-install";
+const LATEST_PROMPT_REL = `${PROMPT_DIR_REL}/latest-prompt.json`;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const AVORELO_ROOT = path.resolve(__dirname, "../../");
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function safeReadJsonRel(cwd, rel) {
+  return safeReadJson(path.join(cwd, rel));
+}
+
+// ── Command sequence ──────────────────────────────────────────────────────────
+
+function buildCommandSequence() {
+  return [
+    { step: 1, cmd: "node bin/avorelo activate --json", purpose: "Detect project and run activation checks" },
+    { step: 2, cmd: "node bin/avorelo alpha-readiness --json", purpose: "Verify first-value readiness gate" },
+    { step: 3, cmd: "node bin/avorelo launch-hardening --json", purpose: "Check launch hardening status" },
+    { step: 4, cmd: "node bin/avorelo token-efficiency --json", purpose: "Check token/context efficiency" },
+    { step: 5, cmd: "node bin/avorelo mcp doctor --json", purpose: "Check MCP/tool governance" },
+    { step: 6, cmd: "node bin/avorelo hooks doctor --json", purpose: "Check hook lifecycle status" },
+    { step: 7, cmd: "node bin/avorelo run \"<task>\" --prepare-only --json", purpose: "Run first safe value path (prepare only)" },
+    { step: 8, cmd: "node bin/avorelo support-bundle --json", purpose: "Generate support bundle if needed" },
+    { step: 9, cmd: "node bin/avorelo prelaunch-readiness --json", purpose: "Run full pre-launch activation readiness gate" },
+    { step: 10, cmd: "node bin/avorelo proof", purpose: "Show compact value summary" },
+  ];
+}
+
+// ── Approval boundaries ───────────────────────────────────────────────────────
+
+function buildApprovalBoundaries() {
+  return [
+    {
+      surface: "hooks",
+      rule: "NEVER run `avorelo hooks apply --yes` without explicit user approval. Always show dry-run preview first.",
+      command: "node bin/avorelo hooks apply --dry-run",
+      approvalCommand: "node bin/avorelo hooks apply --yes",
+    },
+    {
+      surface: "mcp_config",
+      rule: "NEVER modify MCP config automatically. MCP governance is preview-only in this flow.",
+      command: null,
+      approvalCommand: null,
+    },
+    {
+      surface: "global_config",
+      rule: "NEVER modify global config files (e.g., ~/.claude/settings.json) without explicit user instruction.",
+      command: null,
+      approvalCommand: null,
+    },
+    {
+      surface: "destructive_commands",
+      rule: "NEVER run deploy, publish, rm -rf, database migrations, or production commands.",
+      command: null,
+      approvalCommand: null,
+    },
+  ];
+}
+
+// ── Safety rules ──────────────────────────────────────────────────────────────
+
+function buildSafetyRules() {
+  return [
+    "Do not write product code before activation readiness checks complete.",
+    "Stop immediately if any command returns status: fail — show the safeNextAction and wait.",
+    "Do not bypass, skip, or override any approval boundary.",
+    "Do not expose, log, or include secrets, API keys, tokens, or PII in any output.",
+    "Do not run --yes on hook apply without the user reading the dry-run preview.",
+    "Do not modify global config or MCP server config.",
+    "Keep all output compact. Use --debug only if the user requests diagnostics.",
+    "The value summary must be evidence-backed — no exact cost savings claims.",
+  ];
+}
+
+// ── Prompt text ───────────────────────────────────────────────────────────────
+
+function buildPromptText(commandSequence, approvalBoundaries, safetyRules) {
+  const steps = commandSequence.map((s) => `  ${s.step}. ${s.cmd}\n     # ${s.purpose}`).join("\n");
+  const boundaries = approvalBoundaries.map((b) => `  - ${b.surface}: ${b.rule}`).join("\n");
+  const rules = safetyRules.map((r) => `  - ${r}`).join("\n");
+
+  return `You are helping install and activate Avorelo in this repo.
+
+Follow these steps in order. Stop on any failure and show the safeNextAction.
+
+Steps:
+${steps}
+
+Approval boundaries (NEVER bypass these):
+${boundaries}
+
+Safety rules:
+${rules}
+
+After all steps complete, return a compact value summary:
+- What Avorelo checked automatically
+- Activation and readiness status
+- Hook and MCP governance status
+- Token/context efficiency status
+- Support bundle status
+- One safe next action
+
+Do not claim public launch readiness. Do not claim exact/guaranteed savings.
+Output must be compact by default. Use --debug flags only if the user asks for details.`;
+}
+
+// ── Expected outputs ──────────────────────────────────────────────────────────
+
+function buildExpectedOutputs() {
+  return [
+    { step: "activate", shape: "avorelo.alphaActivation.v1", keyField: "status" },
+    { step: "alpha-readiness", shape: "avorelo.alphaReadinessGate.v1", keyField: "status" },
+    { step: "launch-hardening", shape: "avorelo.launchHardeningGate.v1", keyField: "status" },
+    { step: "token-efficiency", shape: "evidence.contract", keyField: "status" },
+    { step: "mcp doctor", shape: "mcp governance summary", keyField: "policy.status" },
+    { step: "hooks doctor", shape: "avorelo.hookApply.v1", keyField: "status" },
+    { step: "prelaunch-readiness", shape: "avorelo.prelaunchActivationReadiness.v1", keyField: "status" },
+    { step: "proof", shape: "compact proof output", keyField: "summary" },
+  ];
+}
+
+// ── Build prompt receipt ──────────────────────────────────────────────────────
+
+function buildAiInstallPrompt(cwd, options = {}) {
+  const commandSequence = buildCommandSequence();
+  const approvalBoundaries = buildApprovalBoundaries();
+  const safetyRules = buildSafetyRules();
+  const promptText = buildPromptText(commandSequence, approvalBoundaries, safetyRules);
+  const expectedOutputs = buildExpectedOutputs();
+
+  // Check if activation module is available
+  let activationAvailable = false;
+  try {
+    require("./alpha-activation");
+    activationAvailable = true;
+  } catch {}
+
+  // Check if prelaunch readiness module is available
+  let prelaunchAvailable = false;
+  try {
+    require("./prelaunch-activation-readiness");
+    prelaunchAvailable = true;
+  } catch {}
+
+  const status = activationAvailable ? "ready" : "partial";
+
+  const receipt = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    promptText,
+    commandSequence,
+    approvalBoundaries,
+    safetyRules,
+    expectedOutputs,
+    nextAction: "Copy the promptText and paste it into Claude Code, Codex, Cursor, VS Code, or your AI coding agent.",
+    activationAvailable,
+    prelaunchAvailable,
+    redacted: true,
+  };
+
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "ai_install_prompt_generated",
+      status: receipt.status,
+      activationAvailable,
+      prelaunchAvailable,
+    });
+  } catch {}
+
+  return receipt;
+}
+
+// ── Build install plan (metadata without full prompt text) ────────────────────
+
+function buildAiInstallPlan(cwd, options = {}) {
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    stepCount: buildCommandSequence().length,
+    approvalBoundaryCount: buildApprovalBoundaries().length,
+    safetyRuleCount: buildSafetyRules().length,
+    summary: "One-prompt AI install: activate → readiness → launch-hardening → token/context → mcp → hooks → first-value → support → prelaunch-readiness → proof",
+    safeForAutoRun: false,
+    requiresExplicitApproval: ["hooks apply", "mcp config changes", "global config changes"],
+    redacted: true,
+  };
+}
+
+// ── Artifact I/O ──────────────────────────────────────────────────────────────
+
+function writeAiInstallPromptReceipt(cwd, receipt) {
+  const dir = path.join(cwd, PROMPT_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  const latest = path.join(cwd, LATEST_PROMPT_REL);
+  // Never write raw secrets. Receipt has redacted:true.
+  // Strip promptText from the stored artifact (keep it in-memory only) to avoid
+  // accidentally committing repo-sensitive context.
+  const stored = Object.assign({}, receipt, { promptText: "[see formatAiInstallPromptText]" });
+  fs.writeFileSync(latest, JSON.stringify(stored, null, 2), "utf8");
+  return latest;
+}
+
+// ── Surface / format ──────────────────────────────────────────────────────────
+
+function buildAiInstallPromptSurface(cwd, options = {}) {
+  const receipt = buildAiInstallPrompt(cwd, options);
+  return { receipt };
+}
+
+function formatAiInstallPromptText(receipt, options = {}) {
+  const lines = [
+    `Install Avorelo with AI`,
+    ``,
+    `Copy this prompt into Claude Code, Codex, Cursor, VS Code, or your AI coding agent:`,
+    ``,
+    `─────────────────────────────────────────────────────────────`,
+    receipt.promptText,
+    `─────────────────────────────────────────────────────────────`,
+    ``,
+    `What it will do:`,
+    `  - Check project readiness.`,
+    `  - Run safe activation.`,
+    `  - Verify hooks and MCP/tool governance.`,
+    `  - Request approval before config changes.`,
+    `  - Run first-value verification.`,
+    `  - Produce a compact value summary.`,
+    ``,
+    `Next:`,
+    `  - Paste the prompt into your AI coding session.`,
+    ``,
+    `Note: Hook apply requires explicit approval. MCP config is not modified automatically.`,
+  ];
+  return lines.join("\n");
+}
+
+module.exports = {
+  buildAiInstallPrompt,
+  buildAiInstallPlan,
+  writeAiInstallPromptReceipt,
+  buildAiInstallPromptSurface,
+  formatAiInstallPromptText,
+  // exposed for testing
+  buildCommandSequence,
+  buildApprovalBoundaries,
+  buildSafetyRules,
+  buildPromptText,
+  CONTRACT,
+  LATEST_PROMPT_REL,
+};