@guilz-dev/belay 0.1.0

package/dist/corpus/evaluate.d.ts

@@ -0,0 +1,24 @@
+import type { Assessment, HookVerdict } from '../core/types.js';
+export interface CorpusCase {
+    command: string;
+    verdict: HookVerdict;
+    reason?: string;
+}
+export interface CorpusMetrics {
+    total: number;
+    correct: number;
+    accuracy: number;
+    precision: Record<string, number>;
+    recall: Record<string, number>;
+    falsePositiveRate: number;
+    mismatches: Array<{
+        command: string;
+        expected: string;
+        actual: string;
+        reason: string;
+    }>;
+}
+export declare function assessmentsDiverge(predicted: Assessment, observed: Assessment): boolean;
+export declare function loadCorpusCases(corpusDir: string): Promise<CorpusCase[]>;
+export declare function evaluateCorpus(cases: CorpusCase[], repoRoot?: string): Promise<CorpusMetrics>;
+export declare function runCorpusEvaluation(corpusDir?: string): Promise<CorpusMetrics>;

package/dist/corpus/evaluate.js

@@ -0,0 +1,69 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { classifierOptionsFromConfig, DEFAULT_CONFIG_V3 } from '../core/config.js';
+import { classifyShell } from '../core/v2/adapter.js';
+import { createDeterministicJudgeStub } from '../core/v2/judge.js';
+export function assessmentsDiverge(predicted, observed) {
+    return (predicted.reversibility !== observed.reversibility ||
+        predicted.external !== observed.external ||
+        predicted.blastRadius !== observed.blastRadius);
+}
+const VERDICTS = ['allow', 'allow_flagged', 'deny_pending_approval'];
+export async function loadCorpusCases(corpusDir) {
+    const raw = await readFile(path.join(corpusDir, 'shell-commands.json'), 'utf8');
+    return JSON.parse(raw);
+}
+export async function evaluateCorpus(cases, repoRoot = '/workspace/project') {
+    const cwd = path.join(repoRoot, 'src');
+    const options = classifierOptionsFromConfig(DEFAULT_CONFIG_V3);
+    const mismatches = [];
+    let correct = 0;
+    const confusion = {};
+    for (const expected of VERDICTS) {
+        confusion[expected] = { allow: 0, allow_flagged: 0, deny_pending_approval: 0 };
+    }
+    const judge = createDeterministicJudgeStub();
+    for (const testCase of cases) {
+        const result = await classifyShell(testCase.command, cwd, repoRoot, DEFAULT_CONFIG_V3, options, judge);
+        confusion[testCase.verdict][result.verdict] += 1;
+        const verdictOk = result.verdict === testCase.verdict;
+        const reasonOk = !testCase.reason || result.reason === testCase.reason;
+        if (verdictOk && reasonOk) {
+            correct += 1;
+        }
+        else {
+            mismatches.push({
+                command: testCase.command,
+                expected: testCase.verdict,
+                actual: result.verdict,
+                reason: result.reason,
+            });
+        }
+    }
+    const precision = {};
+    const recall = {};
+    for (const verdict of VERDICTS) {
+        const predicted = VERDICTS.reduce((sum, key) => sum + confusion[key][verdict], 0);
+        const truePositive = confusion[verdict][verdict];
+        precision[verdict] = predicted === 0 ? 1 : truePositive / predicted;
+        const actualTotal = VERDICTS.reduce((sum, key) => sum + confusion[verdict][key], 0);
+        recall[verdict] = actualTotal === 0 ? 1 : truePositive / actualTotal;
+    }
+    const falsePositives = mismatches.filter((entry) => entry.expected === 'deny_pending_approval' && entry.actual !== 'deny_pending_approval').length;
+    const denyCases = cases.filter((entry) => entry.verdict === 'deny_pending_approval').length;
+    return {
+        total: cases.length,
+        correct,
+        accuracy: cases.length === 0 ? 1 : correct / cases.length,
+        precision,
+        recall,
+        falsePositiveRate: denyCases === 0 ? 0 : falsePositives / denyCases,
+        mismatches,
+    };
+}
+export async function runCorpusEvaluation(corpusDir) {
+    const root = corpusDir ?? path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'corpus');
+    const cases = await loadCorpusCases(root);
+    return evaluateCorpus(cases);
+}

