@bobobowis/jev-kit 0.0.0-stage → 0.2.0

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 {
+}

package/dist/cli/common.js

@@ -0,0 +1,40 @@
+/**
+ * What every subcommand shares: the client, the reporter, list flags, stdin, and a deadline.
+ */
+import { JevClient, sharedJev } from "../core/client.js";
+import { createDecider, createReporter } from "../events/index.js";
+export const processIo = () => ({ stdout: process.stdout, stderr: process.stderr, stdin: process.stdin });
+/**
+ * `--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 function clientFor(mock, timeoutMs) {
+    if (!mock && !timeoutMs)
+        return sharedJev;
+    let client;
+    return () => (client ??= new JevClient(mock ? { provider: "mock" } : { timeoutMs }));
+}
+export function deciderFor(harness, opts) {
+    const reporter = createReporter({ harness, quiet: opts.quiet, stderr: opts.stderr });
+    return { reporter, decide: createDecider(reporter, opts.client ?? clientFor(opts.mock, opts.timeoutMs)) };
+}
+export const list = (raw) => (raw ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+export async function readAll(stdin) {
+    let text = "";
+    for await (const chunk of stdin)
+        text += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    return text;
+}
+/** Resolve with the work, or with `fallback` once `ms` pass. The work keeps running but nobody waits. */
+export async function withDeadline(work, ms, fallback) {
+    let timer;
+    const late = new Promise((resolve) => { timer = setTimeout(() => resolve(fallback()), ms); });
+    try {
+        return await Promise.race([work, late]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class UsageError extends Error {
+}

package/dist/cli/hook.d.ts

@@ -0,0 +1,3 @@
+import { type Io } from "./common.ts";
+export declare const HOOK_HELP: string;
+export declare function hook(argv: string[], io: Io): Promise<number>;

package/dist/cli/hook.js

@@ -0,0 +1,85 @@
+/**
+ * jev hook: run as a Claude Code or Codex hook. Reads the hook payload on stdin, writes the
+ * harness's response on stdout. Fails open: a Jev error, a timeout, or a bad payload allows the
+ * action. Never exits 2, which both harnesses read as "block".
+ */
+import { parseArgs } from "node:util";
+import { ALL_GUARDS, LEVEL6_GUARDS, runHarnessHook, HOOK_LINES } from "../hooks/index.js";
+import { deciderFor, list, readAll, withDeadline } from "./common.js";
+export const HOOK_HELP = `Usage: jev hook --harness claude|codex --event <HookEvent> [options]
+
+Reads the hook payload on stdin and answers on stdout. Exit 0 always, except 1 for bad options.
+
+Options:
+  --harness <name>     claude or codex
+  --event <name>       PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact
+  --guards <list>      bash,write,result,mcp (default: bash,write,result)
+  --ask                the bash and mcp gates ask you when Jev is unsure or leans destructive (Claude Code)
+  --allow-read-only    the bash and mcp gates approve what Jev is sure only reads (Claude Code)
+  --compact            run the Level 7 advisor on UserPromptSubmit and Stop
+  --lines <n,n,n>      notice, recommend, request lines in context tokens (default ${HOOK_LINES.notice},${HOOK_LINES.recommend},${HOOK_LINES.request})
+  --window <tokens>    the model's context window, for percentages
+  --timeout-ms <ms>    give up and allow after this long (default 8000)
+  --mock               use the offline mock instead of a Jev key
+`;
+export async function hook(argv, io) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: argv, strict: true,
+            options: {
+                harness: { type: "string" }, event: { type: "string" }, guards: { type: "string" }, compact: { type: "boolean" },
+                ask: { type: "boolean" }, "allow-read-only": { type: "boolean" },
+                lines: { type: "string" }, window: { type: "string" }, "timeout-ms": { type: "string" }, mock: { type: "boolean" }, help: { type: "boolean", short: "h" },
+            },
+        }));
+    }
+    catch (err) {
+        io.stderr.write(`jev hook: ${err.message}\n\n${HOOK_HELP}`);
+        return 1;
+    }
+    if (values.help) {
+        io.stdout.write(HOOK_HELP);
+        return 0;
+    }
+    const harness = values.harness;
+    if (harness !== "claude" && harness !== "codex") {
+        io.stderr.write(`jev hook: --harness must be claude or codex\n`);
+        return 1;
+    }
+    if (!values.event) {
+        io.stderr.write(`jev hook: --event is required\n`);
+        return 1;
+    }
+    const guards = values.guards ? list(values.guards) : LEVEL6_GUARDS;
+    const unknown = guards.filter((g) => !ALL_GUARDS.includes(g));
+    if (unknown.length) {
+        io.stderr.write(`jev hook: unknown guard ${unknown.join(", ")}; known: ${ALL_GUARDS.join(", ")}\n`);
+        return 1;
+    }
+    let lines = HOOK_LINES;
+    if (values.lines) {
+        const [notice, recommend, request] = list(values.lines).map(Number);
+        if (![notice, recommend, request].every((n) => Number.isFinite(n) && n > 0) || !(notice < recommend && recommend < request)) {
+            io.stderr.write(`jev hook: --lines needs three increasing token counts, for example 50000,100000,150000\n`);
+            return 1;
+        }
+        lines = { notice, recommend, request };
+    }
+    const window = values.window ? Number(values.window) : null;
+    const timeoutMs = values["timeout-ms"] ? Number(values["timeout-ms"]) : 8000;
+    const { reporter, decide } = deciderFor(harness, { mock: values.mock, stderr: io.stderr, timeoutMs, client: io.client });
+    let payload;
+    try {
+        payload = JSON.parse(await readAll(io.stdin));
+    }
+    catch (err) {
+        reporter.report("error", { hook: values.event, message: `unreadable hook payload: ${err?.message ?? err}` });
+        return 0;
+    }
+    const response = await withDeadline(runHarnessHook(values.event, payload, { harness, guards, ladder: { ask: values.ask, allowReadOnly: values["allow-read-only"] }, compact: values.compact, lines, window, decide, report: (k, p) => reporter.report(k, p) })
+        .catch((err) => { reporter.report("error", { hook: values.event, message: err?.message ?? String(err) }); return null; }), timeoutMs, () => { reporter.report("error", { hook: values.event, message: `timed out after ${timeoutMs} ms; allowed` }); return null; });
+    if (response)
+        io.stdout.write(JSON.stringify(response));
+    return 0;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * The `jev` bin. Everything lives in main.ts, so tests can call it without a process.
+ */
+import { main } from "./main.js";
+import { processIo } from "./common.js";
+// A reader that stops early (`jev files ... | head -1`) closes the pipe: that ends the output, not an error.
+process.stdout.on("error", (err) => {
+    if (err.code === "EPIPE")
+        process.exit(process.exitCode ?? 0);
+    throw err;
+});
+const argv = process.argv.slice(2);
+main(argv, processIo()).then((code) => {
+    // A hook must exit as soon as it has answered: a Jev call abandoned at the deadline would
+    // otherwise hold the process, and the harness waits for it. Exit once stdout has flushed.
+    if (argv[0] === "hook")
+        process.stdout.write("", () => process.exit(code));
+    else
+        process.exitCode = code;
+});

