pulse-framework-cli 0.4.1

package/dist/commands/status.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStatusCommand = registerStatusCommand;
+const artifacts_js_1 = require("../lib/artifacts.js");
+const config_js_1 = require("../lib/config.js");
+const paths_js_1 = require("../lib/paths.js");
+const git_js_1 = require("../lib/git.js");
+const scanner_js_1 = require("../lib/scanner.js");
+const git_js_2 = require("../lib/git.js");
+const exec_js_1 = require("../lib/exec.js");
+const briefing_js_1 = require("../lib/briefing.js");
+function registerStatusCommand(program) {
+    program
+        .command("status")
+        .description("Quick overview: Preset/Profile, checkpoint time, changes, findings")
+        .option("--json", "Output as JSON")
+        .option("-v, --verbose", "Verbose output")
+        .option("--share", "Markdown format for Slack/Discord")
+        .action(async (opts) => {
+        const repoRoot = await (0, paths_js_1.findRepoRoot)(process.cwd());
+        if (!repoRoot) {
+            if (opts.json) {
+                // eslint-disable-next-line no-console
+                console.log(JSON.stringify({ error: "Not in a git repository" }));
+            }
+            else {
+                // eslint-disable-next-line no-console
+                console.log("❌ Not in a git repository");
+            }
+            process.exit(1);
+        }
+        const [state, config, gitStatus] = await Promise.all([
+            (0, artifacts_js_1.loadState)(repoRoot),
+            (0, config_js_1.loadConfig)(repoRoot),
+            (0, git_js_1.gitStatusPorcelain)(repoRoot),
+        ]);
+        // Calculate time since last checkpoint
+        const lastCp = state.lastCheckpointAt ? Date.parse(state.lastCheckpointAt) : null;
+        const now = Date.now();
+        const minutesSinceCheckpoint = lastCp && Number.isFinite(lastCp) ? Math.floor((now - lastCp) / 60000) : null;
+        // Count dirty files
+        const dirtyFiles = gitStatus
+            .split("\n")
+            .filter((line) => line.trim().length > 0).length;
+        // Scan for findings (if there are changes)
+        let findingsCount = 0;
+        let criticalCount = 0;
+        let warningCount = 0;
+        let linesChanged = 0;
+        let loopRisk = "LOW";
+        let recommendation = null;
+        if (dirtyFiles > 0 || opts.verbose) {
+            const [diffText, diffStat, diffNumstat, diffNameStatus, log, logWithFiles] = await Promise.all([
+                (0, git_js_2.gitDiffText)(repoRoot),
+                (0, git_js_2.gitDiffStat)(repoRoot),
+                (0, git_js_2.gitDiffNumstat)(repoRoot),
+                (0, git_js_2.gitDiffNameStatus)(repoRoot),
+                (0, git_js_1.gitLogOneline)(repoRoot, 15),
+                (0, exec_js_1.exec)("git", ["log", "--name-only", "--oneline", "-15"], { cwd: repoRoot }).then((r) => r.stdout),
+            ]);
+            const scan = (0, scanner_js_1.scanDiff)(config, { diffText, diffStat, diffNumstat, diffNameStatus });
+            // Add loop signals
+            const loopSignals = (0, scanner_js_1.detectLoopSignals)(log, logWithFiles);
+            for (const signal of loopSignals) {
+                scan.findings.push({
+                    severity: signal.severity,
+                    code: "LOOP_SIGNAL",
+                    message: signal.message,
+                    details: signal.details,
+                });
+            }
+            findingsCount = scan.findings.length;
+            criticalCount = scan.findings.filter((f) => f.severity === "critical").length;
+            warningCount = scan.findings.filter((f) => f.severity === "warn").length;
+            linesChanged = scan.stats.linesAdded + scan.stats.linesDeleted;
+            // Calculate risk for verbose/share
+            if (opts.verbose || opts.share) {
+                const scope = (0, briefing_js_1.calculateScopeCheck)(config, scan.stats);
+                const risk = (0, briefing_js_1.calculateRiskSummary)(scan);
+                const time = (0, briefing_js_1.calculateTimeSummary)(state.lastCheckpointAt, config.checkpointReminderMinutes ?? 30);
+                recommendation = (0, briefing_js_1.generateRecommendation)(scope, risk, time);
+                loopRisk = risk.loopRisk;
+            }
+        }
+        // Preset/Profile combo
+        const presetProfile = config.preset ? `${config.preset}/${state.profile}` : state.profile;
+        // ════════════════════════════════════════════════════════════════════════
+        // JSON Output
+        // ════════════════════════════════════════════════════════════════════════
+        if (opts.json) {
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify({
+                preset: config.preset || null,
+                profile: state.profile,
+                presetProfile,
+                lastCheckpointMinutesAgo: minutesSinceCheckpoint,
+                dirtyFiles,
+                linesChanged,
+                findings: findingsCount,
+                criticalFindings: criticalCount,
+                warningFindings: warningCount,
+                loopRisk,
+                recommendation: recommendation?.action || null,
+            }));
+            return;
+        }
+        // ════════════════════════════════════════════════════════════════════════
+        // Share Output (Markdown)
+        // ════════════════════════════════════════════════════════════════════════
+        if (opts.share) {
+            const lines = [];
+            lines.push(`**PULSE Status**`);
+            lines.push(``);
+            lines.push(`- Profile: \`${presetProfile}\``);
+            lines.push(`- Checkpoint: ${minutesSinceCheckpoint !== null ? `${minutesSinceCheckpoint} min` : "n/a"}`);
+            lines.push(`- Files: ${dirtyFiles}`);
+            lines.push(`- Lines: ${linesChanged}`);
+            lines.push(`- Findings: ${criticalCount} Critical, ${warningCount} Warnings`);
+            lines.push(`- Loop risk: ${loopRisk}`);
+            if (recommendation) {
+                lines.push(``);
+                lines.push(`**Recommendation:** ${recommendation.action.toUpperCase()}`);
+                lines.push(`> ${recommendation.reason}`);
+            }
+            // eslint-disable-next-line no-console
+            console.log(lines.join("\n"));
+            return;
+        }
+        // ════════════════════════════════════════════════════════════════════════
+        // Verbose Output
+        // ════════════════════════════════════════════════════════════════════════
+        if (opts.verbose) {
+            // eslint-disable-next-line no-console
+            console.log(`\n📊 PULSE Status\n`);
+            // Profile
+            const profileEmoji = state.profile === "concept" ? "🧠" : state.profile === "build" ? "🔨" : "🚨";
+            // eslint-disable-next-line no-console
+            console.log(`${profileEmoji} Profile: ${presetProfile}`);
+            // Checkpoint
+            if (minutesSinceCheckpoint !== null) {
+                const cpColor = minutesSinceCheckpoint > 30 ? "🔴" : minutesSinceCheckpoint > 15 ? "🟡" : "🟢";
+                // eslint-disable-next-line no-console
+                console.log(`${cpColor} Checkpoint: ${minutesSinceCheckpoint} min ago`);
+            }
+            else {
+                // eslint-disable-next-line no-console
+                console.log(`⚪ Checkpoint: none yet`);
+            }
+            // Files & Lines
+            // eslint-disable-next-line no-console
+            console.log(`📝 Files: ${dirtyFiles}`);
+            // eslint-disable-next-line no-console
+            console.log(`📏 Lines: ${linesChanged}`);
+            // Scope bars
+            if (dirtyFiles > 0) {
+                const filesPercent = Math.round((dirtyFiles / config.thresholds.warnMaxFilesChanged) * 100);
+                const linesPercent = Math.round((linesChanged / config.thresholds.warnMaxLinesChanged) * 100);
+                // eslint-disable-next-line no-console
+                console.log(`\n📊 Scope (${config.preset ?? "custom"} Preset):`);
+                // eslint-disable-next-line no-console
+                console.log(`   Files: ${(0, briefing_js_1.renderProgressBar)(filesPercent)} ${filesPercent}% (${dirtyFiles}/${config.thresholds.warnMaxFilesChanged})`);
+                // eslint-disable-next-line no-console
+                console.log(`   Lines: ${(0, briefing_js_1.renderProgressBar)(linesPercent)} ${linesPercent}% (${linesChanged}/${config.thresholds.warnMaxLinesChanged})`);
+            }
+            // Findings
+            // eslint-disable-next-line no-console
+            console.log(`\n🔍 Findings:`);
+            if (criticalCount > 0) {
+                // eslint-disable-next-line no-console
+                console.log(`   🚨 ${criticalCount} Critical`);
+            }
+            if (warningCount > 0) {
+                // eslint-disable-next-line no-console
+                console.log(`   ⚠️ ${warningCount} Warnings`);
+            }
+            if (findingsCount === 0) {
+                // eslint-disable-next-line no-console
+                console.log(`   ✅ No findings`);
+            }
+            // Loop Risk
+            const loopEmoji = loopRisk === "HIGH" ? "🔴" : loopRisk === "MEDIUM" ? "🟡" : "🟢";
+            // eslint-disable-next-line no-console
+            console.log(`\n${loopEmoji} Loop risk: ${loopRisk}`);
+            // Recommendation
+            if (recommendation) {
+                // eslint-disable-next-line no-console
+                console.log(`\n💡 Recommendation: ${recommendation.action.toUpperCase()}`);
+                // eslint-disable-next-line no-console
+                console.log(`   → ${recommendation.reason}`);
+                if (recommendation.command) {
+                    // eslint-disable-next-line no-console
+                    console.log(`   → ${recommendation.command}`);
+                }
+            }
+            // eslint-disable-next-line no-console
+            console.log(``);
+            return;
+        }
+        // ════════════════════════════════════════════════════════════════════════
+        // Default: One-liner Output
+        // ════════════════════════════════════════════════════════════════════════
+        const parts = [];
+        // Profile (with preset)
+        const profileEmoji = state.profile === "concept" ? "🧠" : state.profile === "build" ? "🔨" : "🚨";
+        parts.push(`${profileEmoji} ${presetProfile}`);
+        // Last checkpoint
+        if (minutesSinceCheckpoint !== null) {
+            const cpColor = minutesSinceCheckpoint > 30 ? "🔴" : minutesSinceCheckpoint > 15 ? "🟡" : "🟢";
+            parts.push(`${cpColor} ${minutesSinceCheckpoint}m`);
+        }
+        else {
+            parts.push("⚪ no cp");
+        }
+        // Dirty files
+        if (dirtyFiles > 0) {
+            parts.push(`📝 ${dirtyFiles} files`);
+        }
+        else {
+            parts.push("✨ clean");
+        }
+        // Findings
+        if (criticalCount > 0) {
+            parts.push(`🚨 ${criticalCount} critical`);
+        }
+        else if (findingsCount > 0) {
+            parts.push(`⚠️ ${findingsCount} warn`);
+        }
+        else if (dirtyFiles > 0) {
+            parts.push("✅ ok");
+        }
+        // eslint-disable-next-line no-console
+        console.log(parts.join(" | "));
+        // Hint if overdue
+        if (minutesSinceCheckpoint !== null && minutesSinceCheckpoint > 30 && dirtyFiles > 0) {
+            // eslint-disable-next-line no-console
+            console.log("\n💡 Tip: `pulse checkpoint` to commit");
+        }
+    });
+}