package/dist/defaults.d.ts

@@ -0,0 +1,18 @@
+import { type BelayConfigV3 } from './core/config.js';
+export { PACKAGE_NAME } from './branding.js';
+export declare const DEFAULT_CONFIG: BelayConfigV3;
+export type ManagedHookDefinition = {
+    command: string;
+    placement: 'prepend' | 'append';
+    matcher?: string;
+};
+export declare function getManagedHookEntries(platform?: NodeJS.Platform, hooksDir?: string, repoRoot?: string): Array<{
+    event: string;
+    definition: ManagedHookDefinition;
+}>;
+/** @deprecated Use getManagedHookEntries instead. */
+export declare function getManagedHookEvents(platform?: NodeJS.Platform): Record<string, ManagedHookDefinition>;
+export declare const EMPTY_APPROVALS: {
+    readonly version: 1;
+    readonly approvals: readonly [];
+};

package/dist/defaults.js

@@ -0,0 +1,155 @@
+import path from 'node:path';
+import { cursorLayout } from './adapters/layouts/cursor.js';
+import { buildRunnerInvocation } from './adapters/layouts/scope.js';
+import { DEFAULT_CONFIG_V3 } from './core/config.js';
+export { PACKAGE_NAME } from './branding.js';
+export const DEFAULT_CONFIG = DEFAULT_CONFIG_V3;
+function runnerCommand(platform, hooksDir, repoRoot, hookScript, ...args) {
+    return buildRunnerInvocation(platform, hooksDir, repoRoot, hookScript, ...args);
+}
+export function getManagedHookEntries(platform = process.platform, hooksDir, repoRoot) {
+    const resolvedRepo = path.resolve(repoRoot ?? process.cwd());
+    const resolvedHooksDir = hooksDir ?? cursorLayout.hooksDir(resolvedRepo);
+    const toolGate = runnerCommand(platform, resolvedHooksDir, resolvedRepo, 'belay-tool-gate', 'preToolUse');
+    const subagentGate = runnerCommand(platform, resolvedHooksDir, resolvedRepo, 'belay-tool-gate', 'subagentStart');
+    return [
+        {
+            event: 'beforeSubmitPrompt',
+            definition: {
+                command: runnerCommand(platform, resolvedHooksDir, resolvedRepo, 'belay-before-submit'),
+                placement: 'prepend',
+            },
+        },
+        {
+            event: 'beforeShellExecution',
+            definition: {
+                command: runnerCommand(platform, resolvedHooksDir, resolvedRepo, 'belay-shell-gate'),
+                placement: 'prepend',
+            },
+        },
+        {
+            event: 'preToolUse',
+            definition: {
+                command: toolGate,
+                placement: 'prepend',
+                matcher: 'Task',
+            },
+        },
+        {
+            event: 'preToolUse',
+            definition: {
+                command: toolGate,
+                placement: 'prepend',
+                matcher: 'Shell',
+            },
+        },
+        {
+            event: 'preToolUse',
+            definition: {
+                command: toolGate,
+                placement: 'prepend',
+                matcher: 'Write',
+            },
+        },
+        {
+            event: 'preToolUse',
+            definition: {
+                command: toolGate,
+                placement: 'prepend',
+                matcher: 'StrReplace',
+            },
+        },
+        {
+            event: 'preToolUse',
+            definition: {
+                command: toolGate,
+                placement: 'prepend',
+                matcher: 'Delete',
+            },
+        },
+        {
+            event: 'subagentStart',
+            definition: {
+                command: subagentGate,
+                placement: 'prepend',
+                matcher: 'generalPurpose',
+            },
+        },
+        {
+            event: 'subagentStart',
+            definition: {
+                command: subagentGate,
+                placement: 'prepend',
+                matcher: 'computerUse',
+            },
+        },
+        {
+            event: 'subagentStart',
+            definition: {
+                command: subagentGate,
+                placement: 'prepend',
+                matcher: 'debug',
+            },
+        },
+        {
+            event: 'subagentStart',
+            definition: {
+                command: subagentGate,
+                placement: 'prepend',
+                matcher: 'explore',
+            },
+        },
+        {
+            event: 'subagentStart',
+            definition: {
+                command: subagentGate,
+                placement: 'prepend',
+                matcher: 'videoReview',
+            },
+        },
+        {
+            event: 'subagentStart',
+            definition: {
+                command: subagentGate,
+                placement: 'prepend',
+                matcher: 'bugbot',
+            },
+        },
+        {
+            event: 'postToolUse',
+            definition: {
+                command: runnerCommand(platform, resolvedHooksDir, resolvedRepo, 'belay-audit', 'postToolUse'),
+                placement: 'append',
+            },
+        },
+        {
+            event: 'stop',
+            definition: {
+                command: runnerCommand(platform, resolvedHooksDir, resolvedRepo, 'belay-audit', 'stop'),
+                placement: 'append',
+            },
+        },
+        {
+            event: 'sessionEnd',
+            definition: {
+                command: runnerCommand(platform, resolvedHooksDir, resolvedRepo, 'belay-audit', 'sessionEnd'),
+                placement: 'append',
+            },
+        },
+    ];
+}
+/** @deprecated Use getManagedHookEntries instead. */
+export function getManagedHookEvents(platform = process.platform) {
+    const entries = getManagedHookEntries(platform);
+    const result = {};
+    for (const entry of entries) {
+        if (!result[entry.event]) {
+            result[entry.event] = entry.definition;
+        }
+    }
+    return result;
+}
+export const EMPTY_APPROVALS = {
+    version: 1,
+    approvals: [],
+};

