@guilz-dev/belay 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,230 @@
+export type { BelayConfig, BelayConfigV1, BelayConfigV2, BelayConfigV3, BelayControlPlaneConfig, BelayEgressConfig, BelayMode, BelayOverridesConfig, BelayPolicyConfig, BelayRedactionConfig, BelaySandboxConfig, BelayTransactionalConfig, UnknownLocalEffectPolicy, } from './core/config.js';
+export type { ApprovalRecord, ApprovalStateFile, Assessment, ClassifyResult, HookVerdict, } from './core/types.js';
+import type { InstallScope } from './adapters/layouts/scope.js';
+import type { RecentAskEntry } from './core/audit-summary.js';
+import type { BelayEgressConfig, BelayOverridesConfig, BelayPolicyConfig, BelaySandboxConfig } from './core/config.js';
+import type { ApprovalRecord, ClassifyResult } from './core/types.js';
+export interface HookEntry {
+    command: string;
+    matcher?: string;
+}
+export interface HooksFile {
+    version: number;
+    hooks: Record<string, HookEntry[]>;
+}
+export type AdapterName = 'cursor' | 'claude' | 'codex';
+export interface InitOptions {
+    targetDir?: string;
+    withSkill?: boolean;
+    dogfood?: boolean;
+    adapter?: AdapterName;
+    scope?: InstallScope;
+    preset?: import('./presets.js').ConfigPresetName;
+    judgeProfile?: 'local-ollama';
+    judgeProvider?: 'ollama' | 'openai-compatible' | 'cursor';
+    judgeModel?: string;
+    judgeEndpoint?: string;
+    /** Acknowledge cloud judge egress + redaction limits (R19). Required for openai-compatible provider. */
+    acceptCloudJudge?: boolean;
+    /** When true, skip writing judge config (used when user declines cloud consent). */
+    skipJudgeWrite?: boolean;
+}
+export interface UpgradeOptions {
+    targetDir?: string;
+    withSkill?: boolean;
+    adapter?: AdapterName;
+    scope?: InstallScope;
+}
+export interface DoctorOptions {
+    targetDir?: string;
+    fix?: boolean;
+    dryRun?: boolean;
+    adapter?: AdapterName;
+}
+export interface DogfoodStatus {
+    active: boolean;
+    mode: string;
+    unknownLocalEffect: string;
+    readyForEnforce: boolean;
+    gateEvents: number;
+    wouldBlockCount: number;
+    wouldBlockRate: number;
+    notes: string[];
+}
+export interface ConfigProvenanceNote {
+    path: string;
+    source: 'builtin' | 'team' | 'repo' | 'protected';
+}
+export interface DoctorReport {
+    ok: boolean;
+    repoRoot: string;
+    configPath: string;
+    hooksPath: string;
+    nodeResolution: {
+        ok: boolean;
+        detail: string;
+        path?: string;
+    };
+    issues: string[];
+    notes: string[];
+    warnings: string[];
+    configProvenance: ConfigProvenanceNote[];
+    dogfood: DogfoodStatus | null;
+}
+export interface StatusOptions {
+    targetDir?: string;
+    json?: boolean;
+}
+export interface HealthSnapshotOptions {
+    targetDir?: string;
+    adapter?: AdapterName;
+}
+export interface HealthSnapshot {
+    repoRoot: string;
+    adapter: AdapterName;
+    installScope: 'project' | 'global';
+    configPath: string;
+    hooksPath: string;
+    skillPath: string;
+    commandsPath?: string;
+    configPresent: boolean;
+    hooksInstalled: boolean;
+    managedHooksOk: boolean;
+    runtimePresent: boolean;
+    skillInstalled: boolean;
+    skillOnly: boolean;
+    commandsInstalled: boolean;
+    floorInstalled: boolean;
+    missingArtifacts: string[];
+    judgeIssues: string[];
+    judgeWarnings: string[];
+    judgeNotes: string[];
+    containmentPosture: 'best-effort' | 'l1-full';
+    containmentWarnings: string[];
+    additionalRiskSignals: string[];
+    l1FullActive: boolean;
+}
+export interface ClassifyForReportResult {
+    repoRoot: string;
+    kind: ExplainKind;
+    input: string;
+    cwd: string;
+    config: import('./core/config.js').BelayConfigV3;
+    policy: BelayPolicyConfig;
+    overrides: BelayOverridesConfig;
+    egress: BelayEgressConfig;
+    egressProxyRunning: boolean;
+    sandbox: BelaySandboxConfig;
+    sandboxBrokerActive: boolean;
+    l1FullActive: boolean;
+    transactionalEligible: boolean;
+    permission: string;
+    tier: string;
+    result: ClassifyResult;
+}
+export interface StatusReport {
+    repoRoot: string;
+    approvalStateDir: string;
+    pending: ApprovalRecord[];
+    approved: ApprovalRecord[];
+    expiredPendingCount: number;
+    dogfood: DogfoodStatus;
+    health: HealthSnapshot;
+    visibility: AuditVisibilityReport;
+}
+export interface ReportOptions {
+    targetDir?: string;
+    since?: string;
+    until?: string;
+    limit?: number;
+    json?: boolean;
+}
+export interface AuditVisibilityReport {
+    repoRoot: string;
+    auditLogPath: string;
+    gateEvents: number;
+    askCount: number;
+    enforceAskCount: number;
+    auditAskCount: number;
+    unknownModeAskCount: number;
+    flagCount: number;
+    allowCount: number;
+    silentPassRate: number;
+    recentAsks: RecentAskEntry[];
+    warnings: string[];
+    notes: string[];
+}
+export interface RecoverOptions {
+    targetDir?: string;
+    since?: string;
+    fingerprint?: string;
+    command?: string;
+    limit?: number;
+    json?: boolean;
+}
+export interface RecoverReport {
+    repoRoot: string;
+    target?: {
+        timestamp?: string;
+        fingerprint?: string;
+        summary: string;
+        reason: string;
+        effect?: string;
+        location?: string;
+        permission?: string;
+    };
+    recoverable: boolean;
+    confidence: 'high' | 'medium';
+    disclaimer: string[];
+    advice: string[];
+    warnings: string[];
+}
+export interface DogfoodOptions {
+    targetDir?: string;
+    enforce?: boolean;
+    force?: boolean;
+    adapter?: AdapterName;
+}
+export interface DogfoodResult {
+    ok: boolean;
+    repoRoot: string;
+    message: string;
+    configPath: string;
+    mode: string;
+    unknownLocalEffect: string;
+}
+export type ExplainKind = 'shell' | 'tool' | 'subagent';
+export interface ExplainReport {
+    repoRoot: string;
+    kind: string;
+    command: string;
+    cwd: string;
+    policy: BelayPolicyConfig;
+    overrides: BelayOverridesConfig;
+    egress: BelayEgressConfig;
+    egressProxyRunning: boolean;
+    egressL3DemotionActive: boolean;
+    sandbox: BelaySandboxConfig;
+    sandboxBrokerActive: boolean;
+    l1FullActive: boolean;
+    transactionalEligible: boolean;
+    permission: string;
+    tier: string;
+    approvalId?: string;
+    result: ClassifyResult;
+}
+export interface ExplainOptions {
+    targetDir?: string;
+    command?: string;
+    cwd?: string;
+    json?: boolean;
+    kind?: ExplainKind;
+    toolName?: string;
+    payload?: Record<string, unknown>;
+    /** Re-classify the latest pending approval when no command is given. */
+    explainLastPending?: boolean;
+}
+export interface RevokeOptions {
+    targetDir?: string;
+    approvalId: string;
+}