package/dist/commands/watch.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerWatchCommand(program: Command): void;

package/dist/commands/watch.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWatchCommand = registerWatchCommand;
+const chokidar_1 = __importDefault(require("chokidar"));
+const node_path_1 = __importDefault(require("node:path"));
+const config_js_1 = require("../lib/config.js");
+const artifacts_js_1 = require("../lib/artifacts.js");
+const paths_js_1 = require("../lib/paths.js");
+const git_js_1 = require("../lib/git.js");
+const notifications_js_1 = require("../lib/notifications.js");
+function registerWatchCommand(program) {
+    program
+        .command("watch")
+        .alias("w") // Kurzform: pulse w
+        .description("Background watcher: 30-min timer + checkpoint reminders (macOS notifications)")
+        .option("--minutes <n>", "Minutes between checkpoint reminders", "30")
+        .option("--poll-seconds <n>", "Polling interval seconds", "30")
+        .action(async (opts) => {
+        const repoRoot = await (0, paths_js_1.findRepoRoot)(process.cwd());
+        if (!repoRoot)
+            throw new Error("Not inside a git repository.");
+        const config = await (0, config_js_1.loadConfig)(repoRoot);
+        const minutes = Math.max(1, Number(opts.minutes ?? "30"));
+        const pollSeconds = Math.max(5, Number(opts.pollSeconds ?? "30"));
+        await (0, notifications_js_1.notify)(config.notifications, "Pulse watch started", `Checkpoint reminder every ${minutes} minutes. Poll: ${pollSeconds}s.`);
+        const watcher = chokidar_1.default.watch(repoRoot, {
+            ignored: [
+                /(^|[\/\\])\.git/,
+                /(^|[\/\\])node_modules/,
+                /(^|[\/\\])dist/,
+                /(^|[\/\\])build/,
+                /(^|[\/\\])coverage/,
+                /(^|[\/\\])\.pulse/,
+            ],
+            ignoreInitial: true,
+        });
+        let dirtySince = null;
+        let lastReminderAt = Date.now();
+        watcher.on("all", async () => {
+            const st = await (0, git_js_1.gitStatusPorcelain)(repoRoot);
+            const dirty = st.trim().length > 0;
+            if (dirty && dirtySince == null)
+                dirtySince = Date.now();
+            if (!dirty)
+                dirtySince = null;
+        });
+        // Polling loop (git status + checkpoint age)
+        const interval = setInterval(async () => {
+            const st = await (0, git_js_1.gitStatusPorcelain)(repoRoot);
+            const dirty = st.trim().length > 0;
+            if (dirty && dirtySince == null)
+                dirtySince = Date.now();
+            if (!dirty)
+                dirtySince = null;
+            const state = await (0, artifacts_js_1.loadState)(repoRoot);
+            const lastCp = state.lastCheckpointAt ? Date.parse(state.lastCheckpointAt) : null;
+            const now = Date.now();
+            const minutesSinceLastCp = lastCp && Number.isFinite(lastCp) ? Math.floor((now - lastCp) / 60000) : null;
+            const shouldRemind = now - lastReminderAt >= minutes * 60_000;
+            if (!shouldRemind)
+                return;
+            lastReminderAt = now;
+            if (!dirty) {
+                await (0, notifications_js_1.notify)(config.notifications, "Pulse checkpoint", "Repo is clean. No checkpoint needed right now.");
+                return;
+            }
+            const dirtyMins = dirtySince ? Math.floor((now - dirtySince) / 60000) : null;
+            await (0, notifications_js_1.notify)(config.notifications, "Pulse checkpoint now", [
+                `You have uncommitted changes.`,
+                dirtyMins != null ? `Dirty for ~${dirtyMins} min.` : "",
+                minutesSinceLastCp != null ? `Last checkpoint: ${minutesSinceLastCp} min ago.` : "No checkpoint recorded yet.",
+                `Run: pulse checkpoint`,
+            ]
+                .filter(Boolean)
+                .join("\n"));
+        }, pollSeconds * 1000);
+        const cleanup = async () => {
+            clearInterval(interval);
+            await watcher.close().catch(() => { });
+        };
+        process.on("SIGINT", async () => {
+            await cleanup();
+            // eslint-disable-next-line no-console
+            console.log("Pulse watch stopped.");
+            process.exit(0);
+        });
+        process.on("SIGTERM", async () => {
+            await cleanup();
+            process.exit(0);
+        });
+        // Keep process alive
+        // eslint-disable-next-line no-console
+        console.log(`Watching ${node_path_1.default.basename(repoRoot)} ... (Ctrl+C to stop)`);
+    });
+}