package/dist/egress-daemon.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/egress-daemon.js

@@ -0,0 +1,52 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { belayStateDir, loadApprovalState, loadConfigFile, repoLocalStateDirFor, } from './config-io.js';
+import { scrubOptionsFromConfig } from './core/config.js';
+import { startEgressProxy as bindEgressProxy } from './core/egress/proxy-server.js';
+import { scrubValue } from './core/scrub.js';
+import { clearEgressDaemonState, createEgressApprovalStore, writeEgressDaemonState, } from './services/egress-service.js';
+async function main() {
+    const repoRoot = process.env.BELAY_EGRESS_REPO_ROOT;
+    if (!repoRoot) {
+        process.stderr.write('BELAY_EGRESS_REPO_ROOT is required.\n');
+        process.exitCode = 1;
+        return;
+    }
+    const config = await loadConfigFile(repoRoot);
+    if (!config.egress.enabled) {
+        process.stderr.write('egress.enabled is false; refusing to start daemon.\n');
+        process.exitCode = 1;
+        return;
+    }
+    const store = createEgressApprovalStore(repoRoot, config);
+    const stateDir = belayStateDir(config, repoLocalStateDirFor(repoRoot, config));
+    const auditPath = path.join(repoRoot, config.audit.logPath);
+    const { server, host, port } = await bindEgressProxy({
+        config,
+        repoRoot,
+        store,
+        async loadApproved() {
+            return loadApprovalState(repoRoot, 'approved-approvals.json', config);
+        },
+        async onAudit(event) {
+            await mkdir(path.dirname(auditPath), { recursive: true });
+            const record = { timestamp: new Date().toISOString(), ...event };
+            const scrubbed = scrubValue(record, scrubOptionsFromConfig(config));
+            await writeFile(auditPath, `${JSON.stringify(scrubbed)}\n`, { encoding: 'utf8', flag: 'a' });
+        },
+    });
+    await writeEgressDaemonState({ stateDir, pid: process.pid, host, port, repoRoot });
+    const shutdown = async () => {
+        server.close();
+        await clearEgressDaemonState(stateDir);
+        process.exit(0);
+    };
+    process.on('SIGTERM', () => {
+        void shutdown();
+    });
+    process.on('SIGINT', () => {
+        void shutdown();
+    });
+    process.stdout.write(`egress proxy listening on ${host}:${port} for ${repoRoot}\n`);
+}
+await main();

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { claudeAdapter } from './adapters/claude/adapter.js';
+export { cursorAdapter } from './adapters/cursor/adapter.js';
+export { getAdapter, listAdapters } from './adapters/registry.js';
+export type { BelayAdapter } from './adapters/types.js';
+export { doctorProject, formatDoctorReport } from './commands/doctor.js';
+export { explainCommand, formatExplainReport } from './commands/explain.js';
+export { formatRecoverReport, recoverProject } from './commands/recover.js';
+export { formatReport, reportProject } from './commands/report.js';
+export { revokeApproval } from './commands/revoke.js';
+export { formatStatusReport, statusProject } from './commands/status.js';
+export { GATE_CONTRACT_VERSION, type GatedAction, type GateVerdict, } from './core/gate-contract.js';
+export { classifyShell, classifySubagent, classifyToolUse, DEFAULT_CONFIG_V2, DEFAULT_CONFIG_V3, mergeConfig, migrateConfig, } from './core/index.js';
+export { initProject, upgradeProject } from './installer.js';
+export { resolveNodeBinary } from './node-resolution.js';
+export { applyConfigPreset, CONFIG_PRESETS, type ConfigPresetName } from './presets.js';
+export type { ApprovalRecord, ApprovalStateFile, Assessment, AuditVisibilityReport, BelayConfig, BelayConfigV1, BelayConfigV2, BelayConfigV3, ClassifyResult, DoctorOptions, DoctorReport, ExplainOptions, ExplainReport, InitOptions, RecoverOptions, RecoverReport, ReportOptions, RevokeOptions, StatusOptions, StatusReport, UpgradeOptions, } from './types.js';
+export { PACKAGE_VERSION } from './version.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+export { claudeAdapter } from './adapters/claude/adapter.js';
+export { cursorAdapter } from './adapters/cursor/adapter.js';
+export { getAdapter, listAdapters } from './adapters/registry.js';
+export { doctorProject, formatDoctorReport } from './commands/doctor.js';
+export { explainCommand, formatExplainReport } from './commands/explain.js';
+export { formatRecoverReport, recoverProject } from './commands/recover.js';
+export { formatReport, reportProject } from './commands/report.js';
+export { revokeApproval } from './commands/revoke.js';
+export { formatStatusReport, statusProject } from './commands/status.js';
+export { GATE_CONTRACT_VERSION, } from './core/gate-contract.js';
+export { classifyShell, classifySubagent, classifyToolUse, DEFAULT_CONFIG_V2, DEFAULT_CONFIG_V3, mergeConfig, migrateConfig, } from './core/index.js';
+export { initProject, upgradeProject } from './installer.js';
+export { resolveNodeBinary } from './node-resolution.js';
+export { applyConfigPreset, CONFIG_PRESETS } from './presets.js';
+export { PACKAGE_VERSION } from './version.js';