package/dist/cli/main.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `jev` command: one bin, one subcommand per delivery surface.
+ */
+import { HOOK_HELP } from "./hook.ts";
+import type { Io } from "./common.ts";
+export { HOOK_HELP };
+export declare function helpText(): string;
+export declare function main(argv: string[], io: Io): Promise<number>;

package/dist/cli/main.js

@@ -0,0 +1,41 @@
+/**
+ * The `jev` command: one bin, one subcommand per delivery surface.
+ */
+import { hook, HOOK_HELP } from "./hook.js";
+import { setup } from "./setup.js";
+import { mcp } from "./mcp.js";
+import { ask, files, gate, guard } from "./ask.js";
+const SUBCOMMANDS = [
+    ["ask", "Ask a question block about a state, files, or a command's output; JSON on stdout", ask],
+    ["files", "Ask the same question block about each file, in parallel", files],
+    ["gate", "One yes or no question; exit 0 yes, 1 no, 2 usage, 3 Jev error", gate],
+    ["guard", "Check a shell command or a file write with the Level 6 gates; exit 0 allow, 1 block", guard],
+    ["setup", "Write or merge the Jev hooks and MCP server into a project's Claude Code or Codex config", setup],
+    ["hook", "Run as a Claude Code or Codex hook: guards and the compaction advisor", hook],
+    ["mcp", "Serve the Jev tools over stdio MCP", mcp],
+];
+export { HOOK_HELP };
+export function helpText() {
+    const width = Math.max(...SUBCOMMANDS.map(([n]) => n.length));
+    return [
+        "Usage: jev <command> [options]",
+        "",
+        "Commands:",
+        ...SUBCOMMANDS.map(([n, s]) => `  ${n.padEnd(width)}  ${s}`),
+        "",
+        "Run `jev <command> --help` for a command's options.",
+    ].join("\n");
+}
+export async function main(argv, io) {
+    const [command, ...rest] = argv;
+    if (!command || command === "--help" || command === "-h" || command === "help") {
+        io.stdout.write(helpText() + "\n");
+        return 0;
+    }
+    const entry = SUBCOMMANDS.find(([n]) => n === command);
+    if (!entry) {
+        io.stderr.write(`jev: unknown command "${command}".\n\n${helpText()}\n`);
+        return 2;
+    }
+    return entry[2](rest, io);
+}

