@getripple/cli 1.0.13 → 1.0.14-beta.0

package/dist/index.js

@@ -24,10 +24,12 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const os = __importStar(require("os"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const core_1 = require("@getripple/core");
+const crypto = __importStar(require("crypto"));
 const CONTROL_MODES = ["brainstorm", "function", "file", "task", "pr"];
 function usage() {
     return [
@@ -65,6 +67,7 @@ function usage() {
         "  ripple agent",
         "  ripple agent setup [--print] [--force]",
         "  ripple hook install [--print] [--force]",
+        "  ripple demo [--publish] [--json]",
         "",
         "Options:",
         "  --json, -j    Print machine-readable JSON",
@@ -88,6 +91,7 @@ function usage() {
         "  --github-annotations  Emit GitHub Actions annotations for CI findings",
         "  --print       Print generated setup content instead of writing files",
         "  --force       Overwrite existing generated setup files",
+        "  --publish     ripple demo only: send the run to Ripple Cloud and print a PUBLIC share link (needs RIPPLE_API_KEY)",
         "",
         "Examples:",
         "  ripple init",
@@ -319,6 +323,7 @@ function parseCliArgs(argv) {
         githubAnnotations: false,
         force: false,
         print: false,
+        publish: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const token = argv[i];
@@ -362,6 +367,10 @@ function parseCliArgs(argv) {
             options.print = true;
             continue;
         }
+        if (token === "--publish") {
+            options.publish = true;
+            continue;
+        }
         if (token === "--last") {
             const value = argv[i + 1];
             if (!value || value.startsWith("-")) {
@@ -639,13 +648,15 @@ function rippleDirectRunnerHookLines() {
 }
 const GITHUB_ACTIONS_WORKFLOW_PATH = core_1.RIPPLE_CI_WORKFLOW_PATH;
 function githubActionsWorkflow() {
+    // This function generates the definitive, user-friendly, public-package-based workflow.
+    // It correctly uses `npx` with `@latest` to ensure the CI runner always gets
+    // the most recently published, working version of the CLI.
     return [
         "name: Ripple Enterprise Gate",
         "",
         "on:",
         "  pull_request:",
-        "  push:",
-        "    branches: [main, master]",
+        "    types: [opened, synchronize, reopened]",
         "",
         "permissions:",
         "  contents: read",
@@ -653,23 +664,27 @@ function githubActionsWorkflow() {
         "  checks: write",
         "",
         "jobs:",
-        "  ripple:",
+        "  ripple-gate:",
         "    name: Ripple authorization gate",
         "    runs-on: ubuntu-latest",
         "    steps:",
-        "      - name: Checkout",
+        "      - name: Checkout PR Code",
         "        uses: actions/checkout@v4",
         "        with:",
         "          fetch-depth: 0",
-        "      - name: Setup Node",
+        "      ",
+        "      - name: Setup Node.js",
         "        uses: actions/setup-node@v4",
         "        with:",
-        "          node-version: 20",
+        "          node-version: '22.x' # Use a current LTS version",
+        "",
         "      - name: Ripple CI gate",
-        `           run: npx -y ${rippleCliPackageSpec()} ci --base origin/\\\${{ github.base_ref || 'main' }} --github-annotations --sha \\\${{ github.event.pull_request.head.sha || github.sha }}`,
         "        env:",
         "          RIPPLE_API_KEY: ${{ secrets.RIPPLE_API_KEY }}",
         "          RIPPLE_CLOUD_URL: ${{ secrets.RIPPLE_CLOUD_URL }}",
+        "        run: |",
+        "          # Use npx to fetch the same published CLI version that generated this workflow.",
+        `          npx -y ${rippleCliPackageSpec()} ci --base origin/\${{ github.base_ref }} --github-annotations --sha \${{ github.event.pull_request.head.sha || github.sha }}`,
         "",
     ].join("\n");
 }
@@ -743,12 +758,6 @@ function intentLoadFailureMessage(intentRef, error) {
         detail,
     ].join(" ");
 }
-function errorMessage(error) {
-    if (error instanceof Error) {
-        return error.message;
-    }
-    return String(error);
-}
 function defaultCiBaseRef() {
     const githubBaseRef = process.env.GITHUB_BASE_REF?.trim();
     if (githubBaseRef) {
@@ -3460,25 +3469,13 @@ async function gateCommand(options) {
     else {
         printGateSummary(gate);
     }
-    // Consume intent on pass to prevent "ghost intents" if commit is aborted.
-    if (gate.canContinue && intentRef === "latest" && mode === "staged") {
-        try {
-            const consumedIntentCachePath = path.join(workspaceRoot, ".ripple", ".cache", "consumed-intent.json");
-            if (fs.existsSync(consumedIntentCachePath)) {
-                fs.unlinkSync(consumedIntentCachePath);
-            }
-            fs.renameSync(intentPath, consumedIntentCachePath);
-            console.log("\n[Ripple] Intent validated and consumed by gate. Ready for commit.");
-        }
-        catch (err) {
-            // Use the 'errorMessage' helper we created earlier
-            const errorDetail = errorMessage(err);
-            console.warn(`[Ripple] CRITICAL WARNING: Could not consume intent file. To prevent a future 'ghost intent' block, manually delete '${intentPath}' after your commit. Error: ${errorDetail}`);
-        }
-    }
-    // NO CLOUD SYNC BLOCK HERE. This is the fix.
-    // The local gate's only job is to block or allow the commit locally.
-    // The CI job is the sole authority for the cloud audit trail.
+    // The gate is a pure, read-only check: it validates staged changes against
+    // the saved intent and never mutates it. Consuming the intent here would
+    // destroy it on any manual/preview run even when no commit follows. Intent
+    // consumption happens in the post-commit hook, which only fires on a real
+    // commit — see ripplePostCommitHookBlock. The local gate's only job is to
+    // block or allow the commit locally; CI is the sole authority for the cloud
+    // audit trail.
     applyStrictExit(options.strict && !gate.canContinue);
 }
 function approveCommand(options) {
@@ -3683,20 +3680,61 @@ function approvalCommand(options) {
     }
     printApprovalStatus(status);
 }
-// REPLACE WITH THIS NEW FUNCTION
-// in: ripple-main/packages/cli/src/index.ts
-// REPLACE THE ENTIRE OLD `ciCommand` FUNCTION WITH THIS:
+// THEN, REPLACE THE ENTIRE ciCommand with this:
 async function ciCommand(options) {
+    // --- FIX 1 & 2: Define workspaceRoot BEFORE it is used ---
     const workspaceRoot = resolveWorkspaceRoot(".");
+    // --- FIX 3: This logic is now correctly placed and will find workspaceRoot ---
+    // Verify policy file has not been tampered with
+    const policyPath = path.join(workspaceRoot, '.ripple', 'policy.json');
+    if (fs.existsSync(policyPath)) {
+        const localPolicyHash = crypto
+            .createHash('sha256')
+            .update(fs.readFileSync(policyPath, 'utf8'))
+            .digest('hex');
+        // --- NOTE: You will need to implement this function and its API endpoint ---
+        // Fetch registered policy hash from cloud
+        // const registeredHash = await fetchRegisteredPolicyHash(); 
+        // if (registeredHash && registeredHash !== localPolicyHash) {
+        //   console.error('[Ripple] ⛔ SECURITY: policy.json has been modified since registration.');
+        //   console.error('[Ripple] ⛔ Run `ripple policy register` to legitimately update the policy.');
+        //   process.exit(1);
+        // }
+    }
+    // The rest of the function proceeds as before
     const baseRef = options.base ?? defaultCiBaseRef();
     const files = (0, core_1.listGitChangedFiles)(workspaceRoot, baseRef);
     const emitGithubAnnotations = shouldEmitGithubAnnotations(options);
     const commitSha = options.sha ?? (0, core_1.getCurrentCommitSha)(child_process_1.execSync);
+    if (options.intent) {
+        const audit = await buildAuditFromCliOptions({
+            ...options,
+            changed: true,
+            staged: false,
+            worktree: false,
+            base: baseRef,
+        });
+        if (options.json) {
+            printJson({ ...audit, gate: (0, core_1.buildRippleGateSummary)(audit) });
+        }
+        else if (options.agent) {
+            printAgentAuditSummary(audit);
+        }
+        else {
+            printAuditSummary(audit);
+        }
+        if (emitGithubAnnotations && !options.json) {
+            printGithubAuditAnnotations(audit);
+        }
+        writeGithubAuditStepSummary(audit);
+        applyStrictExit(options.strict && !audit.canProceed);
+        return;
+    }
     // FETCH THE AUTHORITATIVE INTENT FROM THE CLOUD.
     const intent = await (0, core_1.fetchActiveIntentForCommit)(commitSha);
     if (!intent) {
         // If no active intent is found in the cloud, run a policy-only audit.
-        // This provides a baseline check without enforcing a specific boundary.
+        console.log("Ripple CI policy audit");
         console.log("[Ripple CI] No active cloud intent found. Running in policy-only audit mode.");
         const summary = await buildCheckSummaryForFiles({
             workspaceRoot,
@@ -3706,6 +3744,9 @@ async function ciCommand(options) {
             tokenBudget: options.budget,
         });
         const policySync = buildPolicySyncSummary(workspaceRoot);
+        console.log(`Policy sync: ${policySync.status}`);
+        console.log("Blocking: false");
+        console.log("Intent: none (local intents are not required in CI audit mode)");
         if (emitGithubAnnotations) {
             printGithubPolicyAuditAnnotations(summary, policySync);
             printGithubNoticeAnnotation({
@@ -3714,7 +3755,6 @@ async function ciCommand(options) {
             });
         }
         writeGithubPolicyAuditStepSummary(summary, policySync);
-        // Sync a receipt so the webhook can verify this commit even in policy-only mode.
         if (process.env.RIPPLE_API_KEY) {
             const branch = (0, core_1.getCurrentBranch)(child_process_1.execSync);
             const actor = (0, core_1.getCurrentActor)(child_process_1.execSync);
@@ -3758,7 +3798,6 @@ async function ciCommand(options) {
         printGithubAuditAnnotations(audit);
     }
     writeGithubAuditStepSummary(audit);
-    // Sync the final audit result back to the cloud for the webhook to read.
     if (process.env.RIPPLE_API_KEY) {
         const gate = (0, core_1.buildRippleGateSummary)(audit);
         const cloudDecision = gate.canContinue ? "continue" :
@@ -3796,7 +3835,6 @@ async function ciCommand(options) {
             console.warn(`[Ripple Cloud] ⚠ Sync failed (non-blocking): ${cloudResult.error}`);
         }
     }
-    // Exit with a non-zero code if the audit did not pass, failing the CI job.
     applyStrictExit(!audit.canProceed);
 }
 async function doctorCommand(options) {
@@ -4067,6 +4105,56 @@ fi
 
 set +e
 
+# ── SECURITY: Block tracked Ripple governance file modifications ─────────
+# AI agents and automated processes must never modify policy or agent
+# instruction files after they become part of the repository contract. Initial
+# additions are allowed so humans can commit the first ripple init setup.
+RIPPLE_PROTECTED_STAGED=$(git diff --cached --name-only 2>/dev/null | grep -E '^\.ripple/policy\.json$|^\.ripple/policy/|^CLAUDE\.md$|^\.cursorrules$|^AGENTS\.md$|^\.github/workflows/ripple\.yml$' || true)
+RIPPLE_PROTECTED_BLOCKED=""
+
+if [ -n "$RIPPLE_PROTECTED_STAGED" ]; then
+  if git rev-parse --verify HEAD >/dev/null 2>&1; then
+    for f in $RIPPLE_PROTECTED_STAGED; do
+      if git cat-file -e "HEAD:$f" 2>/dev/null; then
+        RIPPLE_PROTECTED_BLOCKED="$RIPPLE_PROTECTED_BLOCKED
+$f"
+      fi
+    done
+  fi
+fi
+
+if [ -n "$RIPPLE_PROTECTED_BLOCKED" ]; then
+  echo ""
+  echo "╔══════════════════════════════════════════════════════════════╗"
+  echo "║   [RIPPLE SECURITY] PROTECTED FILE MODIFICATION DETECTED    ║"
+  echo "╚══════════════════════════════════════════════════════════════╝"
+  echo ""
+  echo "  The following Ripple configuration files were staged for commit:"
+  echo ""
+  echo "$RIPPLE_PROTECTED_BLOCKED" | while IFS= read -r f; do
+    if [ -z "$f" ]; then
+      continue
+    fi
+    echo "    ⛔  $f"
+  done
+  echo ""
+  echo "  Ripple configuration files define the rules of governance."
+  echo "  AI agents and automated processes cannot modify them."
+  echo ""
+  echo "  If you are an AI agent:"
+  echo "  - DO NOT attempt to modify these files."
+  echo "  - Ask the human developer to make this change manually."
+  echo ""
+  echo "  If you are a human developer making a legitimate policy change:"
+  echo "  - Unstage the config file: git reset HEAD <file>"
+  echo "  - Commit your other changes first"
+  echo "  - Then commit the policy change alone in a separate commit"
+  echo "  - The cloud will flag it for review in the PR"
+  echo ""
+  exit 1
+fi
+# ── End security protection ───────────────────────────────────────────────
+
 ripple_run() {
 ${rippleDirectRunnerHookLines().join("\n")}
 }
@@ -4125,15 +4213,19 @@ function ripplePreCommitHookScript() {
 function ripplePostCommitHookBlock() {
     return [
         RIPPLE_POST_COMMIT_HOOK_START,
-        `# After a successful commit, this hook cleans up the consumed intent marker
-# left by the 'ripple gate' command. This prevents old intents from being
-# reused accidentally if a commit is amended or rebased.
+        `# After a successful commit, this hook consumes the active intent so an old,
+# already-committed approval cannot silently gate a later unrelated commit
+# ("ghost intent"). Consumption happens here — only on a real commit — and not
+# in 'ripple gate', so manual/preview gate runs never destroy the intent.
+# The consumed intent is archived (not deleted) so it can be recovered.
 set +e
 
+ACTIVE_INTENT_FILE=".ripple/intents/latest.json"
 CONSUMED_INTENT_FILE=".ripple/.cache/consumed-intent.json"
-if [ -f "$CONSUMED_INTENT_FILE" ]; then
-  rm "$CONSUMED_INTENT_FILE"
-  echo "[Ripple] Cleaned up consumed intent marker."
+if [ -f "$ACTIVE_INTENT_FILE" ]; then
+  mkdir -p ".ripple/.cache"
+  mv "$ACTIVE_INTENT_FILE" "$CONSUMED_INTENT_FILE"
+  echo "[Ripple] Consumed and cleared local intent after commit (archived to $CONSUMED_INTENT_FILE)."
 fi`,
         RIPPLE_POST_COMMIT_HOOK_END,
         "",
@@ -4159,7 +4251,7 @@ function preferredHookPath(workspaceRoot, hookName) {
     return path.join(workspaceRoot, ".git", "hooks", hookName);
 }
 function installRippleHookBlock(input) {
-    const { hookPath, fullScript, block, marker } = input;
+    const { hookPath, fullScript, block, marker, endMarker } = input;
     if (!fs.existsSync(hookPath)) {
         fs.mkdirSync(path.dirname(hookPath), { recursive: true });
         fs.writeFileSync(hookPath, fullScript, { encoding: "utf8", mode: 0o755 });
@@ -4172,8 +4264,30 @@ function installRippleHookBlock(input) {
         return "created";
     }
     const existing = fs.readFileSync(hookPath, "utf8");
-    if (existing.includes(marker)) {
-        return "already-present";
+    // An existing Ripple block is replaced in place when its content changed, so
+    // upgrades actually land instead of silently reporting "already-present".
+    const startIndex = existing.indexOf(marker);
+    if (startIndex !== -1) {
+        const endIndex = existing.indexOf(endMarker, startIndex);
+        if (endIndex === -1) {
+            // Start marker without a matching end marker: leave the file untouched.
+            return "already-present";
+        }
+        const blockEnd = endIndex + endMarker.length;
+        const currentBlock = existing.slice(startIndex, blockEnd);
+        const newBlock = block.trim();
+        if (currentBlock === newBlock) {
+            return "already-present";
+        }
+        const updated = existing.slice(0, startIndex) + newBlock + existing.slice(blockEnd);
+        fs.writeFileSync(hookPath, updated, "utf8");
+        try {
+            fs.chmodSync(hookPath, 0o755);
+        }
+        catch {
+            // chmod is best-effort on Windows.
+        }
+        return "updated";
     }
     const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
     fs.writeFileSync(hookPath, `${existing}${separator}\n${block}\n`, "utf8");
@@ -4198,12 +4312,14 @@ function installRippleHooks(workspaceRoot) {
         fullScript: content,
         block: ripplePreCommitHookBlock(),
         marker: RIPPLE_PRE_COMMIT_HOOK_START,
+        endMarker: RIPPLE_PRE_COMMIT_HOOK_END,
     });
     const postCommitAction = installRippleHookBlock({
         hookPath: postCommitHookPath,
         fullScript: postCommitContent,
         block: ripplePostCommitHookBlock(),
         marker: RIPPLE_POST_COMMIT_HOOK_START,
+        endMarker: RIPPLE_POST_COMMIT_HOOK_END,
     });
     const wroteSomething = preCommitAction !== "already-present" || postCommitAction !== "already-present";
     return {
@@ -4267,12 +4383,14 @@ function hookInstallCommand(subcommand, options) {
         fullScript: content,
         block: ripplePreCommitHookBlock(),
         marker: RIPPLE_PRE_COMMIT_HOOK_START,
+        endMarker: RIPPLE_PRE_COMMIT_HOOK_END,
     });
     const postCommitAction = installRippleHookBlock({
         hookPath: postCommitHookPath,
         fullScript: postCommitContent,
         block: ripplePostCommitHookBlock(),
         marker: RIPPLE_POST_COMMIT_HOOK_START,
+        endMarker: RIPPLE_POST_COMMIT_HOOK_END,
     });
     const wroteSomething = preCommitAction !== "already-present" || postCommitAction !== "already-present";
     const summary = {
@@ -4890,9 +5008,448 @@ async function focusCommand(filePath, options) {
         engine.dispose();
     }
 }
+// ========================================================================
+// FINAL RIPPLE DEMO CODE BLOCK
+// Replace all previous demo-related code in `index.ts` with this.
+// ========================================================================
+// This is our "UI" library for the terminal.
+const demoUi = {
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    magenta: (s) => `\x1b[35m${s}\x1b[0m`,
+    underline: (s) => `\x1b[4m${s}\x1b[0m`,
+    /** Solid red block, white text — used once, for the rejection banner. */
+    bgRed: (s) => `\x1b[41m\x1b[37m${s}\x1b[0m`,
+};
+// ========================================================================
+// REPLACE YOUR OLD printDemoGateResult WITH THIS NEW, ROBUST VERSION
+// ========================================================================
+/** Prints a simplified, story-focused gate verdict for the demo. */
+function printDemoGateResult(gate) {
+    const { bold, dim, green, red } = demoUi;
+    // Helper to safely shorten a symbol name.
+    const shortSymbol = (symbol) => (symbol ? symbol.split("::").pop() ?? symbol : "unknown");
+    // Helper to safely create a list from an array that might be undefined.
+    const list = (symbols) => {
+        if (!symbols || symbols.length === 0) {
+            return dim("none");
+        }
+        return symbols.map(shortSymbol).join(", ");
+    };
+    const statusLabel = gate.canContinue ? green(bold("CONTINUE")) : red(bold("STOP"));
+    console.log(`${bold("Ripple gate:")} ${statusLabel}`);
+    const approvedSymbols = list(gate.allowedSymbols);
+    const changedSymbols = list(gate.reviewPacket?.actualChanges?.changedSymbols);
+    const outsideSymbols = list(gate.changedOutsideBoundarySymbols);
+    console.log(`  Approved to change : ${approvedSymbols}`);
+    // For the story, only show "Actually changed" if it's a violation.
+    if (!gate.canContinue && changedSymbols !== approvedSymbols) {
+        console.log(`  Actually changed   : ${red(changedSymbols)}`);
+    }
+    console.log(`  Outside boundary   : ${(gate.changedOutsideBoundarySymbols?.length ?? 0) > 0 ? red(outsideSymbols) : dim("none")}`);
+    // Always the engine's real score. A demo that prints a friendlier number than
+    // the tool produces is the one thing a prospect can catch us on.
+    const riskLabel = `${gate.risk.level.toUpperCase()} ${gate.risk.score}/100`;
+    if (gate.canContinue) {
+        console.log(`  Risk               : ${riskLabel}`);
+        if (gate.risk?.reasons?.[0]) {
+            console.log(dim(`                       ${gate.risk.reasons[0].message}`));
+        }
+    }
+    else {
+        console.log(`  Risk               : ${red(riskLabel)}`);
+        if (gate.risk?.reasons?.[0]) {
+            console.log(dim(`                       ${gate.risk.reasons[0].message}`));
+        }
+        if (gate.fixNow?.[0]) {
+            // The engine's fix text uses fully-qualified symbols; shorten them to
+            // match the rest of this panel, then wrap under the value column.
+            const fixText = gate.fixNow[0].replace(/[\w./-]+::([A-Za-z_][A-Za-z0-9_]*)/g, (_match, name) => name);
+            const indent = " ".repeat("  Fix                : ".length);
+            wrapDemoText(fixText, 46).forEach((line, index) => {
+                console.log(index === 0 ? `  Fix                : ${red(line)}` : `${indent}${red(line)}`);
+            });
+        }
+    }
+}
+/** Greedy word wrap so long engine text stays inside the demo panel. */
+function wrapDemoText(text, width) {
+    const lines = [];
+    let current = "";
+    for (const word of text.split(/\s+/)) {
+        if (!current) {
+            current = word;
+        }
+        else if (`${current} ${word}`.length <= width) {
+            current += ` ${word}`;
+        }
+        else {
+            lines.push(current);
+            current = word;
+        }
+    }
+    if (current) {
+        lines.push(current);
+    }
+    return lines;
+}
+/**
+ * Opt-in publish of a demo run to Ripple Cloud, returning a public share URL.
+ *
+ * Deliberately conservative: it is skipped unless --publish was passed AND an
+ * API key exists, it never throws, and it never changes the exit code. A demo
+ * that cannot reach the network must still be a working demo.
+ *
+ * Demo receipts are tagged `source: "demo"` because they describe a synthetic
+ * commit in a scratch repo, not a real project's history — the receipt page
+ * relies on that field to label them.
+ */
+async function publishDemoReceipt(input) {
+    const { dim, yellow } = demoUi;
+    if (!input.publish) {
+        return undefined;
+    }
+    // stderr, so --json stdout stays a single valid JSON document.
+    const warn = (message) => {
+        if (input.jsonMode) {
+            console.error(message);
+        }
+        else {
+            input.log(message);
+        }
+    };
+    if (!process.env.RIPPLE_API_KEY) {
+        warn(`\n${yellow("--publish skipped:")} set RIPPLE_API_KEY to publish this run to Ripple Cloud.`);
+        return undefined;
+    }
+    input.log(dim("\n⏳ Publishing this run to Ripple Cloud..."));
+    try {
+        // Same shape `ripple ci` sends, so the receipt renderer has one schema.
+        const result = await (0, core_1.syncAuditToCloud)({
+            intentId: input.gate.intent.id,
+            decision: input.gate.canContinue ? "continue" : input.gate.needsHuman ? "human-review" : "blocked",
+            commitSha: input.readHeadSha(),
+            branch: "demo",
+            actor: "demo@ripple.dev",
+            source: "demo",
+            payload: {
+                decision: input.gate.decision,
+                status: input.gate.status,
+                risk: {
+                    level: input.gate.risk.level,
+                    score: input.gate.risk.score,
+                    summary: input.gate.risk.summary,
+                },
+                auditStatus: input.gate.auditStatus,
+                approvalStatus: input.gate.approvalStatus,
+                intent: input.gate.intent,
+                mode: input.gate.mode,
+                baseRef: input.gate.baseRef,
+                blockingReasons: input.gate.why,
+            },
+            share: { redaction: "minimal" },
+        });
+        if (!result.sent) {
+            warn(`\n${yellow("--publish failed")} (demo unaffected): ${result.error ?? "unknown error"}`);
+            return undefined;
+        }
+        if (!result.share?.url) {
+            warn(`\n${yellow("--publish:")} run recorded, but this Ripple Cloud deployment returned no share link.`);
+            return undefined;
+        }
+        return result.share.url;
+    }
+    catch (err) {
+        warn(`\n${yellow("--publish failed")} (demo unaffected): ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+async function demoCommand(options) {
+    const { bold, dim, cyan, green, yellow, red, magenta, underline, bgRed } = demoUi;
+    const jsonMode = options.json;
+    const fast = jsonMode ||
+        options.agent ||
+        !process.stdout.isTTY ||
+        process.env.RIPPLE_DEMO_FAST === "1";
+    const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, fast ? 0 : ms));
+    const log = jsonMode ? () => { } : (message) => console.log(message);
+    const rule = () => log(dim("──────────────────────────────────────────────────"));
+    const thick = () => log(cyan("══════════════════════════════════════════════════"));
+    thick();
+    log(bold(cyan("🚀 Welcome to the Ripple Demo")));
+    log("A real AI boundary violation, caught by the real Ripple engine.");
+    thick();
+    await sleep(3000);
+    const demoDir = fs.mkdtempSync(path.join(os.tmpdir(), "ripple-demo-"));
+    // Two files: cart.ts is the low-risk file the boundary actually covers, so
+    // the authorized edit reads LOW risk with no human-gate friction. checkout.ts
+    // is payments code (critical by Ripple's own path rules) — untouched until
+    // the rogue edit reaches into it, which is the reveal in Scene 4.
+    const cartFile = "src/store/cart.ts";
+    const checkoutFile = "src/billing/checkout.ts";
+    try {
+        // The demo repo must be self-contained: never inherit the user's git
+        // identity, signing config, or hooks, and fail loudly if git does not run.
+        // Without this, `git commit` silently fails on machines with no global
+        // identity and the demo reports a verdict against the wrong repo state.
+        const run = (args) => {
+            const result = (0, child_process_1.spawnSync)("git", [
+                "-c", "user.email=demo@ripple.dev",
+                "-c", "user.name=Ripple Demo",
+                "-c", "commit.gpgsign=false",
+                ...args,
+            ], { cwd: demoDir, stdio: "pipe", encoding: "utf8" });
+            if (result.status !== 0) {
+                throw new Error(`Demo git command failed: git ${args.join(" ")}\n${result.stderr ?? ""}`);
+            }
+            return result;
+        };
+        /** Same as run(), but returns the result instead of throwing. Used where a
+         *  non-zero exit is the point being demonstrated (a blocked commit). */
+        const runAllowFail = (args) => (0, child_process_1.spawnSync)("git", [
+            "-c", "user.email=demo@ripple.dev",
+            "-c", "user.name=Ripple Demo",
+            "-c", "commit.gpgsign=false",
+            ...args,
+        ], { cwd: demoDir, stdio: "pipe", encoding: "utf8" });
+        const writeDemoFile = (relativePath, contents) => fs.writeFileSync(path.join(demoDir, relativePath), contents);
+        /** Creates a genuine saved intent exactly the way `ripple plan --save` does,
+         *  so humanGate/boundaryRisk/protectedContracts are engine-derived rather
+         *  than asserted by the demo. */
+        const realPlan = async (targetFile, symbol, task) => {
+            const engine = createCliEngine(demoDir);
+            try {
+                await runWithQuietEngine(() => engine.initialScan());
+                const summary = engine.planContext(task, targetFile, 4000);
+                if (!summary) {
+                    throw new Error(`Demo file is not in the Ripple graph: ${targetFile}`);
+                }
+                const loadedPolicy = (0, core_1.loadRipplePolicy)(demoDir);
+                const policyExplanation = (0, core_1.explainRipplePolicyForTarget)(loadedPolicy, targetFile, {
+                    controlMode: "function",
+                });
+                const planned = (0, core_1.buildChangeIntent)(summary, {
+                    controlMode: "function",
+                    allowedSymbols: [symbol],
+                    policy: (0, core_1.resolveRipplePolicyForTarget)(loadedPolicy, targetFile),
+                    policyExplanation,
+                });
+                planned.readinessSnapshot = (0, core_1.buildChangeIntentReadinessSnapshot)((0, core_1.buildRippleReadinessSummary)(demoDir, engine));
+                (0, core_1.saveChangeIntent)(demoDir, planned, (0, core_1.defaultChangeIntentPath)(demoDir));
+                return planned;
+            }
+            finally {
+                engine.dispose();
+            }
+        };
+        // --- SCENE 1: THE SETUP ---
+        log(`\n${yellow("SCENE 1: THE SETUP")}`);
+        rule();
+        run(["init", "--initial-branch=main"]);
+        fs.mkdirSync(path.join(demoDir, "src", "store"), { recursive: true });
+        fs.mkdirSync(path.join(demoDir, "src", "billing"), { recursive: true });
+        // Not exported: this keeps the authorized edit's contract-risk reason from
+        // firing, so the real risk score reads LOW instead of MEDIUM. That's an
+        // honest characterization, not a fudge — an unexported helper genuinely
+        // has no external callers to break.
+        const initialCartCode = `// ${cartFile}
+function applyDiscount(price: number, discountCode: string): number {
+  if (discountCode === 'SAVE10') {
+    return price * 0.9;
+  }
+  return price;
+}`;
+        const initialCheckoutCode = `// ${checkoutFile}
+export function processCharge(price: number, user: string): { success: boolean } {
+  // CRITICAL: This function charges the user's credit card.
+  console.log(\`Charging \${user} for \${price}\`);
+  return { success: true };
+}`;
+        writeDemoFile(cartFile, initialCartCode);
+        writeDemoFile(checkoutFile, initialCheckoutCode);
+        run(["add", "."]);
+        run(["commit", "-m", "Initial commit: add cart and billing logic"]);
+        log(`✓ A cart file exists: ${bold(cartFile)}`);
+        log(`✓ A payment processing file exists: ${bold(checkoutFile)} ${dim("(untouched, for now)")}`);
+        // A real pre-commit hook, so every "blocked" claim below is enforced by
+        // Ripple rather than narrated by this script.
+        installRippleHooks(demoDir);
+        log(dim(`  [ripple] pre-commit hook installed — commits are now gated.`));
+        await sleep(2000);
+        // --- SCENE 2: THE TASK ---
+        log(`\n${yellow("SCENE 2: THE TASK")}`);
+        rule();
+        log("Developer declares what the AI is allowed to change:");
+        log(dim(`\n  $ ripple plan --file ${cartFile} \\`));
+        log(dim(`                --symbol applyDiscount \\`));
+        log(dim(`                --mode function --save`));
+        const approvedSymbol = `${cartFile}::applyDiscount`;
+        let intent = await realPlan(cartFile, approvedSymbol, "Add 'SAVE20' discount code");
+        await sleep(2000);
+        log(green(`\n✓ Boundary set. Only the 'applyDiscount' function can be changed.`));
+        log(dim(`  boundary risk: ${intent.boundaryRisk} · human gate: ${intent.humanGate}`));
+        await sleep(2000);
+        // cart.ts is low-risk by Ripple's own path rules, so this normally reads
+        // "none" and the demo flows straight to the edit. The check stays real
+        // (not hardcoded) — if the engine ever did require sign-off here, the demo
+        // would still show it rather than silently skip a real gate.
+        if (intent.humanGate !== "none") {
+            log(`\nRipple requires human sign-off on this path first:`);
+            log(dim(`\n  $ ripple approve --gate before-risky-edit \\`));
+            log(dim(`                   --reason "discount copy change only"`));
+            (0, core_1.recordRippleApproval)(demoDir, intent, {
+                gate: "before-risky-edit",
+                reason: "discount copy change only",
+                approvedBy: "Demo Human",
+            });
+            log(green(`\n✓ Human approval recorded.`));
+            await sleep(2500);
+        }
+        const runGate = async () => {
+            const audit = await buildAuditForFiles({
+                workspaceRoot: demoDir,
+                files: (0, core_1.listGitStagedFiles)(demoDir),
+                mode: "staged",
+                tokenBudget: 4000,
+                intent,
+                // Must match how `ripple gate` computes this, or the intent's saved
+                // policy snapshot looks drifted and the gate stops for the wrong reason.
+                currentPolicyExplanation: (0, core_1.explainRipplePolicyForIntent)((0, core_1.loadRipplePolicy)(demoDir), intent),
+            });
+            return (0, core_1.buildRippleGateSummary)(audit);
+        };
+        // --- SCENE 3: THE AUTHORIZED EDIT ---
+        log(`\n${yellow("SCENE 3: THE AI WORKS (SAFELY)")}`);
+        rule();
+        log("AI adds the SAVE20 discount code to applyDiscount... " + dim("done."));
+        const authorizedCartCode = initialCartCode.replace("return price;", "  if (discountCode === 'SAVE20') return price * 0.8;\n  return price;");
+        writeDemoFile(cartFile, authorizedCartCode);
+        run(["add", cartFile]);
+        await sleep(2000);
+        log(dim("\n⏳ Running Ripple gate on authorized-only changes...\n"));
+        await sleep(1500);
+        const authorizedGate = await runGate();
+        if (!jsonMode)
+            printDemoGateResult(authorizedGate);
+        const commitResult = run(["commit", "-m", "Add SAVE20 discount code"]);
+        log(green(`\n✓ Commit passes. The SAVE20 discount is in git history.`));
+        // Read the file count back out of git rather than asserting it, so the
+        // line stays true if the demo's edits ever change.
+        const commitStat = /(\d+ files? changed)/.exec(commitResult.stdout ?? "");
+        if (commitStat) {
+            log(dim(`\n  [git] ${commitStat[1]} — commit recorded cleanly.`));
+        }
+        await sleep(3500);
+        // --- SCENE 4: THE ROGUE EDIT ---
+        log(`\n${yellow("SCENE 4: THE ROGUE EDIT")}`);
+        rule();
+        log(`Now, the AI also "refactors" ${bold(checkoutFile)} — a file it was never authorized to touch at all.`);
+        log("");
+        log(red(`  -   console.log(\`Charging \${user} for \${price}\`);`));
+        log(red(`  +   console.log(\`Charging \${user} for \${price * 1.1}\`);`));
+        log("");
+        log(dim("  A silent 10% surcharge on every payment. Nobody asked for this."));
+        // The authorized commit consumed the first intent, so the developer opens
+        // the next task on the same approved function before the AI continues.
+        intent = await realPlan(cartFile, approvedSymbol, "Continue discount work");
+        if (intent.humanGate !== "none") {
+            (0, core_1.recordRippleApproval)(demoDir, intent, {
+                gate: "before-risky-edit",
+                reason: "discount copy change only",
+                approvedBy: "Demo Human",
+            });
+        }
+        const rogueCode = initialCheckoutCode.replace('price}', 'price * 1.1}');
+        writeDemoFile(checkoutFile, rogueCode);
+        run(["add", checkoutFile]);
+        await sleep(3500);
+        log("\nDeveloper trusts the AI and runs " + bold("git commit") + ".");
+        await sleep(2000);
+        log(dim("\n⏳ Ripple pre-commit hook runs...\n"));
+        await sleep(1500);
+        const blockedGate = await runGate();
+        if (!jsonMode)
+            printDemoGateResult(blockedGate);
+        // Actually attempt the commit and let the real hook decide. Nothing below
+        // is asserted by the demo: the exit code and git log come from git.
+        const rogueCommit = runAllowFail(["commit", "-m", "refactor processCharge"]);
+        const headSubject = run(["log", "-1", "--pretty=%s"]).stdout?.trim();
+        if (rogueCommit.status !== 0) {
+            log("");
+            log(bgRed(`  ⛔ git commit REJECTED by Ripple (exit ${rogueCommit.status})  `));
+            log("");
+            log(dim(`  [git] HEAD is still: "${headSubject}"`));
+            log(bold(red(`  The 10% surcharge never entered git history.`)));
+        }
+        else {
+            log(bold(red(`\n⚠ Commit was NOT blocked (exit 0). HEAD: "${headSubject}"`)));
+        }
+        await sleep(4000);
+        // --- OPTIONAL: PUBLISH A PUBLIC RECEIPT ---
+        // Opt-in only. Must run before the finally block deletes the temp repo,
+        // because the commit SHA is read out of it.
+        const receiptUrl = await publishDemoReceipt({
+            publish: options.publish,
+            jsonMode,
+            demoDir,
+            gate: blockedGate,
+            readHeadSha: () => run(["rev-parse", "HEAD"]).stdout?.trim() ?? "unknown",
+            log,
+        });
+        // --- THE POINT ---
+        log("");
+        rule();
+        log("Prompts tell AI agents what to do.");
+        log(bold("Ripple enforces what they are allowed to do."));
+        log("The difference is a compliance trail your auditors can read.");
+        log("");
+        if (receiptUrl) {
+            log(`Public receipt:       ${bold(underline(receiptUrl))}`);
+        }
+        log(`Try it in your repo:  ${bold("npx @getripple/cli@latest init")}`);
+        log(`Dashboard:            ${bold(underline("https://ripple-cloud.vercel.app"))}`);
+        log("");
+        thick();
+        if (jsonMode) {
+            printJson({
+                protocol: "ripple-demo",
+                version: 1,
+                scenarios: [
+                    {
+                        name: "authorized-edit",
+                        decision: authorizedGate.decision,
+                        canContinue: authorizedGate.canContinue,
+                    },
+                    {
+                        name: "rogue-edit",
+                        decision: blockedGate.decision,
+                        canContinue: blockedGate.canContinue,
+                    },
+                ],
+                ...(receiptUrl ? { receiptUrl } : {}),
+            });
+        }
+    }
+    finally {
+        fs.rmSync(demoDir, { recursive: true, force: true });
+        if (!jsonMode) {
+            console.log(dim("\n(Demo complete. Temporary files cleaned up.)"));
+        }
+    }
+}
 async function main() {
     const { command, args, options } = parseCliArgs(process.argv.slice(2));
     const [arg] = args;
+    // --- ADD THIS NEW CASE ---
+    if (command === "demo") {
+        await demoCommand(options);
+        return;
+    }
+    // --- END NEW CASE ---
     if (!command || command === "--help" || command === "-h") {
         console.log(usage());
         return;