package/dist/installer/bootstrap.d.ts

@@ -0,0 +1,5 @@
+import type { ScopedPaths } from '../adapters/layouts/scope.js';
+import type { AdapterName } from '../adapters/layouts/types.js';
+import type { BelayConfigV3 } from '../core/config.js';
+export declare function bootstrapStateFiles(repoRoot: string, config: BelayConfigV3, paths: ScopedPaths): Promise<void>;
+export declare function writeSkillArtifacts(adapterName: AdapterName, paths: ScopedPaths): Promise<void>;

package/dist/installer/bootstrap.js

@@ -0,0 +1,61 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { approvedApprovalsPath, pendingApprovalsPath } from '../config-io.js';
+import { EMPTY_APPROVALS } from '../defaults.js';
+const BUNDLED_SKILL_TEMPLATE_URL = new URL('../../skills/belay/SKILL.md', import.meta.url);
+const BUNDLED_COMMAND_TEMPLATES = [
+    'belay-approve.md',
+    'belay-why.md',
+    'belay-explain.md',
+    'belay-status.md',
+    'belay-report.md',
+    'belay-recover.md',
+];
+async function readBundledTemplate(fileUrl) {
+    try {
+        return await readFile(fileUrl, 'utf8');
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : 'Unknown read failure.';
+        throw new Error(`Bundled template missing at ${fileUrl.pathname}: ${detail}`);
+    }
+}
+async function writeJsonIfMissing(filePath, value) {
+    if (existsSync(filePath)) {
+        return;
+    }
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+async function writeTextIfMissing(filePath, content) {
+    if (existsSync(filePath)) {
+        return;
+    }
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, content, 'utf8');
+}
+export async function bootstrapStateFiles(repoRoot, config, paths) {
+    await mkdir(paths.repoLocalStateDir, { recursive: true });
+    await mkdir(path.join(paths.repoLocalStateDir, 'runtime'), { recursive: true });
+    await writeJsonIfMissing(pendingApprovalsPath(repoRoot, config), EMPTY_APPROVALS);
+    await writeJsonIfMissing(approvedApprovalsPath(repoRoot, config), EMPTY_APPROVALS);
+    const auditPath = path.join(repoRoot, config.audit.logPath);
+    if (!existsSync(auditPath)) {
+        await mkdir(path.dirname(auditPath), { recursive: true });
+        await writeFile(auditPath, '', 'utf8');
+    }
+    await writeTextIfMissing(path.join(paths.repoLocalStateDir, 'audit.ndjson'), '');
+}
+export async function writeSkillArtifacts(adapterName, paths) {
+    await mkdir(paths.skillsDir, { recursive: true });
+    const bundledSkill = await readBundledTemplate(BUNDLED_SKILL_TEMPLATE_URL);
+    await writeFile(path.join(paths.skillsDir, 'SKILL.md'), bundledSkill, 'utf8');
+    if (adapterName === 'cursor' && paths.commandsDir) {
+        await mkdir(paths.commandsDir, { recursive: true });
+        for (const fileName of BUNDLED_COMMAND_TEMPLATES) {
+            const bundledCommand = await readBundledTemplate(new URL(`../../skills/belay/${fileName}`, import.meta.url));
+            await writeFile(path.join(paths.commandsDir, fileName), bundledCommand, 'utf8');
+        }
+    }
+}

