@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/mcp/handlers/operator-inspection.js

@@ -0,0 +1,284 @@
+"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.createOperatorInspectionHandlers = createOperatorInspectionHandlers;
+// @implements A-SPEC-605, A-SPEC-605.1
+// @implements A-SPEC-642
+// @implements A-SPEC-631
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const spec_store_1 = require("../../spec/spec-store");
+const approval_status_1 = require("../../spec/approval-status");
+const ledger_store_1 = require("../../governance/ledger-store");
+const ledger_timeline_1 = require("../../governance/ledger-timeline");
+const provenance_ledger_1 = require("../../governance/provenance-ledger");
+const provenance_chain_1 = require("../../governance/provenance-chain");
+const approval_grants_1 = require("../../governance/approval-grants");
+function createOperatorInspectionHandlers(context) {
+    return {
+        /**
+         * @implements A-SPEC-538.2
+         * Read-only: report a spec's approval/seal state — sealed?, approved_digest, each parent's seal
+         * state, and the concrete blockers still standing between it and approval — so a caller need not
+         * parse files to ask "what is the approval state right now". Reuses `sealOf` and `approvalBlockers`
+         * (the same predicates the code gate and spec_approve read) so the report cannot drift from the
+         * acts it describes. No writes, no ledger append.
+         */
+        async approval_status(a) {
+            context.assertStoreReachable('approval_status', a.root); // @implements A-SPEC-419
+            const all = await context.listSpecs();
+            if (all.filter((s) => s.id === a.id).length > 1) {
+                return {
+                    ok: false,
+                    reason: `${a.id}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본의 상태를 물었는지 도구가 고를 수 없어 거부합니다.`,
+                };
+            }
+            const cur = await context.readSpec(a.id);
+            if (!cur) {
+                const dir = context.specsRoot();
+                const unreadable = typeof dir === 'string' ? (0, spec_store_1.unreadableSpecFiles)(dir) : [];
+                return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
+            }
+            // @implements A-SPEC-572.1
+            // The graph advisory, delivered at DESIGN time. Measured on our own work: A-SPEC-571.1's
+            // sealing advisory named the exact cluster three regressions then landed in — and by then
+            // the design was done. The calculation was never the gap; the delivery time was. So the
+            // read-only "what is blocking this right now" tool also answers "what will this scope leak,
+            // and where is it dense" — using the SAME functions spec_approve calls, so the preview can
+            // never disagree with the seal. Read-only stays read-only: no scan, no build, no ledger
+            // append (a query must not pollute the observation denominator), and every failure degrades
+            // to an absent field on an otherwise identical response.
+            let graphPreview;
+            try {
+                if (cur.spec.type === 'A-SPEC' && a.root) {
+                    const dbPath = path.join(a.root, '.ax', 'rtm.sqlite');
+                    // @implements A-SPEC-631 — non-mutating inspection of the live graph; an empty or
+                    // unreadable file is reported as such instead of previewing "no impact" from nothing.
+                    const { openPublishedGraph, headCommitOf } = require('../../rtm/graph-store');
+                    const { cleanSubprocessEnv } = require('../../project/root');
+                    const view = openPublishedGraph(dbPath, headCommitOf(a.root, cleanSubprocessEnv()));
+                    if (view.status === 'empty' || view.status === 'unreadable') {
+                        graphPreview = { unavailable: view.status, ...(view.graphAsOf ? { graphAsOf: view.graphAsOf } : {}) };
+                    }
+                    else if (view.graph !== null) {
+                        const { declaredImpactGap } = require('../../rtm/impact-advisory');
+                        const { anchorDensityFindings } = require('../../rtm/anchor-density');
+                        const { filesToTouch } = require('../../spec/compat-impact');
+                        const graph = view.graph;
+                        const condition = { status: view.status, sourceCommit: view.sourceCommit, head: view.head };
+                        try {
+                            const ftt = filesToTouch(cur.spec);
+                            const impact = declaredImpactGap(ftt, graph, (rel) => { try {
+                                return fs.readFileSync(path.join(a.root, rel), 'utf8');
+                            }
+                            catch {
+                                return null;
+                            } });
+                            const density = anchorDensityFindings(ftt, graph.implementsAnchorCounts());
+                            // @implements A-SPEC-574.2 — the computation lives in cycle-detect; this file holds
+                            // the wiring only (measured: 85 anchors here against a p90 of 7).
+                            const { cycleAdvisory, classifyEdgeByTarget, CYCLE_ADVISORY_NOTE } = require('../../cpg/cycle-detect');
+                            const readCache = new Map();
+                            const readSource = (rel) => {
+                                const hit = readCache.get(rel);
+                                if (hit !== undefined)
+                                    return hit;
+                                // A read failure degrades to the conservative kind rather than losing the finding.
+                                let text = '';
+                                try {
+                                    text = fs.readFileSync(path.join(a.root, rel), 'utf8');
+                                }
+                                catch {
+                                    text = '';
+                                }
+                                readCache.set(rel, text);
+                                return text;
+                            };
+                            const cycleFindings = cycleAdvisory(ftt, graph.importEdges().map((edge) => ({
+                                ...edge,
+                                kind: classifyEdgeByTarget(readSource(edge.from), edge.from, edge.to),
+                            })));
+                            // @implements A-SPEC-574.5 — the same import edges the cycle pass already read, plus
+                            // the parent-time symbol spans the graph already holds. No new scan, no new parse.
+                            const { architectureObservation } = require('../../cpg/arch-observe');
+                            const { TreeSitterTsParser } = require('../../cpg/language-parser');
+                            const { langForPath } = require('../../cpg/cpg-scanner');
+                            // Bounded to the DECLARED files, whose text is read once and used for both numbers.
+                            const archParser = new TreeSitterTsParser();
+                            const archText = new Map();
+                            const readArch = (f) => {
+                                if (!archText.has(f)) {
+                                    try {
+                                        archText.set(f, fs.readFileSync(path.join(a.root, f), 'utf8'));
+                                    }
+                                    catch {
+                                        archText.set(f, null);
+                                    }
+                                }
+                                return archText.get(f) ?? null;
+                            };
+                            const spans = new Map(ftt.map((f) => {
+                                const text = readArch(f);
+                                if (text === null)
+                                    return [f, []];
+                                try {
+                                    return [f, archParser.extractSymbols(text, langForPath(f))
+                                            .filter((sy) => sy.kind !== 'class')
+                                            .map((sy) => ({ startLine: sy.startLine, endLine: sy.endLine }))];
+                                }
+                                catch {
+                                    return [f, []];
+                                }
+                            }));
+                            const arch = architectureObservation(ftt, spans, graph.importEdges(), (f) => { const t = readArch(f); return t === null ? null : t.split('\n').length; });
+                            if (impact || density.length > 0 || cycleFindings.length > 0 || arch.length > 0) {
+                                const graphAsOf = (() => { try {
+                                    return fs.statSync(dbPath).mtime.toISOString();
+                                }
+                                catch {
+                                    return undefined;
+                                } })();
+                                graphPreview = {
+                                    graph: condition,
+                                    ...(impact ? { impact } : {}),
+                                    ...(density.length > 0 ? { density } : {}),
+                                    ...(cycleFindings.length > 0
+                                        ? { cycles: { findings: cycleFindings, note: CYCLE_ADVISORY_NOTE } } : {}),
+                                    ...(arch.length > 0 ? { architecture: arch } : {}),
+                                    ...(graphAsOf ? { graphAsOf } : {}),
+                                };
+                            }
+                        }
+                        finally {
+                            graph.close();
+                        }
+                    }
+                }
+            }
+            catch {
+                graphPreview = undefined;
+            }
+            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, context.resolver(all)), ...(graphPreview ? { graphPreview } : {}) };
+        },
+        /**
+         * @implements A-SPEC-538.3
+         * Read-only: return the provenance ledger's events in time order (optionally narrowed to one
+         * spec) so the governance history — approved / unsealed / retired / review-needed … — is legible
+         * at a glance without reading raw JSONL. Reuses FileLedgerStore.loadAll(); the ordering/filtering/
+         * projection is the pure `timelineFrom`. No writes. An absent ledger is an empty history, not an
+         * error.
+         */
+        async ledger_timeline(a) {
+            const dest = context.resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            const dir = path.join(dest.root, '.ax', 'ledger');
+            const events = fs.existsSync(dir) ? new ledger_store_1.FileLedgerStore(dir).loadAll() : [];
+            return { ok: true, events: (0, ledger_timeline_1.timelineFrom)(events, a.id) };
+        },
+        /**
+         * @implements A-SPEC-642
+         * The one exit from a merged cross-replica double-spend. Under out-of-band authority of kind
+         * `ledger-reconcile` for that nonce, append `nonce-double-spend-reconciled` on THIS replica's chain
+         * naming the nonce and every consuming event's hash; `verifyAll`, the Stop hook, baseline trust and
+         * the ledger-conflict refusals then clear. Nothing is erased: both consumptions stay in their
+         * chains, and a later consumption of the same nonce is a new, open double-spend. Refuses to extend
+         * a broken chain, because a reconciliation that itself cannot be verified lifts nothing.
+         */
+        async ledger_reconcile(a) {
+            const dest = context.resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            const nonce = typeof a.nonce === 'string' ? a.nonce.trim() : '';
+            if (!nonce)
+                return { ok: false, reason: 'ledger_reconcile: `nonce` is required — the nonce input exactly as verifyAll / doubleSpends names it (usually "nonce:<12 hex>").' };
+            const dir = path.join(dest.root, '.ax', 'ledger');
+            const store = new ledger_store_1.FileLedgerStore(dir);
+            const pending = store.doubleSpends();
+            const match = pending.find((d) => d.nonce === nonce);
+            if (!match) {
+                return { ok: true, reconciled: false, nonce, pending: pending.map((d) => d.nonce),
+                    reason: pending.length === 0 ? 'the merged ledger holds no unreconciled double-spend' : `${nonce} is not an unreconciled double-spend; pending: ${pending.map((d) => d.nonce).join(', ')}` };
+            }
+            const replicas = [...new Set(match.events.map((e) => e.replicaId ?? 'legacy'))];
+            let approval;
+            try {
+                approval = process.env.HOLMES_APPROVAL ? JSON.parse(process.env.HOLMES_APPROVAL) : undefined;
+            }
+            catch {
+                approval = undefined;
+            }
+            const now = new Date().toISOString();
+            const resolved = context.resolveHandlerApproval(dest.root, approval, { kind: 'ledger-reconcile', target: nonce }, now);
+            if (!resolved) {
+                return { ok: false, code: 'approval-required',
+                    reason: `ledger_reconcile requires an out-of-band HOLMES_APPROVAL (or grant) that COVERS kind "ledger-reconcile" for ${nonce} — accepting that ${match.events.length} consumptions on ${replicas.join(', ')} were intended is an operator decision, not the agent's.`
+                        + context.refusalQueueHint(dest.root, { kind: 'ledger-reconcile', target: nonce, why: `Reconcile the cross-replica double-spend of ${nonce} (${match.events.length} consumptions on ${replicas.join(', ')})` }) };
+            }
+            const chainBreaks = store.verifyAll().broken.filter((b) => b.kind === 'chain');
+            if (chainBreaks.length > 0) {
+                return { ok: false, code: 'audit-conflict', reason: 'ledger_reconcile cannot extend a broken chain: ' + chainBreaks.map((b) => `${b.replicaId ?? 'legacy'}: ${b.detail ?? 'broken'}`).join('; ') };
+            }
+            store.append({
+                ts: now, actor: resolved.approval.actor, kind: provenance_ledger_1.DOUBLE_SPEND_RECONCILED,
+                summary: `reconciled cross-replica double-spend of ${nonce}: ${match.events.length} consumptions on ${replicas.join(', ')}`.slice(0, 200),
+                inputs: [nonce, ...match.events.map((e) => 'event:' + e.hash), ...replicas.map((r) => 'replica:' + r)],
+                rationale: typeof a.rationale === 'string' && a.rationale.trim() !== '' ? a.rationale.trim() : resolved.approval.rationale,
+                authorization: (0, provenance_chain_1.authorizationRef)(resolved.approval.actor, resolved.approval.token),
+            });
+            if (resolved.source === 'grant' && resolved.approval.nonce)
+                (0, approval_grants_1.consumeGrantFile)(resolved.root ?? dest.root, String(resolved.approval.nonce));
+            return { ok: true, reconciled: true, nonce, events: match.events, remaining: store.doubleSpends().map((d) => d.nonce) };
+        },
+        // @implements A-SPEC-545.3 — "show me the RTM dashboard" launches (idempotently) the server the
+        // agent would otherwise start by hand, and returns its URL plus an honesty census of what it shows.
+        async rtm_dashboard(a) {
+            const dest = context.resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            try {
+                const { startDashboardServer } = await Promise.resolve().then(() => __importStar(require('../../server/dashboard')));
+                const { ensureDashboard, dashboardCensus } = await Promise.resolve().then(() => __importStar(require('../../server/dashboard-launcher')));
+                const launch = await ensureDashboard(dest.root, a.port, (opts) => startDashboardServer(opts));
+                const rtm = await context.fetchJson(`${launch.url}/api/rtm`);
+                const heatmap = await context.fetchJson(`${launch.url}/api/rtm/heatmap`);
+                return { ok: true, url: launch.url, running: launch.running, census: dashboardCensus(rtm, heatmap) };
+            }
+            catch (err) {
+                return { ok: false, reason: `대시보드 기동 실패: ${err?.message ?? String(err)}` };
+            }
+        },
+    };
+}