package/dist/hooks/install.d.ts

@@ -0,0 +1 @@
+export declare function installHooks(repoRoot: string): Promise<void>;

package/dist/hooks/install.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installHooks = installHooks;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+async function ensureExecutable(filePath) {
+    try {
+        await promises_1.default.chmod(filePath, 0o755);
+    }
+    catch {
+        // ignore
+    }
+}
+async function installHooks(repoRoot) {
+    const hooksDir = node_path_1.default.join(repoRoot, ".git", "hooks");
+    await promises_1.default.mkdir(hooksDir, { recursive: true });
+    const preCommit = node_path_1.default.join(hooksDir, "pre-commit");
+    const postCommit = node_path_1.default.join(hooksDir, "post-commit");
+    const prePush = node_path_1.default.join(hooksDir, "pre-push");
+    await promises_1.default.writeFile(preCommit, `#!/bin/sh
+# Pulse mixed enforcement:
+# - blocks CRITICAL findings (secrets, mass deletes) - exit code 2
+# - warns on other findings but allows commit - exit code 1
+#
+# Bypass for this commit:
+#   PULSE_SKIP_HOOKS=1 git commit ...
+
+if [ "$PULSE_SKIP_HOOKS" = "1" ]; then
+  exit 0
+fi
+
+pulse doctor --staged --hook pre-commit
+EXIT_CODE=$?
+
+# Only block on CRITICAL (exit 2), allow warnings (exit 1)
+if [ $EXIT_CODE -eq 2 ]; then
+  echo ""
+  echo "❌ Commit blocked by PULSE (critical findings)"
+  echo "   Fix issues or use: PULSE_SKIP_HOOKS=1 git commit ..."
+  exit 2
+fi
+
+exit 0
+`, "utf8");
+    await ensureExecutable(preCommit);
+    // Post-commit: Update checkpoint timestamp so timer resets on every commit
+    await promises_1.default.writeFile(postCommit, `#!/bin/sh
+# Pulse: Track every commit as a checkpoint (reset timer)
+# This updates .pulse/state.json with current timestamp
+
+PULSE_DIR=".pulse"
+STATE_FILE="$PULSE_DIR/state.json"
+
+if [ -d "$PULSE_DIR" ]; then
+  TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+  
+  if [ -f "$STATE_FILE" ]; then
+    # Update existing state.json
+    if command -v node >/dev/null 2>&1; then
+      node -e "
+        const fs = require('fs');
+        const state = JSON.parse(fs.readFileSync('$STATE_FILE', 'utf8'));
+        state.lastCheckpointAt = '$TIMESTAMP';
+        fs.writeFileSync('$STATE_FILE', JSON.stringify(state, null, 2));
+      " 2>/dev/null || true
+    fi
+  else
+    # Create new state.json
+    echo '{"version":1,"profile":"build","lastCheckpointAt":"'$TIMESTAMP'"}' > "$STATE_FILE"
+  fi
+fi
+`, "utf8");
+    await ensureExecutable(postCommit);
+    await promises_1.default.writeFile(prePush, `#!/bin/sh
+set -e
+
+# Pulse safeguard: never push without explicit permission.
+# Allow push explicitly by running:
+#   PULSE_ALLOW_PUSH=1 git push ...
+
+pulse doctor --hook pre-push
+`, "utf8");
+    await ensureExecutable(prePush);
+    // eslint-disable-next-line no-console
+    console.log(`Installed git hooks:\n- ${preCommit}\n- ${postCommit}\n- ${prePush}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const init_js_1 = require("./commands/init.js");
+const profile_js_1 = require("./commands/profile.js");
+const status_js_1 = require("./commands/status.js");
+const start_js_1 = require("./commands/start.js");
+const correct_js_1 = require("./commands/correct.js");
+const review_js_1 = require("./commands/review.js");
+const escalate_js_1 = require("./commands/escalate.js");
+const checkpoint_js_1 = require("./commands/checkpoint.js");
+const doctor_js_1 = require("./commands/doctor.js");
+const learn_js_1 = require("./commands/learn.js");
+const watch_js_1 = require("./commands/watch.js");
+const run_js_1 = require("./commands/run.js");
+const reset_js_1 = require("./commands/reset.js");
+const program = new commander_1.Command();
+program
+    .name("pulse")
+    .description("Pulse Toolkit CLI: controlled agentic development loops with guardrails, checkpoints, and escalation.")
+    .version("0.3.0");
+(0, init_js_1.registerInitCommand)(program);
+(0, status_js_1.registerStatusCommand)(program);
+(0, profile_js_1.registerProfileCommand)(program);
+(0, start_js_1.registerStartCommand)(program);
+(0, run_js_1.registerRunCommand)(program);
+(0, correct_js_1.registerCorrectCommand)(program);
+(0, review_js_1.registerReviewCommand)(program);
+(0, escalate_js_1.registerEscalateCommand)(program);
+(0, checkpoint_js_1.registerCheckpointCommand)(program);
+(0, doctor_js_1.registerDoctorCommand)(program);
+(0, learn_js_1.registerLearnCommand)(program);
+(0, watch_js_1.registerWatchCommand)(program);
+(0, reset_js_1.registerResetCommand)(program);
+program.parseAsync(process.argv).catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(err?.stack || String(err));
+    process.exit(1);
+});

package/dist/lib/artifacts.d.ts

@@ -0,0 +1,7 @@
+import type { PulseState } from "./types.js";
+export type ArtifactKind = "pulses" | "reviews" | "escalations" | "worklogs";
+export declare function timestampId(d?: Date): string;
+export declare function ensurePulseDirs(repoRoot: string): Promise<void>;
+export declare function writeArtifact(repoRoot: string, kind: ArtifactKind, name: string, content: string): Promise<string>;
+export declare function loadState(repoRoot: string): Promise<PulseState>;
+export declare function saveState(repoRoot: string, next: PulseState): Promise<void>;

package/dist/lib/artifacts.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timestampId = timestampId;
+exports.ensurePulseDirs = ensurePulseDirs;
+exports.writeArtifact = writeArtifact;
+exports.loadState = loadState;
+exports.saveState = saveState;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const paths_js_1 = require("./paths.js");
+function timestampId(d = new Date()) {
+    // 2026-01-05T12-34-56Z (filename-safe)
+    return d.toISOString().replace(/:/g, "-");
+}
+async function ensurePulseDirs(repoRoot) {
+    const base = (0, paths_js_1.pulseDir)(repoRoot);
+    await promises_1.default.mkdir(base, { recursive: true });
+    await promises_1.default.mkdir(node_path_1.default.join(base, "pulses"), { recursive: true });
+    await promises_1.default.mkdir(node_path_1.default.join(base, "reviews"), { recursive: true });
+    await promises_1.default.mkdir(node_path_1.default.join(base, "escalations"), { recursive: true });
+    await promises_1.default.mkdir(node_path_1.default.join(base, "worklogs"), { recursive: true });
+}
+async function writeArtifact(repoRoot, kind, name, content) {
+    await ensurePulseDirs(repoRoot);
+    const p = node_path_1.default.join((0, paths_js_1.pulseDir)(repoRoot), kind, name);
+    await promises_1.default.writeFile(p, content, "utf8");
+    return p;
+}
+async function loadState(repoRoot) {
+    try {
+        const raw = await promises_1.default.readFile((0, paths_js_1.stateFile)(repoRoot), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+            return {
+                version: 1,
+                profile: parsed.profile ?? "build",
+                lastCheckpointAt: parsed.lastCheckpointAt,
+            };
+        }
+    }
+    catch {
+        // ignore
+    }
+    return { version: 1, profile: "build" };
+}
+async function saveState(repoRoot, next) {
+    await ensurePulseDirs(repoRoot);
+    await promises_1.default.writeFile((0, paths_js_1.stateFile)(repoRoot), JSON.stringify(next, null, 2) + "\n", "utf8");
+}

package/dist/lib/briefing.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Briefing Library - Aggregates data for Decision Briefings
+ */
+import type { PulseConfig } from "./types.js";
+import type { ScanResult, Finding } from "./scanner.js";
+export type ScopeCheck = {
+    files: {
+        current: number;
+        max: number;
+        percent: number;
+    };
+    lines: {
+        current: number;
+        max: number;
+        percent: number;
+    };
+    deletes: {
+        current: number;
+        max: number;
+        percent: number;
+    };
+    exceeded: boolean;
+    exceededFields: string[];
+};
+export type RiskSummary = {
+    criticalCount: number;
+    warningCount: number;
+    findings: Finding[];
+    loopRisk: "LOW" | "MEDIUM" | "HIGH";
+    loopSignals: string[];
+};
+export type TimeSummary = {
+    minutesSinceCheckpoint: number | null;
+    checkpointOverdue: boolean;
+    sessionMinutes: number | null;
+};
+export type Recommendation = {
+    action: "approve" | "checkpoint" | "escalate" | "stop";
+    reason: string;
+    command?: string;
+};
+export type DecisionBriefing = {
+    preset: string | null;
+    profile: string;
+    scope: ScopeCheck;
+    risk: RiskSummary;
+    time: TimeSummary;
+    recommendation: Recommendation;
+};
+/**
+ * Calculate scope check against preset limits
+ */
+export declare function calculateScopeCheck(config: PulseConfig, stats: {
+    filesChanged: number;
+    linesAdded: number;
+    linesDeleted: number;
+}): ScopeCheck;
+/**
+ * Summarize risks from scan results
+ */
+export declare function calculateRiskSummary(scanResult: ScanResult): RiskSummary;
+/**
+ * Calculate time-based metrics
+ */
+export declare function calculateTimeSummary(lastCheckpointAt: string | undefined, checkpointReminderMinutes: number): TimeSummary;
+/**
+ * Generate recommendation based on all factors
+ */
+export declare function generateRecommendation(scope: ScopeCheck, risk: RiskSummary, time: TimeSummary): Recommendation;
+/**
+ * Render progress bar
+ */
+export declare function renderProgressBar(percent: number, width?: number): string;
+/**
+ * Render full Decision Briefing to terminal
+ */
+export declare function renderBriefing(briefing: DecisionBriefing): string;