package/dist/installer/runtime-artifacts.d.ts

@@ -0,0 +1,3 @@
+import type { ScopedPaths } from '../adapters/layouts/scope.js';
+import type { AdapterName } from '../adapters/layouts/types.js';
+export declare function writeRuntimeArtifacts(adapterName: AdapterName, paths: ScopedPaths): Promise<void>;

package/dist/installer/runtime-artifacts.js

@@ -0,0 +1,23 @@
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildRunnerScript, buildWindowsRunnerScript } from '../node-resolution.js';
+import { renderAuditHook, renderBeforeSubmitHook, renderRuntimeCore, renderShellGateHook, renderToolGateHook, } from '../templates.js';
+async function writeFileMaybeExecutable(filePath, content, executable = false) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, content, 'utf8');
+    if (executable) {
+        await chmod(filePath, 0o755);
+    }
+}
+export async function writeRuntimeArtifacts(adapterName, paths) {
+    const { hooksDir, runtimeDir } = paths;
+    await mkdir(hooksDir, { recursive: true });
+    await mkdir(runtimeDir, { recursive: true });
+    await writeFileMaybeExecutable(path.join(hooksDir, 'belay-before-submit.mjs'), renderBeforeSubmitHook());
+    await writeFileMaybeExecutable(path.join(hooksDir, 'belay-shell-gate.mjs'), renderShellGateHook());
+    await writeFileMaybeExecutable(path.join(hooksDir, 'belay-tool-gate.mjs'), renderToolGateHook());
+    await writeFileMaybeExecutable(path.join(hooksDir, 'belay-audit.mjs'), renderAuditHook());
+    await writeFileMaybeExecutable(path.join(runtimeDir, 'core.mjs'), await renderRuntimeCore(adapterName));
+    await writeFileMaybeExecutable(path.join(hooksDir, 'belay-runner'), buildRunnerScript(process.execPath), true);
+    await writeFileMaybeExecutable(path.join(hooksDir, 'belay-runner.cmd'), buildWindowsRunnerScript(process.execPath));
+}