package/dist/holmes/mcp/handlers/phase-queries.d.ts

@@ -0,0 +1,34 @@
+import { Spec } from '../../spec/spec-parser';
+import { Action } from '../../guardrail/phase';
+export interface PhaseQueryContext {
+    listSpecs(): Promise<Spec[]>;
+    boundSpecsRoot(): string | undefined;
+    projectRootOf(root: string): string;
+}
+export declare function createPhaseQueryHandlers(context: PhaseQueryContext): {
+    phase_status(a: {
+        root?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        specs?: undefined;
+        note?: undefined;
+    } | {
+        specs: {
+            id: string;
+            type: import("../../spec/spec-types").SpecType;
+            status: "draft" | "review" | "approved" | "outdated";
+        }[];
+        note: string;
+        ok?: undefined;
+        reason?: undefined;
+    }>;
+    phase_check(a: {
+        action?: Action;
+        target: string;
+        targetAspecId?: string;
+    }): Promise<import("../../guardrail/phase").CheckResult | {
+        decision: string;
+        note: string;
+    }>;
+};

package/dist/holmes/mcp/handlers/phase-queries.js

@@ -0,0 +1,86 @@
+"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.createPhaseQueryHandlers = createPhaseQueryHandlers;
+// @implements A-SPEC-606, A-SPEC-100.2
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const phase_1 = require("../../guardrail/phase");
+const write_target_1 = require("../../guardrail/write-target");
+function createPhaseQueryHandlers(context) {
+    return {
+        async phase_status(a) {
+            // @implements A-SPEC-189 §6 — `root` was advertised and never read, so a call naming another
+            // project (or a path that does not exist) got THIS server's corpus in a success shape and the
+            // caller derived its phase from someone else's specs. Same anchor discipline as spec_approve.
+            const boundSpecsRoot = typeof a?.root === 'string' && a.root !== '' ? context.boundSpecsRoot() : undefined;
+            if (typeof a?.root === 'string' && a.root !== '' && boundSpecsRoot !== undefined) {
+                let asked;
+                let bound;
+                let derivationFoundMarker = false;
+                try {
+                    asked = (0, write_target_1.resolveTarget)(context.projectRootOf(a.root), '.');
+                    const derived = context.projectRootOf(boundSpecsRoot);
+                    derivationFoundMarker = fs.existsSync(path.join(derived, '.ax'));
+                    bound = (0, write_target_1.resolveTarget)(derived, '.');
+                }
+                catch (e) {
+                    return { ok: false, reason: `root를 해석할 수 없습니다: ${String(e.message)}` };
+                }
+                // @implements A-SPEC-189 §7 (round 10) — spec_approve's round-3 lesson, copied here at last:
+                // resolveProjectRoot returns its INPUT when no `.ax` ancestor exists, so a custom
+                // HOLMES_SPECS outside any project "derived" the spec store itself as the project and this
+                // guard then refused the CORRECT root. Only a derivation that actually found a marker
+                // speaks for a project.
+                if (derivationFoundMarker && asked !== bound) {
+                    return {
+                        ok: false,
+                        reason: `이 서버는 ${bound} 프로젝트에 바인딩되어 있습니다 — 요청한 root ${a.root}는 ${asked} 를 가리킵니다.`
+                            + ' 다른 프로젝트의 코퍼스를 이 서버가 대신 답하지 않습니다.',
+                    };
+                }
+            }
+            const specs = await context.listSpecs();
+            return { specs: specs.map((s) => ({ id: s.id, type: s.type, status: s.status })), note: 'derive phase via phase_check' };
+        },
+        async phase_check(a) {
+            const specs = await context.listSpecs();
+            const action = a.action ?? (0, phase_1.classifyAction)(a.target);
+            if (!action)
+                return { decision: 'allow', note: 'unclassified target' };
+            return (0, phase_1.phaseCheck)(action, { specs, targetAspecId: a.targetAspecId });
+        },
+    };
+}

package/dist/holmes/mcp/handlers/review-evidence.d.ts

@@ -0,0 +1,47 @@
+import { Finding } from '../../review/findings';
+import { Approval } from '../../guardrail/risk-gate';
+import { ElicitOutcome } from '../elicit-approval';
+import { Basis } from '../basis';
+export interface ReviewEvidenceContext {
+    foreignRootReason(root?: string): string | null;
+    refusal(reason: string): Error;
+    boundFindingsLedger(root: string): string;
+    boundNonceLedger(): string | null;
+    projectRootOf(root: string): string;
+    basisFor(root: string | undefined, withDisk?: boolean): Basis;
+    hasElicitor(): boolean;
+    tryElicit(kind: string, target: string, summary: string): Promise<ElicitOutcome>;
+    elicitApproval(reason?: string): Approval;
+    resolveHandlerApproval(root: string | undefined, approval: Approval | undefined, action: {
+        kind: string;
+        target: string;
+    }, now: string): {
+        approval: Approval;
+        source: 'env' | 'grant';
+        root?: string;
+    } | undefined;
+    refusalQueueHint(root: string | undefined, request: {
+        kind: string;
+        target: string;
+        why: string;
+    }): string;
+}
+export declare function createReviewEvidenceHandlers(context: ReviewEvidenceContext): {
+    review_record(a: {
+        root: string;
+        findings: Finding[];
+    }): Promise<{
+        recorded: number;
+    }>;
+    review_status(a: {
+        root: string;
+    }): Promise<{
+        blocked: boolean;
+        open: {
+            critical: number;
+            important: number;
+            minor: number;
+        };
+        reviewNeeded: import("../../review/review-targets").ReviewNeeded[];
+    }>;
+};