package/dist/types.js

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

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const PACKAGE_VERSION = "0.0.1";

package/dist/version.js

@@ -0,0 +1 @@
+export const PACKAGE_VERSION = '0.0.1';

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@guilz-dev/belay",
+  "version": "0.1.0",
+  "description": "Belay-style approval and audit gating for agent runtimes.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/guilz-dev/belay.git"
+  },
+  "homepage": "https://github.com/guilz-dev/belay#readme",
+  "bugs": {
+    "url": "https://github.com/guilz-dev/belay/issues"
+  },
+  "keywords": [
+    "agent",
+    "belay",
+    "hooks",
+    "approval",
+    "audit",
+    "runtime-safety"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.29.3",
+  "bin": {
+    "belay": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "agent-belay-logo.png"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/build-runtime.mjs",
+    "lint": "biome check src package.json README.md CHANGELOG.md CONTRIBUTING.md SECURITY.md tsconfig.json tsconfig.build.json vitest.config.ts scripts docs",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm build && vitest run",
+    "test:stable": "pnpm build && vitest run && vitest run && vitest run",
+    "corpus": "pnpm build && node scripts/corpus.mjs"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.15",
+    "@types/node": "22.15.29",
+    "esbuild": "0.25.5",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
+  }
+}

package/skills/belay/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: belay
+description: >-
+  Guides approval when belay blocks a high-risk shell command, subagent launch,
+  or tool action. Use when an action is denied, blocked, or needs belay-approve, or when
+  installing or checking belay hook health in a repository.
+disable-model-invocation: true
+---
+
+# Belay
+
+Belay installs repo-local hooks that gate high-risk shell commands, tool actions, and
+subagent launches. Enforcement lives in hooks; this skill only explains the flow and
+routes you to the CLI. It does not classify commands itself.
+
+## Prerequisites
+
+Run `npx @guilz-dev/belay init` in the project root before relying on enforcement.
+If you only installed this skill via `npx skills add`, approval instructions are
+available, but the runtime gate is not installed yet. Run `belay doctor` to
+check whether hooks are present.
+
+## When belay blocks an action
+
+1. Read the approval ID in the deny message.
+2. Approve once with `/belay-approve <approval-id>` or `belay approve <approval-id>`.
+3. Retry the original action unchanged.
+
+For why it was blocked, use `/belay why <command>` or `belay explain --command "<command>"`.
+For the latest pending ask, use `/belay explain` or `belay explain`.
+For install health and audit visibility, use `/belay status` or `belay status`.
+For audit-only summary, use `/belay report` or `belay report`.
+For recovery advice after a block, use `/belay recover` or `belay recover`.
+
+## Install or repair
+
+- Full install: `npx @guilz-dev/belay init --with-skill`
+- Interactive wizard: `npx @guilz-dev/belay init-wizard`
+- Health check: `belay doctor`
+
+Do not run init or doctor implicitly from this skill — only when the user asks.
+
+## CLI mapping
+
+| User intent | Command |
+| --- | --- |
+| Why was this blocked? | `belay explain --command "..."` |
+| Explain latest pending ask | `belay explain` |
+| Status / dogfood / audit visibility | `belay status` |
+| Audit summary (read-only) | `belay report` |
+| Recovery advice (advisory only) | `belay recover` |
+| Approve once | `belay approve <id>` |