package/dist/installer/scope-config.d.ts

@@ -0,0 +1,8 @@
+import { type ScopedPaths } from '../adapters/layouts/scope.js';
+import type { AdapterName } from '../adapters/layouts/types.js';
+import type { BelayConfigV4 } from '../core/config.js';
+import type { InitOptions, UpgradeOptions } from '../types.js';
+export type OperationScope = 'project' | 'global';
+export declare function resolveOperationScope(repoRoot: string, adapter: AdapterName, options?: InitOptions | UpgradeOptions): Promise<OperationScope>;
+export declare function applyInstallScope(repoRoot: string, adapter: AdapterName, scope: OperationScope, config?: BelayConfigV4): Promise<BelayConfigV4>;
+export declare function pathsForOperation(adapter: AdapterName, scope: OperationScope, repoRoot: string): ScopedPaths;

package/dist/installer/scope-config.js

@@ -0,0 +1,25 @@
+import { existsSync } from 'node:fs';
+import { getAdapterLayout } from '../adapters/layouts/index.js';
+import { resolveInstallScope, resolveScopedPaths, } from '../adapters/layouts/scope.js';
+import { loadConfigFile, writeConfigFile } from '../config-io.js';
+export async function resolveOperationScope(repoRoot, adapter, options = {}) {
+    const layout = getAdapterLayout(adapter);
+    let persisted;
+    if (existsSync(layout.configPath(repoRoot))) {
+        const config = await loadConfigFile(repoRoot, adapter);
+        persisted = config.installScope;
+    }
+    return resolveInstallScope(options, persisted);
+}
+export async function applyInstallScope(repoRoot, adapter, scope, config) {
+    const current = config ?? (await loadConfigFile(repoRoot, adapter));
+    if (current.installScope === scope) {
+        return current;
+    }
+    const updated = { ...current, installScope: scope };
+    await writeConfigFile(repoRoot, updated, adapter);
+    return updated;
+}
+export function pathsForOperation(adapter, scope, repoRoot) {
+    return resolveScopedPaths(getAdapterLayout(adapter), scope, repoRoot);
+}

package/dist/installer.d.ts

@@ -0,0 +1,22 @@
+import type { AdapterName } from './adapters/layouts/types.js';
+import type { HooksFile, InitOptions, UpgradeOptions } from './types.js';
+export type { InstallScope } from './adapters/layouts/scope.js';
+export declare function loadHooksFile(hooksPath: string): Promise<HooksFile>;
+export declare function mergeHooksFile(current: HooksFile, platform?: NodeJS.Platform, hooksDir?: string, repoRoot?: string): HooksFile;
+export declare function initCursorProject(options?: InitOptions): Promise<{
+    repoRoot: string;
+    withSkill: boolean;
+}>;
+export declare function upgradeCursorProject(options?: UpgradeOptions): Promise<{
+    repoRoot: string;
+}>;
+export declare function initProject(options?: InitOptions): Promise<{
+    repoRoot: string;
+    withSkill: boolean;
+    dogfood: boolean;
+    adapter: AdapterName;
+}>;
+export declare function upgradeProject(options?: UpgradeOptions): Promise<{
+    repoRoot: string;
+    adapter: AdapterName;
+}>;