package/dist/cli/mcp.d.ts

@@ -0,0 +1,3 @@
+import { type Io } from "./common.ts";
+export declare const MCP_HELP = "Usage: jev mcp [--level 7..10 | --tools a,b] [--cwd dir] [--mock]\n\nServes the Jev tools over stdio MCP. Paths resolve against --cwd (default: where it was started).\nWith neither --level nor --tools it serves all of them.\n";
+export declare function mcp(argv: string[], io: Io): Promise<number>;

package/dist/cli/mcp.js

@@ -0,0 +1,47 @@
+/**
+ * jev mcp: serve the Jev tools over stdio MCP, by level or by tool name.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { serve } from "../mcp/server.js";
+import { selectTools } from "../tools/sets.js";
+import { deciderFor, list } from "./common.js";
+export const MCP_HELP = `Usage: jev mcp [--level 7..10 | --tools a,b] [--cwd dir] [--mock]
+
+Serves the Jev tools over stdio MCP. Paths resolve against --cwd (default: where it was started).
+With neither --level nor --tools it serves all of them.
+`;
+const version = () => {
+    try {
+        return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+    }
+    catch {
+        return "0.0.0";
+    }
+};
+export async function mcp(argv, io) {
+    let values;
+    try {
+        ({ values } = parseArgs({ args: argv, strict: true, options: { level: { type: "string" }, tools: { type: "string" }, cwd: { type: "string" }, mock: { type: "boolean" }, help: { type: "boolean", short: "h" } } }));
+    }
+    catch (err) {
+        io.stderr.write(`jev mcp: ${err.message}\n\n${MCP_HELP}`);
+        return 2;
+    }
+    if (values.help) {
+        io.stdout.write(MCP_HELP);
+        return 0;
+    }
+    let tools;
+    try {
+        tools = selectTools({ level: values.level !== undefined ? Number(values.level) : undefined, names: values.tools ? list(values.tools) : undefined });
+    }
+    catch (err) {
+        io.stderr.write(`jev mcp: ${err.message}\n`);
+        return 2;
+    }
+    const { reporter, decide } = deciderFor("mcp", { mock: values.mock, stderr: io.stderr, client: io.client });
+    await serve({ tools, cwd: resolve(values.cwd ?? process.cwd()), decide, report: (k, p) => reporter.report(k, p), version: version() });
+    return 0;
+}

package/dist/cli/setup.d.ts

@@ -0,0 +1,3 @@
+import { type Io } from "./common.ts";
+export declare const SETUP_HELP = "Usage: jev setup --harness claude|codex [options]\n\nWrites or merges the Jev entries into the project's agent config, leaving everything else alone.\nClaude Code: .mcp.json and .claude/settings.json. Codex: a marked block in .codex/config.toml.\nEach run sets the whole selection: running it again replaces only what it set up before.\n\nOptions:\n  --harness <name>    claude or codex\n  --guards <list>     bash,write,result: the Level 6 hooks; mcp: the MCP gate on other servers' tools (Claude Code)\n  --ask               the bash and mcp gates ask you when Jev is unsure or leans destructive (Claude Code)\n  --allow-read-only   the bash and mcp gates approve what Jev is sure only reads (Claude Code)\n  --tools <list>      Jev tools to serve over MCP, for example ask_jev,ask_jev_files\n  --compact           the Level 7 advisor hooks\n  --level <n>         a lab level: 6 guards, 7 advisor, 8 to 10 their tools\n  --out <dir>         the project directory (default: the current one)\n  --command <cmd>     how to run jev in the hooks and the MCP entry (default: node and this package's bin)\n  --hook-args <args>  extra jev hook flags, for example \"--lines 60000,120000,180000\"\n  --dry-run           print what would change, write nothing\n";
+export declare function setup(argv: string[], io: Io): Promise<number>;

package/dist/cli/setup.js

@@ -0,0 +1,84 @@
+/**
+ * jev setup: wire the Jev hooks and MCP server into a project's Claude Code or Codex config.
+ */
+import { parseArgs } from "node:util";
+import { relative } from "node:path";
+import { toPosix } from "../files/read-state.js";
+import { apply, describeSelection, plan, SetupError } from "../setup/index.js";
+import { list } from "./common.js";
+export const SETUP_HELP = `Usage: jev setup --harness claude|codex [options]
+
+Writes or merges the Jev entries into the project's agent config, leaving everything else alone.
+Claude Code: .mcp.json and .claude/settings.json. Codex: a marked block in .codex/config.toml.
+Each run sets the whole selection: running it again replaces only what it set up before.
+
+Options:
+  --harness <name>    claude or codex
+  --guards <list>     bash,write,result: the Level 6 hooks; mcp: the MCP gate on other servers' tools (Claude Code)
+  --ask               the bash and mcp gates ask you when Jev is unsure or leans destructive (Claude Code)
+  --allow-read-only   the bash and mcp gates approve what Jev is sure only reads (Claude Code)
+  --tools <list>      Jev tools to serve over MCP, for example ask_jev,ask_jev_files
+  --compact           the Level 7 advisor hooks
+  --level <n>         a lab level: 6 guards, 7 advisor, 8 to 10 their tools
+  --out <dir>         the project directory (default: the current one)
+  --command <cmd>     how to run jev in the hooks and the MCP entry (default: node and this package's bin)
+  --hook-args <args>  extra jev hook flags, for example "--lines 60000,120000,180000"
+  --dry-run           print what would change, write nothing
+`;
+export async function setup(argv, io) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: argv, strict: true,
+            options: {
+                harness: { type: "string" }, guards: { type: "string" }, tools: { type: "string" }, compact: { type: "boolean" },
+                ask: { type: "boolean" }, "allow-read-only": { type: "boolean" },
+                level: { type: "string" }, out: { type: "string" }, command: { type: "string" }, "hook-args": { type: "string" },
+                "dry-run": { type: "boolean" }, help: { type: "boolean", short: "h" },
+            },
+        }));
+    }
+    catch (err) {
+        io.stderr.write(`jev setup: ${err.message}\n\n${SETUP_HELP}`);
+        return 2;
+    }
+    if (values.help) {
+        io.stdout.write(SETUP_HELP);
+        return 0;
+    }
+    const harness = values.harness;
+    if (harness !== "claude" && harness !== "codex") {
+        io.stderr.write("jev setup: --harness must be claude or codex\n");
+        return 2;
+    }
+    const dir = values.out ?? process.cwd();
+    try {
+        const selection = {
+            guards: values.guards ? list(values.guards) : undefined,
+            tools: values.tools ? list(values.tools) : undefined,
+            compact: values.compact,
+            ask: values.ask,
+            allowReadOnly: values["allow-read-only"],
+            level: values.level !== undefined ? Number(values.level) : undefined,
+        };
+        const changes = plan({
+            harness, dir, ...selection,
+            command: values.command ? values.command.split(/\s+/).filter(Boolean) : undefined,
+            hookArgs: values["hook-args"] ? values["hook-args"].split(/\s+/).filter(Boolean) : undefined,
+        });
+        const changed = changes.filter((c) => c.changed);
+        if (values["dry-run"]) {
+            for (const c of changes)
+                io.stdout.write(`--- ${toPosix(relative(dir, c.path) || c.path)}${c.changed ? "" : " (unchanged)"}\n${c.after}`);
+            return 0;
+        }
+        apply(changes);
+        io.stdout.write(changed.length ? `jev setup: wrote ${changed.map((c) => toPosix(relative(dir, c.path))).join(", ")}\n` : "jev setup: no changes\n");
+        io.stdout.write(`jev setup: on: ${describeSelection(selection)}. Running it again replaces this selection.\n`);
+        return 0;
+    }
+    catch (err) {
+        io.stderr.write(`jev setup: ${err instanceof SetupError ? err.message : err?.message ?? err}\n`);
+        return 1;
+    }
+}

