@bobobowis/jev-kit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IndyDevDan / AgenticEngineer.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,241 @@
-# Temporary Holding Version
+# @bobobowis/jev-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Jev, TypeSafe AI's System One decision model, as a typed client, guards, file reads, agent tools,
+hooks, an MCP server, and a CLI. Zero runtime dependencies. Node 22.18 or later.
+
+Jev answers typed questions about a state (yes or no, pick one of your options, a position on your
+scale) in about 300 ms for a fraction of a cent. This package is the reusable part of
+[10 Levels of Jev](https://github.com/bobobowis/ten-levels-of-jev): the client and the decisions the lab teaches, packaged so a
+project or a coding agent can use them directly.
+
+## Install
+
+```bash
+npm install @bobobowis/jev-kit        # or: pnpm add @bobobowis/jev-kit
+npx jev --help
+```
+
+Or run the command without installing anything:
+
+```bash
+npx @bobobowis/jev-kit gate "Is this ticket about billing?" --state "I was charged twice this month"
+npx @bobobowis/jev-kit setup --harness claude --guards bash,write --tools ask_jev
+```
+
+Run through `npx` or `pnpm dlx`, `jev setup` writes `npx -y @bobobowis/jev-kit@<version>` into the
+hooks and the MCP entry, not a path into the npx cache, so the config keeps working after the cache is cleared.
+Installed in the project, it writes node and the installed bin.
+
+## Keys
+
+Everything reads `TYPESAFE_API_KEY`, or else `OPENROUTER_API_KEY`, from the environment. Without one,
+calls fail with an error; nothing quietly falls back to the mock. `--mock` (CLI) or
+`new JevClient({ provider: "mock" })` selects the offline mock explicitly. The mock is a
+deterministic stand-in for tests and wiring, not a model: its answers are not judgments.
+
+## The library
+
+```ts
+import { JevClient, noul, choice, score } from "@bobobowis/jev-kit";
+
+const jev = new JevClient();              // TypeSafe or OpenRouter from the environment; { provider: "mock" } offline
+const { answers } = await jev.systemOne(
+  { ticket: "The export button has done nothing since Tuesday's release." },
+  {
+    bug: noul("Does the ticket report something broken?"),
+    area: choice("Which area is it about?", { billing: "Payments and invoices", export: "Exporting data", other: "None of these" }),
+    urgency: score("How urgent is it?", ["Whenever", "This week", "Today, people are blocked"]),
+  },
+);
+console.log(answers.bug, answers.area, answers.urgency);
+```
+
+Each entry point is one layer of the lab. The functions that call Jev take an optional `decide`
+function last, so tests and other clients plug in without a key.
+
+| Import | What it has |
+|---|---|
+| `@bobobowis/jev-kit` | `JevClient`, `jev` (a shared client), the `noul`, `choice`, and `score` builders, `MockJev`, the wire types, `validateRequest`, `LIMITS` |
+| `/policy` | `normalized`, `weighted` (scores to numbers), `CONFIDENCE`, `confidenceBand` (floor, middle, bar) |
+| `/guards` | `gateBashCommand(command, cwd)`, `gateWriteCall(path, content, repo)`, `screenToolResult(tool, content)`: the Level 6 gates, with their questions and thresholds |
+| `/compact` | `evaluateCompaction`, `decideTier`, `tierMessage`, `compactVerdict`, `cutPointQuestion`: the Level 7 advisor |
+| `/files` | `readFileState` (a file as state, never outside `cwd`), `askFileBool`, `askFileChoice`, `askFileScore`, `askFiles` (one call per file, in parallel), `pickFirstFile`, `askJev`, `assembleState` |
+| `/tools` | the agent tools as harness-neutral `JevTool` objects (`ALL_TOOLS`, `LEVEL_TOOLS`, `selectTools`), `ASK_JEV_DESCRIPTION`, `runCommand`, `gatedRunner` |
+| `/hooks` | `handleHook` (normalized events), `runHarnessHook` (a Claude Code or Codex payload in, the harness's answer out), transcript usage readers |
+| `/setup` | `plan` and `apply`, behind `jev setup` |
+| `/events` | `createReporter`, `createDecider`, `parseEventLine`: the event channel below |
+| `/ledger` | `emptyLedger`, `record`, `summarize`: Jev spend per session |
+| `/capabilities` | `CAPABILITIES`, `capability(level, option, harness)`: the support table below |
+
+```ts
+import { gateBashCommand } from "@bobobowis/jev-kit/guards";
+import { askFileBool } from "@bobobowis/jev-kit/files";
+
+const verdict = await gateBashCommand("git push --force origin main", process.cwd());
+if (verdict.block) console.error(verdict.reason);
+
+const r = await askFileBool("src/billing.ts", "Does this file round money anywhere?", process.cwd());
+console.log(r.answer, r.noul);   // your script, or the agent, never loads the file
+```
+
+## The jev command
+
+Results go to stdout as JSON, diagnostics to stderr, so stdout pipes straight into `jq`. Every
+command takes `--help`, and the ones that call Jev take `--mock`.
+
+**`jev ask`**: one question block about your own state, files code reads for you, and a command's
+output.
+
+```bash
+jev ask --questions '{"risky":{"type":"score","instructions":"How risky is the change in output?","criteria":["Docs only","Some callers","Auth or billing, no tests"]}}' \
+        --command "git diff HEAD~1" | jq .answers.risky.score
+jev ask --questions @questions.json --state "customer says export fails" --paths "src/**/*.ts"
+```
+
+**`jev files`**: the same block once per file, in parallel.
+
+```bash
+jev files "src/**/*.ts" --questions '{"todo":{"type":"noul","instructions":"Does this file leave work unfinished?"}}' | jq '.results[] | {path, answers}'
+```
+
+**`jev gate`**: the smart if. The exit code is the answer.
+
+```bash
+jev gate "Is this ticket about billing?" --state "I was charged twice this month" && echo billing
+```
+
+**`jev guard`**: the Level 6 gates on a command or a file write.
+
+```bash
+jev guard bash "git push --force origin main"           # block: ... exit 1
+echo 'API_KEY=sk-live-4f9a...' | jev guard write .env    # block: ... exit 1
+```
+
+**`jev setup`**, **`jev hook`**, and **`jev mcp`** are below.
+
+| Command | Exit codes |
+|---|---|
+| `ask`, `files` | 0 answered, 1 refused or failed (the reason is on stderr), 2 bad options |
+| `gate` | 0 yes (at or above `--threshold`, default 0.5), 1 no, 2 bad options or a state that cannot be sent, 3 Jev could not answer |
+| `guard` | 0 allow, 1 block, 2 bad options, 3 Jev could not answer |
+| `setup` | 0 written (or printed with `--dry-run`), 1 a config it can't safely merge, 2 bad options |
+| `hook` | 0 always, 1 bad options; never 2, which both harnesses read as "block" |
+
+`gate` and `guard` exit 3 instead of guessing when Jev cannot answer, so the script decides whether
+that fails open or closed. A pre-commit hook that blocks commits adding a live credential, and lets
+commits through when Jev is unreachable:
+
+```sh
+#!/bin/sh
+# .git/hooks/pre-commit
+jev gate "Does output add a real credential (an API key, token, password, or private key with a real-looking value), not a placeholder?" \
+  --command "git diff --cached" --threshold 0.7
+case $? in
+  0) echo "pre-commit: this commit seems to add a credential; remove it or commit with --no-verify." >&2; exit 1 ;;
+  3) echo "pre-commit: Jev unavailable, not checked." >&2 ;;
+esac
+exit 0
+```
+
+## jev setup
+
+Writes or merges the MCP entry and the hooks into a project's agent config, and leaves everything
+else alone:
+
+```bash
+jev setup --harness claude --guards bash,write,result --tools ask_jev    # .claude/settings.json, .mcp.json
+jev setup --harness codex  --guards bash,write --compact                  # a marked block in .codex/config.toml
+jev setup --harness claude --level 6 --dry-run                            # print, write nothing
+```
+
+Each run sets the whole selection and replaces only what an earlier run wrote. A settings file that
+is not valid JSON is refused, never overwritten. Codex asks you to trust the project and its hooks
+the first time.
+
+## Use the Jev tools in any MCP client
+
+`jev mcp` serves the agent tools over stdio MCP:
+
+| Tool | What it answers |
+|---|---|
+| `should_i_compact` | whether now is a good moment to compact (needs the Level 7 hooks' notes) |
+| `ask_jev_file_bool`, `_choice`, `_score` | a yes or no, a pick, or a score about one file the agent never loads |
+| `ask_jev_files`, `pick_first_file` | the same questions over many files in parallel, then which to open first |
+| `ask_jev` | any question block over the agent's own state, file paths, and a command's output |
+
+```bash
+jev mcp --level 8                    # the lab's levels 7 to 10
+jev mcp --tools ask_jev,ask_jev_files
+```
+
+Claude Code, in `.mcp.json`:
+
+```json
+{ "mcpServers": { "jev": { "command": "jev", "args": ["mcp", "--tools", "ask_jev"] } } }
+```
+
+Codex, in `~/.codex/config.toml` or a trusted project's `.codex/config.toml`:
+
+```toml
+[mcp_servers.jev]
+command = "jev"
+args = ["mcp", "--tools", "ask_jev"]
+default_tools_approval_mode = "approve"
+env_vars = ["TYPESAFE_API_KEY", "OPENROUTER_API_KEY"]   # Codex starts MCP servers without your environment
+```
+
+Or let `jev setup` write either one.
+
+## Hooks: guards and the compaction advisor
+
+`jev hook` runs as a Claude Code or Codex hook. It reads the hook payload on stdin and answers in the
+harness's own format.
+
+- **Guards.** `PreToolUse` runs the bash gate on shell commands and the write gate on file writes
+  (`Write`, `Edit`, `MultiEdit`, `NotebookEdit`, Codex's `apply_patch`). A block denies the call.
+  `PostToolUse` screens `Read` and `Bash` output for instructions aimed at the agent and attaches a
+  banner.
+- **Compaction advisor.** `UserPromptSubmit` and `Stop` ask four questions after each turn and, when
+  the work has moved on and context is high, tell the agent on the next prompt to ask you to run
+  `/compact`.
+
+```bash
+echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git push --force origin main"},"cwd":"."}' \
+  | jev hook --harness claude --event PreToolUse --guards bash
+```
+
+Hooks fail open: a missing key, a Jev error, or a timeout (8 s by default) allows the action and
+reports an error. They never exit 2. The contracts they rely on are in
+[docs/NOTES-claude.md](docs/NOTES-claude.md) and [docs/NOTES-codex.md](docs/NOTES-codex.md).
+
+## Support by harness
+
+The same table is exported as `CAPABILITIES` from `@bobobowis/jev-kit/capabilities`.
+
+<!-- jev:matrix (generated by `pnpm run docs` from packages/jev-kit/src/capabilities.ts) -->
+
+| Level | pi | Claude Code | Codex | Generic MCP |
+|---|---|---|---|---|
+| 6 A Bash gate | full | full | full | unavailable (an MCP client has no hooks) |
+| 6 B Write gate | full | full | full (apply_patch is read from the patch text) | unavailable (an MCP client has no hooks) |
+| 6 C Result screen | full | degraded (the banner is added as context, not above the output) | degraded (the banner is added as context, not above the output) | unavailable (an MCP client has no hooks) |
+| 7 A Turn end hook | full | degraded (advisory after each turn, delivered on the next prompt; no compact_now) | degraded (advisory after each turn, delivered on the next prompt; no compact_now) | unavailable (an MCP client has no turn end hook) |
+| 7 B On demand tool | full | degraded (no compact_now; the agent asks you to run /compact) | degraded (no compact_now; Codex can't compact from a tool) | degraded (no compact_now) |
+| 7 C Pick the cut point | full | unavailable (Claude Code doesn't let a hook choose where to cut) | unavailable (Codex doesn't let a hook choose where to cut) | unavailable (an MCP client has no compaction hook) |
+| 8 A ask_jev_file_bool | full | full | full (the built-in shell can't be removed) | full |
+| 8 B ask_jev_file_choice | full | full | full (the built-in shell can't be removed) | full |
+| 8 C ask_jev_file_score | full | full | full (the built-in shell can't be removed) | full |
+| 9 A Several paths, one block | full | full | full (the built-in shell can't be removed) | full |
+| 9 B A glob over a directory | full | full | full (the built-in shell can't be removed) | full |
+| 9 C Recursive, then pick first | full | full | full (the built-in shell can't be removed) | full |
+| 10 A Triage a failure | full | full | full (the built-in shell can't be removed) | full |
+| 10 B Judge a diff before shipping | full | full | full (the built-in shell can't be removed) | full |
+| 10 C Classify a request, gate a plan | full | full | full (the built-in shell can't be removed) | full |
+
+<!-- /jev:matrix -->
+
+## Events
+
+Every Jev call and hook decision is reported as one JSON line: to `$JEV_EVENT_DIR/<harness>-<pid>.jsonl`
+when that is set, otherwise to stderr prefixed `JEV_EVENT `. The lab uses this to show hooks and
+tool calls live. `ask`, `files`, `gate`, and `guard` keep stderr quiet unless `JEV_EVENT_DIR` is set.

package/dist/capabilities.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What each agent level and option can do in each harness. The lab serves it with every level and
+ * the READMEs' table is generated from it, so the docs and the UI can't disagree.
+ *   full: behaves as the level teaches it.
+ *   degraded: runs, with the difference in the note.
+ *   unavailable: the harness has no place for it; the lab won't start it.
+ */
+export type Harness = "pi" | "claude" | "codex" | "mcp";
+export type Status = "full" | "degraded" | "unavailable";
+export interface Support {
+    status: Status;
+    note?: string;
+}
+export type OptionKey = "A" | "B" | "C";
+export declare const HARNESS_LABELS: Record<Harness, string>;
+export declare const HARNESS_ORDER: Harness[];
+export declare const CAPABILITIES: Record<number, {
+    name: string;
+    options: Record<OptionKey, {
+        name: string;
+        support: Record<Harness, Support>;
+    }>;
+}>;
+/** One option's support in one harness; levels without hooks or tools (1 to 5) are full everywhere. */
+export declare function capability(level: number, option: string, harness: Harness): Support;
+/** Every option's support for a level, or null for a level that doesn't run in an agent. */
+export declare function levelCapabilities(level: number): Record<OptionKey, Record<Harness, Support>> | null;
+/** The matrix as a Markdown table, the one the READMEs carry between their jev:matrix markers. */
+export declare function matrixMarkdown(): string;
+export declare const MATRIX_START = "<!-- jev:matrix (generated by `pnpm run docs` from packages/jev-kit/src/capabilities.ts) -->";
+export declare const MATRIX_END = "<!-- /jev:matrix -->";
+/** Replace the table between the markers, in the text's own line endings; unchanged without markers. */
+export declare function withMatrix(text: string): string;

package/dist/capabilities.js

@@ -0,0 +1,81 @@
+export const HARNESS_LABELS = {
+    pi: "pi", claude: "Claude Code", codex: "Codex", mcp: "Generic MCP",
+};
+export const HARNESS_ORDER = ["pi", "claude", "codex", "mcp"];
+const full = (note) => (note ? { status: "full", note } : { status: "full" });
+const degraded = (note) => ({ status: "degraded", note });
+const unavailable = (note) => ({ status: "unavailable", note });
+const NO_HOOKS = unavailable("an MCP client has no hooks");
+const ADVISORY = "advisory after each turn, delivered on the next prompt; no compact_now";
+const TOOLS_FULL = {
+    pi: full(), claude: full(), codex: full("the built-in shell can't be removed"), mcp: full(),
+};
+export const CAPABILITIES = {
+    6: { name: "Guardrail hooks", options: {
+            A: { name: "Bash gate", support: { pi: full(), claude: full(), codex: full(), mcp: NO_HOOKS } },
+            B: { name: "Write gate", support: { pi: full(), claude: full(), codex: full("apply_patch is read from the patch text"), mcp: NO_HOOKS } },
+            C: { name: "Result screen", support: {
+                    pi: full(), claude: degraded("the banner is added as context, not above the output"),
+                    codex: degraded("the banner is added as context, not above the output"), mcp: NO_HOOKS,
+                } },
+        } },
+    7: { name: "Should I compact", options: {
+            A: { name: "Turn end hook", support: { pi: full(), claude: degraded(ADVISORY), codex: degraded(ADVISORY), mcp: unavailable("an MCP client has no turn end hook") } },
+            B: { name: "On demand tool", support: { pi: full(), claude: degraded("no compact_now; the agent asks you to run /compact"), codex: degraded("no compact_now; Codex can't compact from a tool"), mcp: degraded("no compact_now") } },
+            C: { name: "Pick the cut point", support: {
+                    pi: full(), claude: unavailable("Claude Code doesn't let a hook choose where to cut"),
+                    codex: unavailable("Codex doesn't let a hook choose where to cut"), mcp: unavailable("an MCP client has no compaction hook"),
+                } },
+        } },
+    8: { name: "Cheap reads", options: {
+            A: { name: "ask_jev_file_bool", support: TOOLS_FULL },
+            B: { name: "ask_jev_file_choice", support: TOOLS_FULL },
+            C: { name: "ask_jev_file_score", support: TOOLS_FULL },
+        } },
+    9: { name: "Files at scale", options: {
+            A: { name: "Several paths, one block", support: TOOLS_FULL },
+            B: { name: "A glob over a directory", support: TOOLS_FULL },
+            C: { name: "Recursive, then pick first", support: TOOLS_FULL },
+        } },
+    10: { name: "Agentic Jev", options: {
+            A: { name: "Triage a failure", support: TOOLS_FULL },
+            B: { name: "Judge a diff before shipping", support: TOOLS_FULL },
+            C: { name: "Classify a request, gate a plan", support: TOOLS_FULL },
+        } },
+};
+/** One option's support in one harness; levels without hooks or tools (1 to 5) are full everywhere. */
+export function capability(level, option, harness) {
+    return CAPABILITIES[level]?.options[option]?.support[harness] ?? full();
+}
+/** Every option's support for a level, or null for a level that doesn't run in an agent. */
+export function levelCapabilities(level) {
+    const l = CAPABILITIES[level];
+    if (!l)
+        return null;
+    return { A: l.options.A.support, B: l.options.B.support, C: l.options.C.support };
+}
+const cell = (s) => (s.note ? `${s.status} (${s.note})` : s.status);
+/** The matrix as a Markdown table, the one the READMEs carry between their jev:matrix markers. */
+export function matrixMarkdown() {
+    const rows = [
+        `| Level | ${HARNESS_ORDER.map((h) => HARNESS_LABELS[h]).join(" | ")} |`,
+        `|---|${HARNESS_ORDER.map(() => "---").join("|")}|`,
+    ];
+    for (const [level, l] of Object.entries(CAPABILITIES)) {
+        for (const [key, o] of Object.entries(l.options)) {
+            rows.push(`| ${level} ${key} ${o.name} | ${HARNESS_ORDER.map((h) => cell(o.support[h])).join(" | ")} |`);
+        }
+    }
+    return rows.join("\n");
+}
+export const MATRIX_START = "<!-- jev:matrix (generated by `pnpm run docs` from packages/jev-kit/src/capabilities.ts) -->";
+export const MATRIX_END = "<!-- /jev:matrix -->";
+/** Replace the table between the markers, in the text's own line endings; unchanged without markers. */
+export function withMatrix(text) {
+    const a = text.indexOf(MATRIX_START), b = text.indexOf(MATRIX_END);
+    if (a < 0 || b < a)
+        return text;
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const table = matrixMarkdown().split("\n").join(eol);
+    return `${text.slice(0, a + MATRIX_START.length)}${eol}${eol}${table}${eol}${eol}${text.slice(b)}`;
+}

package/dist/cli/ask.d.ts

@@ -0,0 +1,9 @@
+import { type Io } from "./common.ts";
+export declare const ASK_HELP = "Usage: jev ask --questions <json|@file> [state options]\n\nPrints { answers, state_summary, usage, model } as JSON. Exit 0, 1 when the call is refused or fails, 2 for bad options.\n\n  --questions <json|@file>  the question block, keyed by question id\n  --state <text|json>  your own state, plain text or a JSON object\n  --state-file <file>  the same, read from a file\n  --paths <glob>       files for code to read into files[\"path\"]; repeat for more (up to 20 files)\n  --command <cmd>      a command for code to run; its result goes into output (passes the bash gate)\n  --cwd <dir>          where paths resolve and the command runs (default: here)\n  --mock               the offline mock instead of a Jev key\n";
+export declare const FILES_HELP = "Usage: jev files <glob|dir|file>... --questions <json|@file> [--recursive] [--cwd dir] [--mock]\n\nAsks the question block once per file, in parallel. Prints { results, skipped, calls } as JSON.\n";
+export declare const GATE_HELP = "Usage: jev gate \"<yes or no question>\" [state options] [--threshold 0.5] [--yes <text>] [--no <text>] [--json]\n\nExit 0 when the probability of yes is at or above the threshold, 1 below it, 2 for bad options or a\nstate that cannot be sent, 3 when Jev could not answer. The script chooses whether 3 fails open or closed.\n\n  --threshold <0..1>   default 0.5\n  --yes <text>         what counts as yes\n  --no <text>          what counts as no\n  --json               also print { noul, threshold, yes } on stdout\n  --state <text|json>  your own state, plain text or a JSON object\n  --state-file <file>  the same, read from a file\n  --paths <glob>       files for code to read into files[\"path\"]; repeat for more (up to 20 files)\n  --command <cmd>      a command for code to run; its result goes into output (passes the bash gate)\n  --cwd <dir>          where paths resolve and the command runs (default: here)\n  --mock               the offline mock instead of a Jev key\n";
+export declare const GUARD_HELP = "Usage: jev guard bash \"<command>\" | jev guard write <path> < content   [--cwd dir] [--json] [--mock]\n\nThe Level 6 gates. Prints allow or block with the reason. Exit 0 allow, 1 block, 2 bad options, 3 Jev error.\n";
+export declare function ask(argv: string[], io: Io): Promise<number>;
+export declare function files(argv: string[], io: Io): Promise<number>;
+export declare function gate(argv: string[], io: Io): Promise<number>;
+export declare function guard(argv: string[], io: Io): Promise<number>;

package/dist/cli/ask.js

@@ -0,0 +1,210 @@
+/**
+ * The general CLI, for scripts, CI, and git hooks:
+ *   jev ask     a question block about a state, files, and a command's output; JSON on stdout
+ *   jev files   the same question block about each file, in parallel
+ *   jev gate    one yes or no question; the answer is the exit code
+ *   jev guard   the Level 6 bash or write gate on a command or a file
+ * Results go to stdout, diagnostics to stderr. Events only go to JEV_EVENT_DIR, when it is set.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { noul } from "../core/helpers.js";
+import { QuestionValidationError } from "../core/types.js";
+import { AskStateError, assembleState } from "../files/assemble.js";
+import { gateBashCommand } from "../guards/bash-gate.js";
+import { gateWriteCall } from "../guards/write-gate.js";
+import { askJev } from "../tools/ask-jev.js";
+import { askJevFiles } from "../tools/file-tools.js";
+import { gatedRunner } from "../tools/run-command.js";
+import { deciderFor, readAll } from "./common.js";
+const STATE_OPTIONS = {
+    state: { type: "string" }, "state-file": { type: "string" }, paths: { type: "string", multiple: true },
+    command: { type: "string" }, cwd: { type: "string" }, mock: { type: "boolean" }, help: { type: "boolean", short: "h" },
+};
+const STATE_HELP = `  --state <text|json>  your own state, plain text or a JSON object
+  --state-file <file>  the same, read from a file
+  --paths <glob>       files for code to read into files["path"]; repeat for more (up to 20 files)
+  --command <cmd>      a command for code to run; its result goes into output (passes the bash gate)
+  --cwd <dir>          where paths resolve and the command runs (default: here)
+  --mock               the offline mock instead of a Jev key`;
+export const ASK_HELP = `Usage: jev ask --questions <json|@file> [state options]
+
+Prints { answers, state_summary, usage, model } as JSON. Exit 0, 1 when the call is refused or fails, 2 for bad options.
+
+  --questions <json|@file>  the question block, keyed by question id
+${STATE_HELP}
+`;
+export const FILES_HELP = `Usage: jev files <glob|dir|file>... --questions <json|@file> [--recursive] [--cwd dir] [--mock]
+
+Asks the question block once per file, in parallel. Prints { results, skipped, calls } as JSON.
+`;
+export const GATE_HELP = `Usage: jev gate "<yes or no question>" [state options] [--threshold 0.5] [--yes <text>] [--no <text>] [--json]
+
+Exit 0 when the probability of yes is at or above the threshold, 1 below it, 2 for bad options or a
+state that cannot be sent, 3 when Jev could not answer. The script chooses whether 3 fails open or closed.
+
+  --threshold <0..1>   default 0.5
+  --yes <text>         what counts as yes
+  --no <text>          what counts as no
+  --json               also print { noul, threshold, yes } on stdout
+${STATE_HELP}
+`;
+export const GUARD_HELP = `Usage: jev guard bash "<command>" | jev guard write <path> < content   [--cwd dir] [--json] [--mock]
+
+The Level 6 gates. Prints allow or block with the reason. Exit 0 allow, 1 block, 2 bad options, 3 Jev error.
+`;
+function parse(argv, options, io, help, name, positionals = false) {
+    try {
+        return parseArgs({ args: argv, options, strict: true, allowPositionals: positionals });
+    }
+    catch (err) {
+        io.stderr.write(`jev ${name}: ${err.message}\n\n${help}`);
+        return null;
+    }
+}
+const readQuestions = (raw) => (raw.startsWith("@") ? readFileSync(raw.slice(1), "utf8") : raw);
+function context(cwd, mock, io) {
+    const { reporter, decide } = deciderFor("cli", { mock, quiet: true, stderr: io.stderr, client: io.client });
+    return { cwd, harness: "cli", decide, report: (k, p) => reporter.report(k, p) };
+}
+function stateText(v) {
+    if (v["state-file"])
+        return readFileSync(v["state-file"], "utf8");
+    return v.state;
+}
+export async function ask(argv, io) {
+    const parsed = parse(argv, { ...STATE_OPTIONS, questions: { type: "string" } }, io, ASK_HELP, "ask");
+    if (!parsed)
+        return 2;
+    const v = parsed.values;
+    if (v.help) {
+        io.stdout.write(ASK_HELP);
+        return 0;
+    }
+    if (!v.questions) {
+        io.stderr.write("jev ask: --questions is required\n");
+        return 2;
+    }
+    let questions;
+    try {
+        questions = readQuestions(v.questions);
+    }
+    catch (err) {
+        io.stderr.write(`jev ask: cannot read ${v.questions}: ${err.message}\n`);
+        return 2;
+    }
+    const ctx = context(resolve(v.cwd ?? process.cwd()), v.mock, io);
+    const r = await askJev.execute({ questions_json: questions, state: stateText(v), paths: v.paths, command: v.command }, ctx);
+    if (r.isError) {
+        io.stderr.write(r.text + "\n");
+        return 1;
+    }
+    io.stdout.write(JSON.stringify(r.payload) + "\n");
+    return 0;
+}
+export async function files(argv, io) {
+    const parsed = parse(argv, { questions: { type: "string" }, recursive: { type: "boolean" }, cwd: { type: "string" }, mock: { type: "boolean" }, help: { type: "boolean", short: "h" } }, io, FILES_HELP, "files", true);
+    if (!parsed)
+        return 2;
+    const v = parsed.values;
+    if (v.help) {
+        io.stdout.write(FILES_HELP);
+        return 0;
+    }
+    if (!v.questions || !parsed.positionals.length) {
+        io.stderr.write(`jev files: pass one or more globs and --questions\n\n${FILES_HELP}`);
+        return 2;
+    }
+    let questions;
+    try {
+        questions = readQuestions(v.questions);
+    }
+    catch (err) {
+        io.stderr.write(`jev files: cannot read ${v.questions}: ${err.message}\n`);
+        return 2;
+    }
+    const ctx = context(resolve(v.cwd ?? process.cwd()), v.mock, io);
+    const r = await askJevFiles.execute({ paths_or_globs: parsed.positionals, questions_json: questions, recursive: v.recursive ?? false }, ctx);
+    if (r.isError) {
+        io.stderr.write(r.text + "\n");
+        return 1;
+    }
+    io.stdout.write(JSON.stringify(r.payload) + "\n");
+    return 0;
+}
+export async function gate(argv, io) {
+    const parsed = parse(argv, { ...STATE_OPTIONS, threshold: { type: "string" }, yes: { type: "string" }, no: { type: "string" }, json: { type: "boolean" } }, io, GATE_HELP, "gate", true);
+    if (!parsed)
+        return 2;
+    const v = parsed.values;
+    if (v.help) {
+        io.stdout.write(GATE_HELP);
+        return 0;
+    }
+    const question = parsed.positionals.join(" ").trim();
+    if (!question) {
+        io.stderr.write(`jev gate: the question is required\n\n${GATE_HELP}`);
+        return 2;
+    }
+    const threshold = v.threshold === undefined ? 0.5 : Number(v.threshold);
+    if (!(threshold >= 0 && threshold <= 1)) {
+        io.stderr.write("jev gate: --threshold must be between 0 and 1\n");
+        return 2;
+    }
+    const cwd = resolve(v.cwd ?? process.cwd());
+    const ctx = context(cwd, v.mock, io);
+    let assembled;
+    try {
+        assembled = await assembleState({ state: stateText(v), paths: v.paths, command: v.command }, cwd, gatedRunner(ctx));
+    }
+    catch (err) {
+        io.stderr.write(`jev gate: ${err instanceof AskStateError ? err.message : `cannot build the state: ${err?.message ?? err}`}\n`);
+        return err instanceof AskStateError ? 2 : 3;
+    }
+    const criteria = v.yes || v.no ? { true: v.yes, false: v.no } : undefined;
+    let answer;
+    try {
+        const { answers } = await ctx.decide("gate", assembled.state, { gate: noul(question, criteria) });
+        answer = answers.gate;
+    }
+    catch (err) {
+        io.stderr.write(`jev gate: ${err?.message ?? err}\n`);
+        return err instanceof QuestionValidationError ? 2 : 3;
+    }
+    const yes = answer.noul >= threshold;
+    if (v.json)
+        io.stdout.write(JSON.stringify({ noul: answer.noul, threshold, yes }) + "\n");
+    return yes ? 0 : 1;
+}
+export async function guard(argv, io) {
+    const parsed = parse(argv, { cwd: { type: "string" }, json: { type: "boolean" }, mock: { type: "boolean" }, help: { type: "boolean", short: "h" } }, io, GUARD_HELP, "guard", true);
+    if (!parsed)
+        return 2;
+    const v = parsed.values;
+    if (v.help) {
+        io.stdout.write(GUARD_HELP);
+        return 0;
+    }
+    const [kind, ...rest] = parsed.positionals;
+    const target = rest.join(" ").trim();
+    if ((kind !== "bash" && kind !== "write") || !target) {
+        io.stderr.write(`jev guard: pass bash "<command>" or write <path>\n\n${GUARD_HELP}`);
+        return 2;
+    }
+    const cwd = resolve(v.cwd ?? process.cwd());
+    const ctx = context(cwd, v.mock, io);
+    let d;
+    try {
+        d = kind === "bash"
+            ? await gateBashCommand(target, cwd, (s, q) => ctx.decide("guard bash", s, q))
+            : await gateWriteCall(target, await readAll(io.stdin), cwd, (s, q) => ctx.decide("guard write", s, q));
+    }
+    catch (err) {
+        io.stderr.write(`jev guard: ${err?.message ?? err}\n`);
+        return 3;
+    }
+    ctx.report("hook", { hook: `guard ${kind}`, [kind === "bash" ? "command" : "path"]: target, block: d.block, reason: d.reason });
+    io.stdout.write(v.json ? JSON.stringify(d) + "\n" : `${d.block ? "block" : "allow"}: ${d.reason}\n`);
+    return d.block ? 1 : 0;
+}

package/dist/cli/common.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What every subcommand shares: the client, the reporter, list flags, stdin, and a deadline.
+ */
+import { JevClient } from "../core/client.ts";
+import { type Decider, type Reporter } from "../events/index.ts";
+export interface Io {
+    stdout: {
+        write(s: string): unknown;
+    };
+    stderr: {
+        write(s: string): unknown;
+    };
+    stdin: AsyncIterable<string | Buffer>;
+    /** Tests inject a client; commands otherwise build one from --mock and the keys. */
+    client?: () => Pick<JevClient, "systemOne">;
+}
+export declare const processIo: () => Io;
+/**
+ * `--mock` selects the offline mock explicitly; otherwise the client picks TypeSafe or OpenRouter
+ * from the keys. A deadline gets its own client, so a call cut off by it is aborted, not left running.
+ */
+export declare function clientFor(mock: boolean | undefined, timeoutMs?: number): () => Pick<JevClient, "systemOne">;
+export declare function deciderFor(harness: string, opts: {
+    mock?: boolean;
+    quiet?: boolean;
+    stderr?: Io["stderr"];
+    timeoutMs?: number;
+    client?: Io["client"];
+}): {
+    reporter: Reporter;
+    decide: Decider;
+};
+export declare const list: (raw: string | undefined) => string[];
+export declare function readAll(stdin: Io["stdin"]): Promise<string>;
+/** Resolve with the work, or with `fallback` once `ms` pass. The work keeps running but nobody waits. */
+export declare function withDeadline<T>(work: Promise<T>, ms: number, fallback: () => T): Promise<T>;
+export declare class UsageError extends Error {
+}