@vyuhlabs/dxkit 2.12.0 → 2.13.1

package/dist/loop/ledger.js

@@ -0,0 +1,201 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEDGER_FILE = exports.LEDGER_DIR = exports.LEDGER_SCHEMA_VERSION = void 0;
+exports.buildLedgerEvent = buildLedgerEvent;
+exports.appendLedgerEvent = appendLedgerEvent;
+exports.readLedger = readLedger;
+exports.clearLedger = clearLedger;
+exports.summarizeLedger = summarizeLedger;
+/**
+ * Loop ledger — an append-only audit trail of postflight (Stop-gate)
+ * events for autonomous coding loops.
+ *
+ * Every time the Stop-gate runs (whether it allows the loop to stop or
+ * blocks it on net-new findings), it appends one line to
+ * `.dxkit/loop/ledger.jsonl`. The ledger answers "what did the loop
+ * actually do?" — how many completions were blocked, how many net-new
+ * findings, and whether the agent repaired after a block.
+ *
+ * This is deliberately NOT a dashboard. It is a flat JSONL file so a
+ * loop can write to it from any process without coordination, and a
+ * human (or a benchmark harness) can `cat` / `jq` it directly.
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Bump only on a breaking change to the event shape. */
+exports.LEDGER_SCHEMA_VERSION = 1;
+/** Relative location of the ledger inside a repo. */
+exports.LEDGER_DIR = path.join('.dxkit', 'loop');
+exports.LEDGER_FILE = path.join(exports.LEDGER_DIR, 'ledger.jsonl');
+/** Best-effort current branch; empty string when not derivable. */
+function gitBranch(cwd) {
+    try {
+        return (0, child_process_1.execFileSync)('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/** Best-effort current commit SHA; empty string when not derivable. */
+function gitCommit(cwd) {
+    try {
+        return (0, child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Fill in the repo-derived fields (branch, commit) and stamp the
+ * schema version + timestamp, so callers only supply the outcome.
+ */
+function buildLedgerEvent(cwd, fields) {
+    return {
+        schema_version: exports.LEDGER_SCHEMA_VERSION,
+        timestamp: new Date().toISOString(),
+        event: 'Stop',
+        branch: fields.branch ?? gitBranch(cwd),
+        commit: fields.commit ?? gitCommit(cwd),
+        ...fields,
+    };
+}
+/**
+ * Append one event to the ledger. Creates `.dxkit/loop/` on demand.
+ * Best-effort: a ledger write must never abort the Stop-gate (the
+ * gate's verdict matters more than its audit line), so failures are
+ * swallowed and reported via the return value.
+ */
+function appendLedgerEvent(cwd, event) {
+    try {
+        const dir = path.join(cwd, exports.LEDGER_DIR);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.appendFileSync(path.join(cwd, exports.LEDGER_FILE), JSON.stringify(event) + '\n', 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read every ledger event. Returns [] when the ledger is absent. */
+function readLedger(cwd) {
+    const file = path.join(cwd, exports.LEDGER_FILE);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            out.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip a corrupt line rather than failing the whole read — the
+            // ledger is append-only and a partial write shouldn't blind the
+            // summary to every other event.
+        }
+    }
+    return out;
+}
+/** Remove the ledger file. Returns true when a file was deleted. */
+function clearLedger(cwd) {
+    try {
+        fs.rmSync(path.join(cwd, exports.LEDGER_FILE));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reduce a list of events to the audit-trail summary. Repair detection
+ * is per-session: a session counts as "repaired" if it has at least one
+ * blocked event AND a strictly-later allowed event with a passing
+ * guardrail. Order is taken from event position (the ledger is
+ * append-only, so file order is chronological).
+ */
+function summarizeLedger(events) {
+    let allowed = 0;
+    let blocked = 0;
+    let netNewBlocked = 0;
+    // Per-session timeline of (blocked?, repaired?) — repaired means a
+    // clean allowed+pass event appeared after the session's first block.
+    const blockedAt = new Map(); // session → index of first block
+    const repairedSessions = new Set();
+    const blockedSessions = new Set();
+    events.forEach((e, idx) => {
+        if (e.allowed)
+            allowed++;
+        else {
+            blocked++;
+            netNewBlocked += e.net_new_findings;
+        }
+        const sid = e.session_id || '(unknown)';
+        if (!e.allowed) {
+            blockedSessions.add(sid);
+            if (!blockedAt.has(sid))
+                blockedAt.set(sid, idx);
+        }
+        else if (e.guardrail_status === 'pass' &&
+            blockedAt.has(sid) &&
+            idx > blockedAt.get(sid)) {
+            repairedSessions.add(sid);
+        }
+    });
+    return {
+        total: events.length,
+        allowed,
+        blocked,
+        netNewBlocked,
+        repairedAfterBlock: repairedSessions.size,
+        unrepairedSessions: [...blockedSessions].filter((s) => !repairedSessions.has(s)).length,
+    };
+}
+//# sourceMappingURL=ledger.js.map

package/dist/loop/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/loop/ledger.ts"],"names":[],"mappings":"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"}

package/dist/loop/policy.d.ts

@@ -0,0 +1,35 @@
+import { type BrownfieldPolicy } from '../baseline/policy';
+/**
+ * The two shipped loop postures.
+ *   - `security-only` (default): block only on net-new secrets + crit/high
+ *     security + crit/high reachable dependency vulns. test-gap + quality
+ *     are NOT blocked — they warn. Cost-bounded; safe to run unattended.
+ *   - `full-debt`: block on every net-new finding (adds test-gap +
+ *     quality). Exhaustive but can drive an open-ended repair; opt-in.
+ */
+export type LoopPreset = 'security-only' | 'full-debt';
+/** The cost-bounded default — the posture an unattended loop gets unless
+ *  the repo explicitly opts into `full-debt`. */
+export declare const DEFAULT_LOOP_PRESET: LoopPreset;
+/** Resolved loop posture: the policy the Stop-gate hands to the guardrail,
+ *  plus the preset name that produced it (recorded in the ledger). */
+export interface ResolvedLoopPolicy {
+    readonly policy: BrownfieldPolicy;
+    readonly preset: LoopPreset;
+}
+/**
+ * Resolve the active loop preset. Precedence (mirrors the other
+ * `DXKIT_LOOP_*` knobs the Stop-gate already honours):
+ *   1. `DXKIT_LOOP_PRESET` env var (benchmark / CI override).
+ *   2. `.dxkit/policy.json` → `loop.preset`.
+ *   3. `DEFAULT_LOOP_PRESET` (`security-only`).
+ */
+export declare function resolveLoopPreset(cwd: string): LoopPreset;
+/**
+ * Build the loop-scoped policy: the repo's base `BrownfieldPolicy`
+ * (confidence thresholds, baseline mode, drift handling preserved) with
+ * its `block` list + `blockRules` REPLACED by the active preset's. Only
+ * the Stop-gate calls this — see the scope note at the top of the file.
+ */
+export declare function resolveLoopPolicy(cwd: string): ResolvedLoopPolicy;
+//# sourceMappingURL=policy.d.ts.map

package/dist/loop/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/loop/policy.ts"],"names":[],"mappings":"AA0BA,OAAO,EAEL,KAAK,gBAAgB,EAGtB,MAAM,oBAAoB,CAAC;AAG5B;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,WAAW,CAAC;AAEvD;iDACiD;AACjD,eAAO,MAAM,mBAAmB,EAAE,UAA4B,CAAC;AA8C/D;sEACsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAuBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAIzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAYjE"}

package/dist/loop/policy.js

@@ -0,0 +1,151 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LOOP_PRESET = void 0;
+exports.resolveLoopPreset = resolveLoopPreset;
+exports.resolveLoopPolicy = resolveLoopPolicy;
+/**
+ * Loop policy presets — a curated blocking posture scoped to autonomous
+ * coding loops ONLY.
+ *
+ * ──────────────────────────────────────────────────────────────────────
+ *  SCOPE: this layer is read by exactly one consumer — the Stop-gate
+ *  (`src/loop/stop-gate.ts`). The CI / PR guardrail (`vyuh-dxkit baseline
+ *  check`) and `createBaseline` resolve the shared `BrownfieldPolicy`
+ *  directly via `resolvePolicy` and NEVER read `loop.preset`. So setting a
+ *  preset changes how an unattended loop blocks WITHOUT silently
+ *  downgrading a repo's CI posture. The `loop.*` namespace in
+ *  `.dxkit/policy.json` and the `Loop`-prefixed names here both signal
+ *  that boundary.
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * Why a loop-only posture exists: in CI a guardrail block just fails a
+ * check a human then reads — blocking on every debt class (test-gap,
+ * quality) is fine. In a loop a block instead FEEDS THE MODEL a repair
+ * instruction, so blocking on open-ended debt makes the agent grind on it
+ * unattended (writing tests / refactoring until the gap closes), which is
+ * expensive and unbounded. The default loop posture therefore blocks only
+ * on the unambiguous, must-fix security class; the open-ended debt classes
+ * are an explicit opt-in.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const policy_1 = require("../baseline/policy");
+/** The cost-bounded default — the posture an unattended loop gets unless
+ *  the repo explicitly opts into `full-debt`. */
+exports.DEFAULT_LOOP_PRESET = 'security-only';
+/** The security class: secrets, crit/high SAST, crit/high reachable dep
+ *  vulns. Shared by both presets — full-debt is this plus the debt rules. */
+const SECURITY_BLOCK_RULES = {
+    newSecret: true,
+    newCriticalSecurity: true,
+    newHighSecurity: true,
+    newCriticalDependencyVulnerability: true,
+    newHighReachableDependencyVulnerability: true,
+    // Open-ended debt — OFF in security-only (warn, never block in a loop).
+    newUntestedChangedSource: false,
+    newSevereQualityIssueInChangedFiles: false,
+};
+const PRESETS = Object.freeze({
+    'security-only': {
+        // Empty generic block list: nothing auto-blocks by status alone, so
+        // test-gap + quality net-new findings warn but never block the loop.
+        // Blocking comes solely from SECURITY_BLOCK_RULES.
+        block: [],
+        blockRules: SECURITY_BLOCK_RULES,
+    },
+    'full-debt': {
+        // Any net-new finding blocks (generic `added`), plus every escalation.
+        block: ['added'],
+        blockRules: {
+            ...SECURITY_BLOCK_RULES,
+            newUntestedChangedSource: true,
+            newSevereQualityIssueInChangedFiles: true,
+        },
+    },
+});
+function isLoopPreset(v) {
+    return v === 'security-only' || v === 'full-debt';
+}
+/**
+ * Read `loop.preset` from `.dxkit/policy.json`. Best-effort: a missing /
+ * malformed file or absent `loop` block yields `undefined` so the caller
+ * falls back to the default. Read here (not via `resolvePolicy`) so the
+ * loop concept stays out of the shared `BrownfieldPolicy` schema.
+ */
+function readPresetFromPolicyFile(cwd) {
+    try {
+        const raw = fs.readFileSync(path.join(cwd, policy_1.DEFAULT_POLICY_FILENAME), 'utf8');
+        const parsed = JSON.parse(raw);
+        const preset = parsed.loop?.preset;
+        return isLoopPreset(preset) ? preset : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the active loop preset. Precedence (mirrors the other
+ * `DXKIT_LOOP_*` knobs the Stop-gate already honours):
+ *   1. `DXKIT_LOOP_PRESET` env var (benchmark / CI override).
+ *   2. `.dxkit/policy.json` → `loop.preset`.
+ *   3. `DEFAULT_LOOP_PRESET` (`security-only`).
+ */
+function resolveLoopPreset(cwd) {
+    const env = process.env.DXKIT_LOOP_PRESET;
+    if (isLoopPreset(env))
+        return env;
+    return readPresetFromPolicyFile(cwd) ?? exports.DEFAULT_LOOP_PRESET;
+}
+/**
+ * Build the loop-scoped policy: the repo's base `BrownfieldPolicy`
+ * (confidence thresholds, baseline mode, drift handling preserved) with
+ * its `block` list + `blockRules` REPLACED by the active preset's. Only
+ * the Stop-gate calls this — see the scope note at the top of the file.
+ */
+function resolveLoopPolicy(cwd) {
+    const base = (0, policy_1.resolvePolicy)(undefined, cwd);
+    const preset = resolveLoopPreset(cwd);
+    const def = PRESETS[preset];
+    return {
+        preset,
+        policy: {
+            ...base,
+            block: def.block,
+            blockRules: def.blockRules,
+        },
+    };
+}
+//# sourceMappingURL=policy.js.map

package/dist/loop/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/loop/policy.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+HA,8CAIC;AAQD,8CAYC;AAvJD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,uCAAyB;AACzB,2CAA6B;AAC7B,+CAK4B;AAa5B;iDACiD;AACpC,QAAA,mBAAmB,GAAe,eAAe,CAAC;AAc/D;6EAC6E;AAC7E,MAAM,oBAAoB,GAAyB;IACjD,SAAS,EAAE,IAAI;IACf,mBAAmB,EAAE,IAAI;IACzB,eAAe,EAAE,IAAI;IACrB,kCAAkC,EAAE,IAAI;IACxC,uCAAuC,EAAE,IAAI;IAC7C,wEAAwE;IACxE,wBAAwB,EAAE,KAAK;IAC/B,mCAAmC,EAAE,KAAK;CAC3C,CAAC;AAEF,MAAM,OAAO,GAA4C,MAAM,CAAC,MAAM,CAAC;IACrE,eAAe,EAAE;QACf,oEAAoE;QACpE,qEAAqE;QACrE,mDAAmD;QACnD,KAAK,EAAE,EAAE;QACT,UAAU,EAAE,oBAAoB;KACjC;IACD,WAAW,EAAE;QACX,uEAAuE;QACvE,KAAK,EAAE,CAAC,OAAO,CAAC;QAChB,UAAU,EAAE;YACV,GAAG,oBAAoB;YACvB,wBAAwB,EAAE,IAAI;YAC9B,mCAAmC,EAAE,IAAI;SAC1C;KACF;CACF,CAAC,CAAC;AASH,SAAS,YAAY,CAAC,CAAU;IAC9B,OAAO,CAAC,KAAK,eAAe,IAAI,CAAC,KAAK,WAAW,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,SAAS,wBAAwB,CAAC,GAAW;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,gCAAuB,CAAC,EAAE,MAAM,CAAC,CAAC;QAC7E,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoC,CAAC;QAClE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC;QACnC,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,GAAW;IAC3C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAC1C,IAAI,YAAY,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAClC,OAAO,wBAAwB,CAAC,GAAG,CAAC,IAAI,2BAAmB,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,GAAW;IAC3C,MAAM,IAAI,GAAG,IAAA,sBAAa,EAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO;QACL,MAAM;QACN,MAAM,EAAE;YACN,GAAG,IAAI;YACP,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,UAAU,EAAE,GAAG,CAAC,UAAU;SAC3B;KACF,CAAC;AACJ,CAAC"}

package/dist/loop/scaffold.d.ts

@@ -0,0 +1,28 @@
+import type { ShipInstallResult } from '../ship-installers';
+import { type LoopPreset } from './policy';
+/** The command Claude Code runs on Stop. Built from the canonical CLI
+ *  invocation (`src/self-invocation.ts`) so the installer, doctor, and any
+ *  future tooling agree on the exact string and the loop Stop hook is a
+ *  registered self-invocation surface (devDependency + doctor coverage). */
+export declare const STOP_HOOK_COMMAND: string;
+interface LoopScaffoldOpts {
+    /**
+     * Explicit loop posture to write into `.dxkit/policy.json`. When set
+     * (init with `--loop-preset`), it OVERRIDES any existing preset. When
+     * omitted (bare init re-run, or update), an existing preset is PRESERVED
+     * and `security-only` is seeded only if none exists — so an upgrade
+     * never silently resets a user's chosen posture.
+     */
+    readonly preset?: LoopPreset;
+}
+/** True when `.claude/settings.json` already registers the Stop-gate. Used
+ *  by `update`'s install-flag detection so an upgrade refreshes the loop
+ *  surface only on repos that opted into it. */
+export declare function isClaudeLoopInstalled(cwd: string): boolean;
+/**
+ * Scaffold the loop pack into `cwd`. Additive + idempotent: safe to run on
+ * a fresh repo or re-run on one that already has settings/CLAUDE.md/policy.
+ */
+export declare function installClaudeLoop(cwd: string, opts?: LoopScaffoldOpts): ShipInstallResult;
+export {};
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/loop/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/loop/scaffold.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAuB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAGhE;;;4EAG4E;AAC5E,eAAO,MAAM,iBAAiB,QAA6B,CAAC;AA0B5D,UAAU,gBAAgB;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;CAC9B;AAWD;;gDAEgD;AAChD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAY1D;AA2ID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,iBAAiB,CAM7F"}

package/dist/loop/scaffold.js

@@ -0,0 +1,224 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOP_HOOK_COMMAND = void 0;
+exports.isClaudeLoopInstalled = isClaudeLoopInstalled;
+exports.installClaudeLoop = installClaudeLoop;
+/**
+ * `init --claude-loop` scaffolding — wires the loop pack into a repo
+ * ADDITIVELY. None of these writers clobber a user's file:
+ *
+ *   - `.claude/settings.json`: deep-merge our Stop hook into `hooks.Stop[]`,
+ *     preserving every existing hook / permission / key. Idempotent.
+ *   - `CLAUDE.md`: upsert a sentinel-delimited managed block, never
+ *     touching prose outside the markers. Idempotent.
+ *   - `.dxkit/policy.json`: set `loop.preset`, preserving all other policy.
+ *
+ * Each writer reads the existing file, mutates the minimum, and writes
+ * back; a malformed existing file is left untouched and surfaced as a
+ * note rather than overwritten. This mirrors the additive `.gitignore`
+ * installer (`ship-installers.ts:installIgnoreFiles`), extended to JSON +
+ * a Markdown managed block.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const policy_1 = require("./policy");
+const self_invocation_1 = require("../self-invocation");
+/** The command Claude Code runs on Stop. Built from the canonical CLI
+ *  invocation (`src/self-invocation.ts`) so the installer, doctor, and any
+ *  future tooling agree on the exact string and the loop Stop hook is a
+ *  registered self-invocation surface (devDependency + doctor coverage). */
+exports.STOP_HOOK_COMMAND = (0, self_invocation_1.dxkitCli)('hook stop-gate');
+/** Sentinel markers bounding the dxkit-managed region of CLAUDE.md. Only
+ *  the text between them is ever rewritten. */
+const CLAUDE_BLOCK_START = '<!-- dxkit:loop:start -->';
+const CLAUDE_BLOCK_END = '<!-- dxkit:loop:end -->';
+/** Preset-agnostic loop norm. Points at `.dxkit/policy.json` as the
+ *  source of truth for the active posture, so this prose stays correct
+ *  when the preset is switched without re-running init. */
+const CLAUDE_LOOP_NORM = `## Autonomous loop safety (dxkit)
+
+This repo runs coding loops behind the dxkit Stop-gate: when a loop tries
+to stop, \`vyuh-dxkit hook stop-gate\` re-runs the guardrail and blocks
+completion if the branch introduced net-new findings, handing them back
+for repair. Loop norms:
+
+- Fix the net-new finding the gate reports. Do NOT refresh the baseline to
+  clear a block, and do NOT fix unrelated pre-existing debt — the gate
+  only asks for what this branch introduced.
+- The blocking posture is \`loop.preset\` in \`.dxkit/policy.json\`:
+  \`security-only\` (default) blocks net-new secrets + crit/high security +
+  reachable dependency vulns; \`full-debt\` also blocks test-gap + quality.
+- \`vyuh-dxkit loop doctor\` verifies the loop is wired safely;
+  \`vyuh-dxkit loop ledger summarize\` reports what the gate did.`;
+/** True when `.claude/settings.json` already registers the Stop-gate. Used
+ *  by `update`'s install-flag detection so an upgrade refreshes the loop
+ *  surface only on repos that opted into it. */
+function isClaudeLoopInstalled(cwd) {
+    try {
+        const raw = fs.readFileSync(path.join(cwd, '.claude', 'settings.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        return (parsed.hooks?.Stop ?? []).some((e) => (e.hooks ?? []).some((h) => typeof h.command === 'string' && /hook\s+stop-gate/.test(h.command)));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Merge the Stop hook into `.claude/settings.json`. Preserves all existing
+ * settings; idempotent (no-op when our hook is already registered). A
+ * malformed existing file is left intact and reported via `sidecars`.
+ */
+function mergeStopHook(cwd, result) {
+    const rel = path.join('.claude', 'settings.json');
+    const abs = path.join(cwd, rel);
+    let settings = {};
+    let existed = false;
+    if (fs.existsSync(abs)) {
+        existed = true;
+        try {
+            settings = JSON.parse(fs.readFileSync(abs, 'utf8'));
+        }
+        catch {
+            // Don't clobber a file we can't parse — drop a reference sidecar.
+            const sidecar = rel + '.dxkit';
+            fs.writeFileSync(path.join(cwd, sidecar), JSON.stringify({ hooks: { Stop: [stopEntry()] } }, null, 2) + '\n', 'utf8');
+            result.sidecars.push(sidecar);
+            result.notes.push(`${rel} is not valid JSON — left untouched. Merge the Stop hook from ${sidecar} by hand.`);
+            return;
+        }
+    }
+    settings.hooks ??= {};
+    settings.hooks.Stop ??= [];
+    const already = settings.hooks.Stop.some((e) => (e.hooks ?? []).some((h) => typeof h.command === 'string' && /hook\s+stop-gate/.test(h.command)));
+    if (already) {
+        result.skipped.push(rel);
+        return;
+    }
+    settings.hooks.Stop.push(stopEntry());
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    result.installed.push(rel);
+    if (existed) {
+        result.notes.push(`Merged the Stop-gate hook into your existing ${rel} (other hooks preserved).`);
+    }
+}
+function stopEntry() {
+    // Stop hooks take no matcher (unlike PreToolUse).
+    return { hooks: [{ type: 'command', command: exports.STOP_HOOK_COMMAND }] };
+}
+/**
+ * Upsert the dxkit loop managed block in CLAUDE.md. Replaces the block
+ * between the sentinels if present (idempotent), appends it otherwise, and
+ * never touches content outside the markers.
+ */
+function upsertClaudeBlock(cwd, result) {
+    const rel = 'CLAUDE.md';
+    const abs = path.join(cwd, rel);
+    const block = `${CLAUDE_BLOCK_START}\n${CLAUDE_LOOP_NORM}\n${CLAUDE_BLOCK_END}`;
+    let existing = '';
+    let existed = false;
+    if (fs.existsSync(abs)) {
+        existed = true;
+        existing = fs.readFileSync(abs, 'utf8');
+    }
+    const startIdx = existing.indexOf(CLAUDE_BLOCK_START);
+    const endIdx = existing.indexOf(CLAUDE_BLOCK_END);
+    let next;
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        const before = existing.slice(0, startIdx);
+        const after = existing.slice(endIdx + CLAUDE_BLOCK_END.length);
+        next = before + block + after;
+        if (next === existing) {
+            result.skipped.push(rel);
+            return;
+        }
+    }
+    else if (existed) {
+        next = existing.replace(/\s*$/, '') + '\n\n' + block + '\n';
+    }
+    else {
+        next = `# CLAUDE.md\n\n${block}\n`;
+    }
+    fs.writeFileSync(abs, next, 'utf8');
+    result.installed.push(rel);
+    if (existed && startIdx === -1) {
+        result.notes.push(`Appended a dxkit loop block to your existing ${rel} (your content preserved).`);
+    }
+}
+/**
+ * Ensure `loop.preset` in `.dxkit/policy.json`, preserving all other
+ * policy fields. `explicit` (init `--loop-preset`) overrides; otherwise an
+ * existing preset is preserved and `security-only` is seeded only when
+ * none exists. Idempotent; a malformed existing policy is reported, not
+ * overwritten.
+ */
+function ensureLoopPreset(cwd, explicit, result) {
+    const rel = path.join('.dxkit', 'policy.json');
+    const abs = path.join(cwd, rel);
+    let policy = {};
+    if (fs.existsSync(abs)) {
+        try {
+            policy = JSON.parse(fs.readFileSync(abs, 'utf8'));
+        }
+        catch {
+            result.notes.push(`${rel} is not valid JSON — left untouched. Set loop.preset by hand.`);
+            return;
+        }
+    }
+    const existing = policy.loop?.preset;
+    // Override on explicit; else keep existing; else seed the default.
+    const target = explicit ?? existing ?? policy_1.DEFAULT_LOOP_PRESET;
+    if (existing === target) {
+        result.skipped.push(rel);
+        return;
+    }
+    policy.loop = { ...policy.loop, preset: target };
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, JSON.stringify(policy, null, 2) + '\n', 'utf8');
+    result.installed.push(rel);
+}
+/**
+ * Scaffold the loop pack into `cwd`. Additive + idempotent: safe to run on
+ * a fresh repo or re-run on one that already has settings/CLAUDE.md/policy.
+ */
+function installClaudeLoop(cwd, opts = {}) {
+    const result = { installed: [], skipped: [], sidecars: [], notes: [] };
+    mergeStopHook(cwd, result);
+    upsertClaudeBlock(cwd, result);
+    ensureLoopPreset(cwd, opts.preset, result);
+    return result;
+}
+//# sourceMappingURL=scaffold.js.map