package/skills/belay/belay-approve.md

@@ -0,0 +1,7 @@
+Run after belay denies a high-risk action and returns an approval ID.
+
+```bash
+belay approve <approval-id>
+```
+
+Then retry the original action unchanged.

package/skills/belay/belay-explain.md

@@ -0,0 +1,11 @@
+Explain the latest pending belay approval, or a specific blocked action.
+
+```bash
+belay explain
+```
+
+If the user names a command, use:
+
+```bash
+belay explain --command "<command>"
+```

package/skills/belay/belay-recover.md

@@ -0,0 +1,13 @@
+Advisory recovery guidance for a recent blocked or destructive action (does not run commands).
+
+```bash
+belay recover
+```
+
+To target a specific command:
+
+```bash
+belay recover --command "rm important.ts"
+```
+
+Review each suggested step before running — recovery commands pass through belay hooks.

package/skills/belay/belay-report.md

@@ -0,0 +1,7 @@
+Show audit visibility: ask/flag/allow counts, silent-pass rate, and recent asks.
+
+```bash
+belay report
+```
+
+For full install health plus audit summary, use `belay status`.

package/skills/belay/belay-status.md

@@ -0,0 +1,9 @@
+Show belay install health, pending approvals, dogfood metrics, and audit visibility.
+
+```bash
+belay status
+```
+
+For audit-only summary: `belay report`. For recovery advice: `belay recover`.
+
+If hooks are missing, suggest `npx @guilz-dev/belay init` and `belay doctor`.

package/skills/belay/belay-why.md

@@ -0,0 +1,11 @@
+Explain why belay would classify a command. Pass the exact shell command in quotes.
+
+```bash
+belay explain --command "<command>"
+```
+
+Example:
+
+```bash
+belay explain --command "git push origin main"
+```