@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/commands/judge.d.ts

@@ -2,7 +2,8 @@ import type { BelayJudgeConfig } from '../core/config.js';
 export interface JudgeCommandOptions {
     targetDir?: string;
     json?: boolean;
-    subcommand?: 'status' | 'list' | 'use' | 'test' | 'consent';
+    subcommand?: 'status' | 'list' | 'use' | 'test' | 'bench' | 'consent';
+    liveProbe?: boolean;
     providerId?: string;
     model?: string;
     endpoint?: string;
@@ -53,7 +54,16 @@ export declare function judgeTest(options?: JudgeCommandOptions): Promise<string
     warnings: string[];
     notes: string[];
 }>;
+export declare function judgeBench(options?: JudgeCommandOptions): Promise<string | {
+    slo: typeof import("../core/verdict/judge-runtime-config.js").JUDGE_LATENCY_SLO;
+    measured: Record<import("../core/verdict/judge-baseline.js").JudgeLatencyPhase, import("../core/verdict/judge-baseline.js").JudgeLatencyPercentiles>;
+    sessionMeetsTarget: boolean;
+}>;
 export declare function runJudgeCommand(options: JudgeCommandOptions): Promise<string | {
+    slo: typeof import("../core/verdict/judge-runtime-config.js").JUDGE_LATENCY_SLO;
+    measured: Record<import("../core/verdict/judge-baseline.js").JudgeLatencyPhase, import("../core/verdict/judge-baseline.js").JudgeLatencyPercentiles>;
+    sessionMeetsTarget: boolean;
+} | {
     providerId: import("../core/config.js").JudgeProviderId | import("../core/config.js").DeprecatedJudgeProviderId | undefined;
     provider: import("../core/config.js").JudgeProvider;
     endpoint: string | null;

package/dist/commands/judge.js

@@ -63,10 +63,11 @@ export async function judgeStatus(options = {}) {
     });
     const { resolved } = resolveJudgeModel(judge);
     const transport = resolveJudgeTransport(judge);