package/dist/compact/compact-on-demand.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Level 7, option B: should_i_compact on demand.
+ * The same four questions and the same tiers, but the agent asks. The tool returns a typed verdict it can act on instead of a nudge it might miss.
+ */
+import type { CompactAction, CompactAnswers, CompactDecision, Lines, Usage } from "./should-compact.ts";
+export interface CompactVerdict {
+    should_compact: boolean;
+    tier: CompactDecision["tier"];
+    reason: string;
+    context_tokens: number | null;
+    context_percent: number | null;
+    lines: Lines;
+    signals: {
+        switched_gears: number;
+        at_boundary: number;
+        needs_history: number;
+        mid_operation: number;
+    };
+    next_step: string;
+}
+/** The tool result the agent reads. Booleans and numbers first, prose last. */
+export declare function compactVerdict(d: CompactDecision, a: CompactAnswers, usage: Usage | null, lines: Lines, action?: CompactAction): CompactVerdict;

package/dist/compact/compact-on-demand.js

@@ -0,0 +1,29 @@
+/** The tool result the agent reads. Booleans and numbers first, prose last. */
+export function compactVerdict(d, a, usage, lines, action = "compact_now") {
+    const should = d.tier === "recommend" || d.tier === "request";
+    return {
+        should_compact: should,
+        tier: d.tier,
+        reason: d.reason,
+        context_tokens: usage ? usage.tokens : null,
+        context_percent: usage && usage.pct !== null ? Number(usage.pct.toFixed(1)) : null,
+        lines,
+        signals: {
+            switched_gears: a.switched_gears.noul,
+            at_boundary: a.at_boundary.noul,
+            needs_history: a.needs_history.score,
+            mid_operation: a.mid_operation.noul,
+        },
+        next_step: action === "ask_user"
+            ? should
+                ? "Ask the user to run /compact with a one line note of what to keep, then continue the current request."
+                : d.tier === "notice"
+                    ? "Optional. Continue, or suggest /compact to the user at a clean point."
+                    : "Continue. Nothing to do."
+            : should
+                ? "Call compact_now with a short note to yourself, then continue the current request."
+                : d.tier === "notice"
+                    ? "Optional. Continue, or call compact_now if you are at a clean point."
+                    : "Continue. Nothing to do.",
+    };
+}