+    const effectiveTransport = transport === 'cursor-cli' && judge.runtime?.session.enabled ? 'cursor-acp' : transport;
     const lines = [
         `Judge providerId : ${judge.providerId ?? '(inferred)'}`,
         `Judge driver     : ${judge.provider}`,
-        `Transport        : ${transport}`,
+        `Transport        : ${effectiveTransport}`,
         `Endpoint         : ${judge.endpoint ?? '(none)'}`,
         `Model            : ${resolved} (requested: ${judge.model})`,
         `Credential       : ${credential.mode} (${credential.sourceKind})${credential.source ? ` → ${credential.source}` : ''} ${credential.key ? '✓ set' : '✗ missing'}`,
@@ -82,7 +83,7 @@ export async function judgeStatus(options = {}) {
             endpoint: judge.endpoint,
             model: judge.model,
             modelResolved: resolved,
-            transport,
+            transport: effectiveTransport,
             credential,
             cloudConsent: judge.cloudConsent ?? null,
             cloudJudgeActive: isCloudJudgeConfig(judge) && hasValidCloudConsent(judge),
@@ -254,7 +255,9 @@ export async function judgeRequestCloudConsent(options = {}) {
 export async function judgeTest(options = {}) {
     const repoRoot = path.resolve(options.targetDir ?? process.cwd());
     const config = await loadConfigFile(repoRoot);
-    const diagnosis = await diagnoseJudge(config, repoRoot);
+    const diagnosis = await diagnoseJudge(config, repoRoot, {
+        liveProbe: options.liveProbe === true,
+    });
     const modelCheck = diagnosis.modelCheck;
     if (options.json) {
         return { ...diagnosis, modelCheck };
@@ -267,6 +270,21 @@ export async function judgeTest(options = {}) {
         ...diagnosis.issues.map((i) => `Issue: ${i}`),
     ].join('\n');
 }
+export async function judgeBench(options = {}) {
+    const { judgeLatencySloReport } = await import('../core/verdict/judge-baseline.js');
+    const report = judgeLatencySloReport();
+    if (options.json) {
+        return report;
+    }
+    const lines = [
+        `SLO target: Tier1 session p95 <= ${Math.round(report.slo.spawnBaselineP95Ms * (1 - report.slo.tier1P95ReductionTarget))}ms`,
+        `Tier0 p50/p95: ${report.measured.tier0.p50}/${report.measured.tier0.p95}ms (${report.measured.tier0.count} samples)`,
+        `Tier1 spawn p50/p95: ${report.measured.tier1_spawn.p50}/${report.measured.tier1_spawn.p95}ms (${report.measured.tier1_spawn.count} samples)`,
+        `Tier1 session p50/p95: ${report.measured.tier1_session.p50}/${report.measured.tier1_session.p95}ms (${report.measured.tier1_session.count} samples)`,
+        `Session meets target: ${report.sessionMeetsTarget ? 'yes' : 'no'}`,
+    ];
+    return lines.join('\n');
+}
 export async function runJudgeCommand(options) {
     switch (options.subcommand) {
         case 'status':
@@ -277,9 +295,11 @@ export async function runJudgeCommand(options) {
             return judgeUse(options);
         case 'test':
             return judgeTest(options);
+        case 'bench':
+            return judgeBench(options);
         case 'consent':
             return judgeRequestCloudConsent(options);
         default:
-            throw new Error('judge requires subcommand: status, list, use, test, or consent');
+            throw new Error('judge requires subcommand: status, list, use, test, bench, or consent');
     }
 }

package/dist/commands/metrics.js

@@ -2,6 +2,12 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { loadConfigFile } from '../config-io.js';
 import { computeAuditMetrics, parseAuditNdjson } from '../core/audit-metrics.js';
+function formatFingerprintPreview(fingerprint) {
+    if (fingerprint.length <= 12) {
+        return fingerprint;
+    }
+    return `${fingerprint.slice(0, 12)}…`;
+}
 export async function metricsProject(options = {}) {
     const repoRoot = path.resolve(options.targetDir ?? process.cwd());
     const config = await loadConfigFile(repoRoot);
@@ -26,6 +32,7 @@ export function formatMetricsReport(report) {
         `Schema: v${report.schemaVersion}`,
         `Gate events: ${report.gateEvents}`,
         `Would-block: ${report.wouldBlockCount} (${(report.wouldBlockRate * 100).toFixed(1)}%)`,
+        `Classifier-quality would-block: ${report.classifierWouldBlockCount} (${(report.classifierWouldBlockRate * 100).toFixed(1)}%)`,
         `Approvals recorded during audit: ${report.approvalRecordedCount}`,
     ];
     if (report.approvalLatency.count > 0) {
@@ -34,6 +41,31 @@ export function formatMetricsReport(report) {
     if (report.bypassAttemptCount > 0) {
         lines.push(`Bypass attempts detected: ${report.bypassAttemptCount}`);
     }
+    if (report.availabilityAsks.total > 0) {
+        lines.push('', 'Availability-caused asks (infrastructure, not classifier ground truth):');
+        lines.push(`- missing trusted cwd: ${report.availabilityAsks.missingTrustedCwd}`);
+        lines.push(`- judge timeout: ${report.availabilityAsks.judgeTimeout}`);
+        lines.push(`- other judge fallback: ${report.availabilityAsks.judgeFallback}`);
+        lines.push(`- total: ${report.availabilityAsks.total}`);
+    }
+    if (report.repeatedFingerprintAsks.length > 0) {
+        lines.push('', 'Repeated fingerprint asks (repeat friction):');
+        for (const entry of report.repeatedFingerprintAsks) {
+            lines.push(`- [${entry.reason}] x${entry.askCount} ${formatFingerprintPreview(entry.fingerprint)}: ${entry.summary}`);
+        }
+    }
+    if (Object.keys(report.wouldBlockByReason).length > 0) {
+        lines.push('', 'Would-block by reason:');
+        for (const [reason, count] of Object.entries(report.wouldBlockByReason).sort((a, b) => b[1] - a[1])) {
+            lines.push(`- ${reason}: ${count}`);
+        }
+    }
+    if (report.approvalRatioByReason.length > 0) {
+        lines.push('', 'Approval ratio by reason (candidate signal, not ground truth):');
+        for (const entry of report.approvalRatioByReason.slice(0, 10)) {
+            lines.push(`- ${entry.reason}: ${(entry.approvalRate * 100).toFixed(0)}% approved after deny (${entry.approvedAfterDenyCount}/${entry.wouldBlockCount})`);
+        }
+    }
     if (Object.keys(report.byVerdict).length > 0) {
         lines.push('', 'By verdict:');
         for (const [verdict, count] of Object.entries(report.byVerdict).sort((a, b) => b[1] - a[1])) {
@@ -61,13 +93,13 @@ export function formatMetricsReport(report) {
         }
     }
     if (report.noisyRuleCandidates.length > 0) {
-        lines.push('', 'Noisy rule candidates:');
+        lines.push('', 'Noisy rule candidates (high-signal subset of approval ratios; ≥50% approved after deny):');
         for (const rule of report.noisyRuleCandidates) {
             lines.push(`- ${rule.reason}: ${(rule.approvalRate * 100).toFixed(0)}% approved after deny (${rule.approvedCount}/${rule.denyCount})`);
         }
     }
     if (Object.keys(report.byReason).length > 0) {
-        lines.push('', 'By reason:');
+        lines.push('', 'All gate events by reason:');
         for (const [reason, count] of Object.entries(report.byReason).sort((a, b) => b[1] - a[1])) {
             lines.push(`- ${reason}: ${count}`);
         }

package/dist/commands/quality.d.ts

@@ -0,0 +1,38 @@
+import type { CorpusCategory, CorpusProvenanceCounts } from '../corpus/types.js';
+export declare const QUALITY_REPORT_SCHEMA_VERSION = 1;
+export interface QualityReport {
+    schemaVersion: typeof QUALITY_REPORT_SCHEMA_VERSION;
+    ok: boolean;
+    corpus: {
+        path: string;
+        passesHardGates: boolean;
+        totalCases: number;
+        categoryCounts: Record<CorpusCategory, number>;
+        provenanceCounts: CorpusProvenanceCounts;
+        mustAskMisses: number;
+        provablyBenignBlocks: number;
+        acceptedBenignMismatches: number;
+        accuracy: number;
+    };
+    audit: {
+        logPath: string;
+        gateEvents: number;
+        classifierWouldBlockRate: number;
+        availabilityAsks: number;
+        readyForEnforce: boolean;
+        repeatedFingerprintPatterns: number;
+    };
+    harvest: {
+        scope: 'shell';
+        benignCandidates: number;
+        availabilityQueue: number;
+    };
+    notes: string[];
+}
+export interface QualityOptions {
+    targetDir?: string;
+    corpusDir?: string;
+    json?: boolean;
+}
+export declare function qualityCheck(options?: QualityOptions): Promise<QualityReport>;
+export declare function formatQualityReport(report: QualityReport): string;

package/dist/commands/quality.js

@@ -0,0 +1,105 @@
+import path from 'node:path';
+import { loadConfigFile } from '../config-io.js';
+import { computeAuditMetrics } from '../core/audit-metrics.js';
+import { runCorpusEvaluation } from '../corpus/evaluate.js';
+import { passesHardGates } from '../corpus/gates.js';
+import { loadAuditRecords } from './audit.js';
+import { harvestReportFromRecords } from './harvest.js';
+export const QUALITY_REPORT_SCHEMA_VERSION = 1;
+export async function qualityCheck(options = {}) {
+    const repoRoot = path.resolve(options.targetDir ?? process.cwd());
+    const config = await loadConfigFile(repoRoot);
+    const corpusDir = path.resolve(repoRoot, options.corpusDir ?? 'corpus');
+    const corpusMetrics = await runCorpusEvaluation(corpusDir);
+    const hardGatesOk = passesHardGates(corpusMetrics.gates);
+    const auditRecords = await loadAuditRecords(repoRoot);
+    const metrics = computeAuditMetrics(auditRecords, {
+        auditLogPath: config.audit.logPath,
+        mode: config.mode,
+        unknownLocalEffect: config.policy.unknownLocalEffect,
+    });
+    const harvest = harvestReportFromRecords(auditRecords, {
+        allowPatterns: config.overrides.allow,
+    });
+    const notes = [
+        'Overall ok reflects corpus hard gates only; audit and harvest signals are advisory.',
+        'Recursive quality loop: corpus hard gates are the FN/FP safety boundary.',
+        'Harvest candidates and audit metrics inform review — approvals are not ground truth.',
+        'Simulate (`belay simulate`) is triage only; it does not replace `pnpm corpus`.',
+    ];
+    if (!hardGatesOk) {
+        notes.push('Corpus hard gates failed — fix must-ask misses and provably-benign blocks before tuning friction.');
+    }
+    if (metrics.availabilityAsks.total > 0) {
+        notes.push(`${metrics.availabilityAsks.total} availability-caused ask(s) — tune judge/cwd infrastructure before corpus promotion.`);
+    }
+    if (harvest.availabilityQueue.length > 0) {
+        notes.push(`${harvest.availabilityQueue.length} shell pattern(s) in the availability queue — do not harvest into corpus.`);
+    }
+    const ok = hardGatesOk;
+    return {
+        schemaVersion: QUALITY_REPORT_SCHEMA_VERSION,
+        ok,
+        corpus: {
+            path: path.relative(repoRoot, corpusDir) || corpusDir,
+            passesHardGates: hardGatesOk,
+            totalCases: corpusMetrics.total,
+            categoryCounts: corpusMetrics.categoryCounts,
+            provenanceCounts: corpusMetrics.provenanceCounts,
+            mustAskMisses: corpusMetrics.gates.mustAsk.mismatches,
+            provablyBenignBlocks: corpusMetrics.gates.provablyBenign.mismatches,
+            acceptedBenignMismatches: corpusMetrics.gates.acceptedBenign.mismatches,
+            accuracy: corpusMetrics.accuracy,
+        },
+        audit: {
+            logPath: config.audit.logPath,
+            gateEvents: metrics.gateEvents,
+            classifierWouldBlockRate: metrics.classifierWouldBlockRate,
+            availabilityAsks: metrics.availabilityAsks.total,
+            readyForEnforce: metrics.dogfood.readyForEnforce,
+            repeatedFingerprintPatterns: metrics.repeatedFingerprintAsks.length,
+        },
+        harvest: {
+            scope: 'shell',
+            benignCandidates: harvest.candidates.length,
+            availabilityQueue: harvest.availabilityQueue.length,
+        },
+        notes,
+    };
+}
+export function formatQualityReport(report) {
+    const lines = [
+        'belay quality — recursive quality loop status',
+        `Schema: v${report.schemaVersion}`,
+        `Overall: ${report.ok ? 'OK' : 'ATTENTION NEEDED'}`,
+        '',
+        'Corpus hard gates:',
+        `  path: ${report.corpus.path}`,
+        `  passes: ${report.corpus.passesHardGates ? 'yes' : 'no'}`,
+        `  total cases: ${report.corpus.totalCases}`,
+        `  categories: must-ask=${report.corpus.categoryCounts['must-ask']} provably-benign=${report.corpus.categoryCounts['provably-benign']} accepted-benign=${report.corpus.categoryCounts['accepted-benign']}`,
+        `  provenance: manual=${report.corpus.provenanceCounts.manual} mutation=${report.corpus.provenanceCounts.mutation} harvest=${report.corpus.provenanceCounts.harvest} redteam=${report.corpus.provenanceCounts.redteam} unspecified=${report.corpus.provenanceCounts.unspecified}`,
+        `  must-ask misses: ${report.corpus.mustAskMisses}`,
+        `  provably-benign blocks: ${report.corpus.provablyBenignBlocks}`,
+        `  accepted-benign mismatches (soft): ${report.corpus.acceptedBenignMismatches}`,
+        `  accuracy: ${(report.corpus.accuracy * 100).toFixed(1)}%`,
+        '',
+        'Audit metrics:',
+        `  log: ${report.audit.logPath}`,
+        `  gate events: ${report.audit.gateEvents}`,
+        `  classifier would-block rate: ${(report.audit.classifierWouldBlockRate * 100).toFixed(1)}%`,
+        `  availability asks: ${report.audit.availabilityAsks}`,
+        `  ready for enforce: ${report.audit.readyForEnforce ? 'yes' : 'no'}`,
+        `  repeated fingerprint patterns: ${report.audit.repeatedFingerprintPatterns}`,
+        '',
+        'Harvest (shell only):',
+        `  benign candidates: ${report.harvest.benignCandidates}`,
+        `  availability queue: ${report.harvest.availabilityQueue}`,
+        '',
+        'Notes:',
+    ];
+    for (const note of report.notes) {
+        lines.push(`- ${note}`);
+    }
+    return lines.join('\n');
+}

package/dist/commands/session.d.ts

@@ -0,0 +1,20 @@
+import { boundarySessionStatus } from '../core/capability/boundary-session.js';
+export declare function sessionStartProject(params: {
+    targetDir?: string;
+    agentCommand?: string;
+}): Promise<{
+    ok: boolean;
+    message: string;
+    attestationPath?: string;
+    exitCode?: number | null;
+}>;
+export declare function sessionStatusProject(params: {
+    targetDir?: string;
+    json?: boolean;
+}): Promise<{
+    ok: boolean;
+    attestationPath: string;
+    fresh: boolean;
+    attestation: Awaited<ReturnType<typeof boundarySessionStatus>>['attestation'];
+}>;
+export declare function formatSessionStatusReport(report: Awaited<ReturnType<typeof sessionStatusProject>>): string;

package/dist/commands/session.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import process from 'node:process';
+import { loadConfigFile } from '../config-io.js';
+import { boundarySessionStatus, runBoundaryAgentCommand, startBoundarySession, } from '../core/capability/boundary-session.js';
+export async function sessionStartProject(params) {
+    const repoRoot = path.resolve(params.targetDir ?? process.cwd());
+    const config = await loadConfigFile(repoRoot);
+    const started = await startBoundarySession({ repoRoot, config });
+    if (!params.agentCommand) {
+        return {
+            ok: true,
+            message: `Boundary session started (${started.attestation.driver}); attestation written to ${path.relative(repoRoot, started.attestationPath)}.`,
+            attestationPath: started.attestationPath,
+        };
+    }
+    const run = await runBoundaryAgentCommand({
+        repoRoot,
+        config,
+        command: params.agentCommand,
+    });
+    const exitCode = run.exitCode ?? 1;
+    return {
+        ok: exitCode === 0,
+        message: `Boundary session started (${started.attestation.driver}); agent exited with code ${exitCode}.`,
+        attestationPath: started.attestationPath,
+        exitCode,
+    };
+}
+export async function sessionStatusProject(params) {
+    const repoRoot = path.resolve(params.targetDir ?? process.cwd());
+    const config = await loadConfigFile(repoRoot);
+    const status = await boundarySessionStatus({ repoRoot, config });
+    return {
+        ok: status.fresh,
+        attestationPath: status.attestationPath,
+        fresh: status.fresh,
+        attestation: status.attestation,
+    };
+}
+export function formatSessionStatusReport(report) {
+    if (!report.attestation) {
+        return `No boundary attestation at ${report.attestationPath}. Run belay session start.`;
+    }
+    return [
+        `Attestation: ${report.attestationPath}`,
+        `Driver: ${report.attestation.driver}`,
+        `Fresh: ${report.fresh ? 'yes' : 'no'}`,
+        `Expires: ${report.attestation.expiresAt}`,
+        `Materializes grants: ${report.attestation.materializesGrants ? 'yes' : 'no'}`,
+    ].join('\n');
+}

package/dist/commands/simulate.d.ts

@@ -9,6 +9,7 @@ export declare function simulateProject(options: SimulateOptions): Promise<{
     changedCount: number;
     allowToDenyCount: number;
     denyToAllowCount: number;
+    missingSnapshotCount: number;
     diffs: import("../core/reclassify.js").ReclassifyDiff[];
 }>;
 export declare function formatSimulateReport(report: Awaited<ReturnType<typeof simulateProject>>): string;

package/dist/commands/simulate.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { loadConfigFile } from '../config-io.js';
 import { parseAuditNdjson, toAuditRecord } from '../core/audit-metrics.js';
 import { mergeConfig } from '../core/config.js';
-import { diffReclassification } from '../core/reclassify.js';
+import { countMissingActionSnapshots, diffReclassification } from '../core/reclassify.js';
 export async function simulateProject(options) {
     const repoRoot = path.resolve(options.targetDir ?? process.cwd());
     const currentConfig = await loadConfigFile(repoRoot);
@@ -22,6 +22,7 @@ export async function simulateProject(options) {
         raw = '';
     }
     const records = parseAuditNdjson(raw).map(toAuditRecord);
+    const missingSnapshotCount = countMissingActionSnapshots(records);
     const diffs = (await Promise.all(records.map((record) => diffReclassification(record, candidateConfig, repoRoot)))).filter((diff) => diff !== null);
     const allowToDeny = diffs.filter((diff) => (diff.previousVerdict === 'allow' || diff.previousVerdict === 'allow_flagged') &&
         diff.nextVerdict === 'deny_pending_approval');
@@ -33,20 +34,24 @@ export async function simulateProject(options) {
         changedCount: diffs.length,
         allowToDenyCount: allowToDeny.length,
         denyToAllowCount: denyToAllow.length,
+        missingSnapshotCount,
         diffs,
     };
 }
 export function formatSimulateReport(report) {
     const lines = [
         `simulate ${report.candidateConfigPath}`,
+        'Triage only — corpus hard gates (`pnpm corpus`), not simulate counts, are the safety boundary.',
         `Records scanned: ${report.totalRecords}`,
+        `Missing action snapshots: ${report.missingSnapshotCount}`,
         `Verdict changes: ${report.changedCount}`,
         `allow/flagged → deny: ${report.allowToDenyCount}`,
         `deny → allow/flagged: ${report.denyToAllowCount}`,
         '',
     ];
     for (const diff of report.diffs.slice(0, 30)) {
-        lines.push(`- ${diff.summary ?? diff.fingerprint}: ${diff.previousVerdict}/${diff.previousReason} → ${diff.nextVerdict}/${diff.nextReason}`);
+        const context = diff.replayCwd && diff.replayKind ? ` [${diff.replayKind} cwd=${diff.replayCwd}]` : '';
+        lines.push(`- ${diff.summary ?? diff.fingerprint}${context}: ${diff.previousVerdict}/${diff.previousReason} → ${diff.nextVerdict}/${diff.nextReason}`);
     }
     if (report.diffs.length > 30) {
         lines.push(`... ${report.diffs.length - 30} more`);

package/dist/commands/standing-allow.d.ts

@@ -0,0 +1,10 @@
+import type { GatedActionKind } from '../core/gate-contract.js';
+export interface RevokeStandingAllowOptions {
+    targetDir?: string;
+    fingerprint: string;
+    kind?: GatedActionKind;
+}
+export declare function revokeStandingAllow(options: RevokeStandingAllowOptions): Promise<{
+    ok: boolean;
+    message: string;
+}>;

package/dist/commands/standing-allow.js

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { loadConfigFile, repoLocalStateDirFor } from '../config-io.js';
+import { loadStandingAllow, revokeStandingAllowEntry, saveStandingAllow, standingAllowFile, } from '../core/standing-allow.js';
+export async function revokeStandingAllow(options) {
+    const repoRoot = path.resolve(options.targetDir ?? process.cwd());
+    const config = await loadConfigFile(repoRoot);
+    const filePath = standingAllowFile(config, repoLocalStateDirFor(repoRoot, config));
+    const state = await loadStandingAllow(filePath);
+    const kind = options.kind ?? 'shell';
+    const { state: next, removed } = revokeStandingAllowEntry(state, {
+        kind,
+        fingerprint: options.fingerprint,
+        repoRoot,
+    });
+    if (!removed) {
+        return {
+            ok: false,
+            message: `Standing-allow entry not found for ${kind} fingerprint ${options.fingerprint}.`,
+        };
+    }
+    await saveStandingAllow(filePath, next);
+    return {
+        ok: true,
+        message: `Revoked standing-allow for ${kind} fingerprint ${options.fingerprint}.`,
+    };
+}

package/dist/commands/tui.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Zero-dependency terminal UI helpers for the interactive `belay config` wizard.
+ *
+ * Everything here is built on Node's built-in `readline`/`tty` only — no runtime
+ * dependencies — so it stays aligned with belay's zero-dependency posture.
+ *
+ * This module is intentionally TTY-only. Callers are responsible for non-TTY
+ * fallback behavior.
+ */
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    italic: (s: string) => string;
+    underline: (s: string) => string;
+    inverse: (s: string) => string;
+    cyan: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    red: (s: string) => string;
+    gray: (s: string) => string;
+};
+/** A select wizard only makes sense when both stdin and stdout are real TTYs. */
+export declare function isInteractiveTTY(): boolean;
+/** Top banner shown once at the start of the wizard. */
+export declare function intro(title: string, subtitle?: string): void;
+/** Closing line shown once at the end of the wizard. */
+export declare function outro(message: string): void;
+/** Collapsed one-line summary of an answered question. */
+export declare function summary(label: string, value: string): void;
+export interface SelectChoice<T extends string> {
+    value: T;
+    /** Visible label; defaults to `value`. */
+    label?: string;
+    /** Dim hint shown to the right of the focused row. */
+    hint?: string;
+}
+export interface SelectOptions<T extends string> {
+    message: string;
+    choices: SelectChoice<T>[];
+    defaultValue: T;
+}
+/**
+ * Interactive single-choice prompt driven by arrow keys (or j/k). Resolves with
+ * the selected choice value. Must only be called in an interactive TTY.
+ */
+export declare function selectPrompt<T extends string>(opts: SelectOptions<T>): Promise<T>;
+/** Interactive yes/no prompt rendered as a two-row arrow-key selection. */
+export declare function confirmPrompt(message: string, defaultValue: boolean): Promise<boolean>;

package/dist/commands/tui.js

@@ -0,0 +1,150 @@
+/**
+ * Zero-dependency terminal UI helpers for the interactive `belay config` wizard.
+ *
+ * Everything here is built on Node's built-in `readline`/`tty` only — no runtime
+ * dependencies — so it stays aligned with belay's zero-dependency posture.
+ *
+ * This module is intentionally TTY-only. Callers are responsible for non-TTY
+ * fallback behavior.
+ */
+import { stdin as input, stdout as output } from 'node:process';
+import readline from 'node:readline';
+const isColorEnabled = () => isInteractiveTTY() && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+const symbol = (pretty, plain) => (isColorEnabled() ? pretty : plain);
+const wrap = (open, close) => (s) => isColorEnabled() ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+export const c = {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    italic: wrap(3, 23),
+    underline: wrap(4, 24),
+    inverse: wrap(7, 27),
+    cyan: wrap(36, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    red: wrap(31, 39),
+    gray: wrap(90, 39),
+};
+/** A select wizard only makes sense when both stdin and stdout are real TTYs. */
+export function isInteractiveTTY() {
+    return Boolean(input.isTTY && output.isTTY);
+}
+const symPointer = () => symbol('❯', '>');
+const symCheck = () => symbol('✓', 'v');
+const symBar = () => symbol('│', '|');
+const symQuestion = () => '?';
+/** Top banner shown once at the start of the wizard. */
+export function intro(title, subtitle) {
+    output.write('\n');
+    output.write(`${c.green(symBar())} ${c.bold(title)}\n`);
+    if (subtitle) {
+        output.write(`${c.green(symBar())} ${c.dim(subtitle)}\n`);
+    }
+    output.write(`${c.green(symBar())}\n`);
+}
+/** Closing line shown once at the end of the wizard. */
+export function outro(message) {
+    output.write(`${c.green(symBar())}\n`);
+    output.write(`${c.green(symCheck())} ${message}\n\n`);
+}
+/** Collapsed one-line summary of an answered question. */
+export function summary(label, value) {
+    output.write(`${c.green(symCheck())} ${c.dim(label)}  ${c.cyan(value)}\n`);
+}
+/**
+ * Interactive single-choice prompt driven by arrow keys (or j/k). Resolves with
+ * the selected choice value. Must only be called in an interactive TTY.
+ */
+export function selectPrompt(opts) {
+    if (!isInteractiveTTY()) {
+        throw new Error('selectPrompt requires an interactive TTY.');
+    }
+    const { message, choices } = opts;
+    if (choices.length === 0) {
+        throw new Error('selectPrompt requires at least one choice.');
+    }
+    const startIndex = Math.max(0, choices.findIndex((ch) => ch.value === opts.defaultValue));
+    return new Promise((resolve, reject) => {
+        let index = startIndex;
+        let rendered = 0;
+        const lineFor = (ch, active) => {
+            const label = ch.label ?? ch.value;
+            if (active) {
+                const hint = ch.hint ? ` ${c.dim(ch.hint)}` : '';
+                return `${c.cyan(symPointer())} ${c.cyan(c.underline(label))}${hint}`;
+            }
+            return `  ${c.dim(label)}`;
+        };
+        const clearRendered = () => {
+            if (rendered > 0) {
+                output.write(`\x1b[${rendered}A`);
+            }
+            output.write('\x1b[J');
+        };
+        const render = () => {
+            clearRendered();
+            const lines = [
+                `${c.green(symQuestion())} ${c.bold(message)}`,
+                ...choices.map((ch, i) => lineFor(ch, i === index)),
+            ];
+            output.write(`${lines.join('\n')}\n`);
+            rendered = lines.length;
+        };
+        const cleanup = () => {
+            input.off('keypress', onKey);
+            if (input.isTTY && typeof input.setRawMode === 'function') {
+                input.setRawMode(false);
+            }
+            input.pause();
+            output.write('\x1b[?25h'); // show cursor
+        };
+        const finish = () => {
+            clearRendered();
+            cleanup();
+            const chosen = choices[index];
+            summary(message, chosen.label ?? chosen.value);
+            resolve(chosen.value);
+        };
+        const onKey = (_str, key) => {
+            if (!key)
+                return;
+            if (key.ctrl && key.name === 'c') {
+                clearRendered();
+                cleanup();
+                output.write('\n');
+                reject(new Error('Cancelled.'));
+                return;
+            }
+            if (key.name === 'up' || key.name === 'k') {
+                index = (index - 1 + choices.length) % choices.length;
+                render();
+            }
+            else if (key.name === 'down' || key.name === 'j') {
+                index = (index + 1) % choices.length;
+                render();
+            }
+            else if (key.name === 'return' || key.name === 'enter') {
+                finish();
+            }
+        };
+        readline.emitKeypressEvents(input);
+        if (input.isTTY && typeof input.setRawMode === 'function') {
+            input.setRawMode(true);
+        }
+        input.resume();
+        output.write('\x1b[?25l'); // hide cursor
+        input.on('keypress', onKey);
+        render();
+    });
+}
+/** Interactive yes/no prompt rendered as a two-row arrow-key selection. */
+export async function confirmPrompt(message, defaultValue) {
+    const value = await selectPrompt({
+        message,
+        defaultValue: defaultValue ? 'yes' : 'no',
+        choices: [
+            { value: 'yes', label: 'Yes' },
+            { value: 'no', label: 'No' },
+        ],
+    });
+    return value === 'yes';
+}