@paxnax/berliner 0.0.0-stage → 0.2.0

package/dist/commands/hook.js

@@ -0,0 +1,228 @@
+import { spawn } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { findRecord, readClaudeCode, readCodex, readOpenCode, SAFE_ID } from "../agents/index.js";
+import { CliError, request } from "../client.js";
+import { readConfig, stateDir } from "../config.js";
+import { gitFacts } from "../git.js";
+import { estimateCost, loadPrices } from "../prices.js";
+const REMINDER = "This session reports to Berliner: run `berliner report` with the task and PRs before your final message.";
+const TOOLS = ["claude-code", "codex", "opencode"];
+const REPORT_EVENTS = ["Stop", "PreCompact", "SessionEnd"];
+const OPENCODE_EVENTS = ["idle", "compacting"];
+const MAX_PAYLOAD = 1024 * 1024;
+const LOCK_MS = 60_000;
+const DEADLINE_MS = 15_000;
+export function inTool(env) {
+    if (env.CLAUDE_CODE_SESSION_ID)
+        return { tool: "claude-code", sessionId: env.CLAUDE_CODE_SESSION_ID };
+    if (env.CODEX_THREAD_ID)
+        return { tool: "codex", sessionId: env.CODEX_THREAD_ID };
+    if (env.OPENCODE_SESSION_ID)
+        return { tool: "opencode", sessionId: env.OPENCODE_SESSION_ID };
+    return null;
+}
+// The session's facts from the tool's own record, with a cost estimated wherever the tool stores none; the cost stays null when
+// no prices load. Claude Code and Codex name the record in the hook payload, and OpenCode's plugin sends the session itself;
+// otherwise it is looked up. Null without a record.
+export async function sessionFacts(tool, sessionId, env, payload = {}) {
+    let facts;
+    if (tool === "opencode" && payload.session)
+        facts = readOpenCode(payload.session);
+    else {
+        const named = typeof payload.transcript_path === "string" && payload.transcript_path ? payload.transcript_path : null;
+        const file = named ?? (await findRecord(tool, sessionId, env));
+        if (!file)
+            return null;
+        if (tool === "claude-code")
+            facts = await readClaudeCode(file);
+        else if (tool === "codex")
+            facts = await readCodex(file);
+        else
+            facts = readOpenCode(JSON.parse(await readFile(file, "utf8")));
+    }
+    // Codex's payload names the model the session runs on now.
+    if (tool === "codex" && typeof payload.model === "string" && payload.model)
+        facts = { ...facts, model: payload.model };
+    if (facts.costUsd !== null)
+        return facts;
+    const prices = await loadPrices(env);
+    return prices ? { ...facts, costUsd: estimateCost(facts.tokensByModel, prices).costUsd } : facts;
+}
+// The first prompt's first line cut to 80 characters, else the branch. The repository is the last resort: a new session needs a title.
+export function derivedTitle(firstPrompt, git) {
+    const line = firstPrompt?.split("\n")[0].trim();
+    return (line && Array.from(line).slice(0, 80).join("")) || git.branch || git.repository;
+}
+// `berliner hook <tool>` runs inside the agent tool: it never prints (bar the reminder), never fails and never makes the agent
+// wait. The work happens in a detached child (`--run`), and every error goes to hook.log.
+export async function hook(env, positionals, values) {
+    const tool = positionals[0];
+    try {
+        if (!TOOLS.includes(tool))
+            throw new Error(`unknown tool "${tool}"`);
+        if (values.run)
+            await child(tool, values.run, env);
+        else
+            await start(tool, env);
+    }
+    catch (err) {
+        log(env, `${tool}: ${err.message}`);
+    }
+}
+async function start(tool, env) {
+    const text = await readStdin();
+    const p = JSON.parse(text);
+    let id;
+    if (tool === "opencode") {
+        if (!OPENCODE_EVENTS.includes(p.event))
+            return;
+        id = p.session?.id;
+    }
+    else {
+        // A compaction or /clear may have lost the task and PRs the agent hasn't reported yet.
+        if (p.hook_event_name === "SessionStart" && (p.source === "compact" || p.source === "clear"))
+            return console.log(REMINDER);
+        if (!REPORT_EVENTS.includes(p.hook_event_name))
+            return;
+        id = p.session_id;
+    }
+    // The id names the payload file.
+    if (typeof id !== "string" || !SAFE_ID.test(id))
+        throw new Error("the payload has no usable session id");
+    const dir = join(stateDir(env), "hook");
+    // Payloads name the user's projects and sessions: only the user may read them.
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = join(dir, `${id}.json`);
+    // Renamed into place, so a running child never reads half of this payload.
+    // shortcut: payload files are kept, one small file per session, as a child can't tell whether a newer one is on its way.
+    writeFileSync(`${file}.${process.pid}`, text);
+    renameSync(`${file}.${process.pid}`, file);
+    // No stdio and its own process group: the tool waits on this process only, and the child outlives it.
+    spawn(process.execPath, [process.argv[1], "hook", tool, "--run", file], { detached: true, stdio: "ignore" })
+        .on("error", (err) => log(env, `${tool} ${id}: ${err.message}`))
+        .unref();
+}
+async function readStdin() {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        size += chunk.length;
+        if (size > MAX_PAYLOAD)
+            throw new Error("the payload is over 1 MB");
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+// One child per session at a time. Each child leaves a note, then tries the lock: one that can't get it exits, and the holder
+// sends the latest payload again for as long as notes keep coming, so the latest totals win.
+async function child(tool, file, env) {
+    const base = file.replace(/\.json$/, "");
+    const lock = `${base}.lock`;
+    const again = `${base}.again`;
+    const where = `${tool} ${basename(base)}`;
+    // Left before trying the lock, so a holder that checks after this child gave up still finds it.
+    writeFileSync(again, "");
+    if (!takeLock(lock))
+        return;
+    // The CLI's usual 15-second deadline, for the whole child, a slow price download included.
+    // shortcut: a note still waiting when the deadline hits is sent by the next event's child.
+    const timer = setTimeout(() => {
+        log(env, `${where}: gave up after 15 s`);
+        rmSync(lock, { force: true });
+        process.exit(0);
+    }, DEADLINE_MS).unref();
+    try {
+        do {
+            while (existsSync(again)) {
+                rmSync(again, { force: true });
+                await send(tool, file, env).catch((err) => log(env, `${where}: ${err.message}`));
+            }
+            rmSync(lock, { force: true });
+            // A note left after the last check but before the unlock: take the lock back for it, unless a newer child already has.
+        } while (existsSync(again) && takeLock(lock));
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// A lock younger than a minute belongs to a running child. An older one was left by a child that died: it is removed and
+// created again with wx, so of two children that find it stale only one gets it, and the other exits as for a held lock.
+function takeLock(lock) {
+    if (createLock(lock))
+        return true;
+    if (Date.now() - (statSync(lock, { throwIfNoEntry: false })?.mtimeMs ?? 0) < LOCK_MS)
+        return false;
+    // shortcut: a child that found the lock stale just before another one replaced it removes the new lock; this needs a child to have died.
+    rmSync(lock, { force: true });
+    return createLock(lock);
+}
+function createLock(lock) {
+    try {
+        writeFileSync(lock, String(process.pid), { flag: "wx" });
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return false;
+        throw err;
+    }
+}
+// Only the fields the machine knows. The task, PRs, coverage, evidence, project, an existing title and the plan are the agent's.
+async function send(tool, file, env) {
+    const payload = JSON.parse(await readFile(file, "utf8"));
+    const sessionId = String(tool === "opencode" ? payload.session?.id : payload.session_id);
+    const cwd = tool === "opencode" ? payload.session?.directory : payload.cwd;
+    if (typeof cwd !== "string")
+        throw new Error("the payload has no cwd");
+    const facts = await sessionFacts(tool, sessionId, env, payload);
+    if (!facts)
+        throw new Error("no record of this session");
+    const git = await gitFacts(cwd, facts.startedAt);
+    // The repository is required, and it is how Berliner groups work.
+    if (!git.repository)
+        throw new Error(`no GitHub repository at ${cwd}, not reported`);
+    const body = {
+        // Unknown without prices: left out, so a cost already saved stays.
+        cost_usd: facts.costUsd ?? undefined,
+        model: facts.model ?? undefined,
+        commits: git.commits ?? undefined,
+        started_at: facts.startedAt ?? undefined,
+        ended_at: facts.endedAt ?? undefined,
+        repository: git.repository,
+    };
+    const cfg = readConfig(env);
+    const path = `/v1/sessions/${encodeURIComponent(sessionId)}`;
+    try {
+        await request(cfg, "PATCH", path, body);
+    }
+    catch (err) {
+        if (!(err instanceof CliError && err.status === 404))
+            throw err;
+        // shortcut: an agent report landing between the 404 and this PUT gets the derived title; a create-only call would close that.
+        // The plan is BERLINER_PLAN from the tool's environment, else the server's pick from the user's subscriptions. A new
+        // session needs a cost: 0 until prices load.
+        const create = (plan) => request(cfg, "PUT", path, { ...body, cost_usd: body.cost_usd ?? 0, title: derivedTitle(facts.firstPrompt, git), plan });
+        try {
+            await create(cfg.plan ?? undefined);
+        }
+        catch (err) {
+            // A BERLINER_PLAN the server rejects must not lose the session: the server picks the plan instead.
+            if (!(cfg.plan && err instanceof CliError && err.status === 422 && err.details?.fieldErrors?.plan))
+                throw err;
+            await create(undefined);
+            log(env, `${tool} ${sessionId}: BERLINER_PLAN "${cfg.plan}" is not a plan; the server picked the plan`);
+        }
+    }
+}
+// shortcut: hook.log is never rotated (one short line per skipped or failed report); rotate it if it grows large in practice.
+function log(env, line) {
+    try {
+        mkdirSync(stateDir(env), { recursive: true, mode: 0o700 });
+        appendFileSync(join(stateDir(env), "hook.log"), `${new Date().toISOString()} ${line.replace(/\s*\n\s*/g, " ")}\n`);
+    }
+    catch {
+        // Nowhere left to record it, and the hook must stay silent.
+    }
+}

package/dist/commands/query.js

@@ -0,0 +1,25 @@
+import { CliError } from "../client.js";
+// Filters shared by `sessions` and `summary`, mapped to the API's query string.
+export function filterQuery(values, extra = {}) {
+    const q = new URLSearchParams();
+    const set = (k, v) => v !== undefined && q.set(k, v);
+    set("repository", values.repo);
+    set("model", values.model);
+    set("project", values.project);
+    set("ci", values.ci);
+    set("merge", values.merge);
+    if (values.since !== undefined) {
+        const m = /^(\d+)d$/.exec(values.since);
+        if (!m)
+            throw new CliError(`--since must look like 30d, got "${values.since}"`, "usage");
+        const to = new Date();
+        q.set("to", to.toISOString());
+        q.set("from", new Date(to.getTime() - Number(m[1]) * 864e5).toISOString());
+    }
+    set("from", values.from);
+    set("to", values.to);
+    q.set("tz", Intl.DateTimeFormat().resolvedOptions().timeZone);
+    for (const [k, v] of Object.entries(extra))
+        set(k, v);
+    return `?${q}`;
+}

package/dist/commands/report.js

@@ -0,0 +1,65 @@
+import { CliError } from "../client.js";
+import { print, warn } from "../output.js";
+import { uploadEvidence } from "../upload.js";
+import { fromTool, saveSession, sessionBody } from "./body.js";
+import { inTool } from "./hook.js";
+const required = ["session-id", "title", "repo", "cost", "model", "plan"];
+export async function report(cfg, values, positionals, env) {
+    // Usually an unquoted value with spaces, e.g. --title Fix the bug.
+    if (positionals.length)
+        throw new CliError(`unexpected argument "${positionals[0]}"; quote values that contain spaces`, "usage");
+    const tool = inTool(env);
+    const titled = values.title !== undefined;
+    if (tool)
+        values = await fromTool(tool, values, env, "report");
+    // BERLINER_PLAN stands in for --plan. Inside a tool, a report without a plan leaves it to the server, and one without a
+    // cost has no prices to estimate it.
+    const missing = required.filter((flag) => values[flag] === undefined && !(flag === "plan" && cfg.plan) && !(tool && (flag === "plan" || flag === "cost")));
+    if (missing.length)
+        throw new CliError(`missing required flag(s): ${missing.map((f) => `--${f}`).join(", ")}`, "usage");
+    const body = { ...sessionBody(values), plan: cfg.plan ?? values.plan };
+    const id = values["session-id"];
+    const path = `/v1/sessions/${encodeURIComponent(id)}`;
+    // Inside a tool a report without --title is usually a follow-up: the derived title is only for a new session. A report
+    // without a cost must not replace the saved one either.
+    const { json: saved, dropped } = await (tool && (!titled || body.cost_usd === undefined)
+        ? patchFirst(cfg, path, body, titled, values.plan)
+        : saveSession(cfg, "PUT", path, body, values.plan));
+    const json = dropped.length ? { ...saved, dropped } : saved;
+    const { created, session } = json;
+    const text = `Saved session ${session.id} (${created ? "created" : "updated"}). ${session.pr_count} PR(s) linked.`;
+    const json_ = values.json === true;
+    // Human mode prints the session line before uploads start; --json waits so stdout is one document.
+    if (!json_)
+        print({ data: json, text }, false);
+    if (!values.evidence?.length) {
+        if (json_)
+            print({ data: json, text }, true);
+        return;
+    }
+    const result = await uploadEvidence(cfg, id, values.evidence.map(parseEvidence));
+    if (json_)
+        print({ data: { ...json, evidence: result }, text }, true);
+    else
+        console.log(`Evidence: ${result.uploaded} uploaded, ${result.existing} already uploaded, ${result.skipped.length} skipped.`);
+    for (const s of result.skipped)
+        warn(`${s.path}: ${s.reason}`);
+}
+// The same fields, minus a derived title, for a session that exists; on a 404, the PUT that creates it, at cost 0 while the
+// cost is unknown.
+async function patchFirst(cfg, path, body, titled, guess) {
+    try {
+        const res = await saveSession(cfg, "PATCH", path, titled ? body : { ...body, title: undefined }, guess);
+        return { ...res, json: { created: false, ...res.json } };
+    }
+    catch (err) {
+        if (!(err instanceof CliError && err.status === 404))
+            throw err;
+        return saveSession(cfg, "PUT", path, { ...body, cost_usd: body.cost_usd ?? 0 }, guess);
+    }
+}
+// <path>[::<caption>]
+function parseEvidence(spec) {
+    const i = spec.indexOf("::");
+    return i < 0 ? { path: spec } : { path: spec.slice(0, i), caption: spec.slice(i + 2) || undefined };
+}

package/dist/commands/session.js

@@ -0,0 +1,33 @@
+import { CliError, request } from "../client.js";
+import { mergeLabel, print } from "../output.js";
+export async function session(cfg, values, positionals) {
+    if (positionals.length !== 1)
+        throw new CliError("usage: berliner session <session-id> [--json]", "usage");
+    const { json } = await request(cfg, "GET", `/v1/sessions/${encodeURIComponent(positionals[0])}`);
+    const s = json.session;
+    const fields = [
+        ["Session", s.id],
+        ["Title", s.title],
+        ["Repository", s.repository],
+        ["Task", [s.task_id, s.task_url].filter(Boolean).join(" ")],
+        ["Project", s.project],
+        ["Estimated cost", `$${s.cost_usd.toFixed(2)}`],
+        ["Model", s.model],
+        ["Plan", s.plan],
+        ["Started", s.started_at],
+        ["Ended", s.ended_at],
+        ["Duration (s)", s.duration_seconds],
+        ["Commits", s.commits],
+        ["Coverage", s.coverage],
+        ["CI", s.ci],
+        ["Merge", mergeLabel(s)],
+    ];
+    const lines = fields.filter(([, v]) => v !== null && v !== undefined && v !== "").map(([k, v]) => `${k}: ${v}`);
+    lines.push(`Pull requests: ${s.prs.length || "none"}`);
+    for (const p of s.prs)
+        lines.push(`  ${p.url}  merge=${p.merge_state} ci=${p.ci_state}${p.tracked ? "" : " (not tracked)"}`);
+    lines.push(`Evidence: ${s.evidence.length || "none"}`);
+    for (const e of s.evidence)
+        lines.push(`  #${e.id} ${e.kind} ${e.filename}${e.caption ? ` - ${e.caption}` : ""}${e.status === "ready" ? "" : ` (${e.status})`}`);
+    print({ data: json, text: lines.join("\n") }, values.json === true);
+}

package/dist/commands/sessions.js

@@ -0,0 +1,17 @@
+import { request } from "../client.js";
+import { mergeLabel, print } from "../output.js";
+import { filterQuery } from "./query.js";
+const usd = (n) => `$${n.toFixed(2)}`;
+export async function sessions(cfg, values) {
+    const { json } = await request(cfg, "GET", `/v1/sessions${filterQuery(values, { limit: values.limit })}`);
+    const rows = [["TASK", "TITLE", "REPO", "COST (est.)", "PRS", "CI", "MERGE"]];
+    for (const s of json.sessions)
+        rows.push([s.task_id ?? s.id, s.title, s.repository, usd(s.cost_usd), String(s.pr_count), s.ci, mergeLabel(s)]);
+    const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => r[i].length)));
+    const lines = rows.map((r) => r
+        .map((c, i) => c.padEnd(widths[i]))
+        .join("  ")
+        .trimEnd());
+    const text = json.sessions.length ? `${lines.join("\n")}\n${json.sessions.length} of ${json.total} session(s).` : "No sessions.";
+    print({ data: json, text }, values.json === true);
+}

package/dist/commands/setup.js

@@ -0,0 +1,174 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { CliError, request } from "../client.js";
+import { configPath, DEFAULT_URL, readConfig, readConfigFile, saveConfig } from "../config.js";
+import { machineName, openBrowser, startConnect, waitForApproval } from "../setup/connect.js";
+import { describeClaudeHooks, describeCodexHooks, describeOpenCodePlugin, installClaudeHooks, installCodexHooks, installOpenCodePlugin, } from "../setup/hooks.js";
+import { claudeDir, codexDir, detectTools, onPath, opencodeDir, skillTargets } from "../setup/targets.js";
+// The same command the web guide shows.
+const TEST_REPORT = 'berliner report --session-id try-1 --title "First report" --repo you/app --cost 0.10 --model test --plan pro';
+const tilde = (p) => (p.startsWith(`${homedir()}/`) ? `~${p.slice(homedir().length)}` : p);
+export async function confirm(input, output) {
+    const rl = createInterface({ input, output });
+    // Ctrl+C and Ctrl+D reject the question without ending the line; both mean no.
+    const answer = await rl.question("Continue? [Y/n] ").catch(() => {
+        output.write("\n");
+        return "n";
+    });
+    rl.close();
+    return /^(y|yes)?$/i.test(answer.trim());
+}
+// The login of the saved token, or null when there is none or the server no longer accepts it.
+async function savedLogin(url, token) {
+    if (!token)
+        return null;
+    try {
+        return (await request({ url, token }, "GET", "/v1/me")).json.github_login;
+    }
+    catch (err) {
+        if (err instanceof CliError && err.status === 401)
+            return null;
+        throw err;
+    }
+}
+export async function setup(env, values) {
+    const { url } = readConfig(env);
+    const login = await savedLogin(url, readConfigFile(env)?.token);
+    const tools = detectTools(env);
+    const targets = skillTargets(tools, env);
+    // One reporting hook per tool found, where the spec's "Hooks" table puts it.
+    const hookFiles = {
+        "claude-code": { path: join(claudeDir(env), "settings.json"), describe: describeClaudeHooks, install: installClaudeHooks },
+        codex: { path: join(codexDir(env), "hooks.json"), describe: describeCodexHooks, install: installCodexHooks },
+        opencode: { path: join(opencodeDir(env), "plugins", "berliner.js"), describe: describeOpenCodePlugin, install: installOpenCodePlugin },
+    };
+    const hooks = tools.filter((t) => t.found).map((t) => ({ ...t, ...hookFiles[t.id] }));
+    const version = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+    const install = [...(process.versions.bun ? ["bun", "add", "-g"] : ["npm", "install", "-g"]), `@paxnax/berliner@${version}`];
+    // The plan is data, built and shown before anything changes.
+    const steps = [
+        ...(login
+            ? [{ label: `Token: connected as ${login}, kept`, detail: [] }]
+            : [
+                { label: `${values["no-browser"] ? "Show a link to" : "Open"} ${url}/connect so you can approve this terminal`, detail: [] },
+                { label: `Save your token to ${tilde(configPath(env))} (readable only by you)`, detail: [] },
+            ]),
+        { label: `Install the berliner command:  ${install.join(" ")}${values["no-install"] ? " (skipped by --no-install)" : ""}`, detail: [] },
+        {
+            label: "Add the Berliner skill for:",
+            detail: tools.map((tool) => {
+                const target = targets.find((t) => t.tool === tool.id);
+                const where = target ? `${tilde(target.path)}${target.exists ? " (replaces the existing copy)" : ""}` : "not found, skipped";
+                return `${tool.name.padEnd(14)}${where}`;
+            }),
+        },
+        {
+            label: "Add the Berliner reporting hook for:",
+            detail: tools.map((tool) => {
+                const hook = hooks.find((h) => h.id === tool.id);
+                if (!hook)
+                    return `${tool.name.padEnd(14)}not found, skipped`;
+                const what = hook.describe(hook.path);
+                // Codex runs a new hook only once the user trusts it in Codex's terminal UI; setup leaves that check to Codex.
+                const approval = tool.id === "codex" && what === "adds a hook" ? ", which you trust by opening `codex` once in a terminal" : "";
+                return `${tool.name.padEnd(14)}${tilde(hook.path)} (${what}${approval})`;
+            }),
+        },
+    ];
+    const plan = steps.flatMap((s, i) => [`  ${i + 1}. ${s.label}`, ...s.detail.map((d) => `       ${d}`)]);
+    console.log(["", "Berliner setup", "", "This will:", ...plan, ""].join("\n"));
+    if (!values.yes) {
+        if (!process.stdin.isTTY)
+            throw new CliError("There is no terminal to ask on. Run setup again with --yes to continue without asking.", "usage");
+        if (!(await confirm(process.stdin, process.stdout)))
+            throw new CliError("Cancelled. Nothing was changed.", "usage");
+        console.log();
+    }
+    if (!login) {
+        const name = machineName();
+        const req = await startConnect({ url, token: null }, name);
+        console.log(`Confirm this code in your browser:  ${req.user_code}`);
+        if (values["no-browser"])
+            console.log(`Open ${req.verification_url} to approve. Waiting for approval...`);
+        else {
+            openBrowser(req.verification_url);
+            console.log(`Opened ${req.verification_url}. Waiting for approval...`);
+        }
+        const status = await waitForApproval({ url, token: null }, req.id, req.interval, req.expires_in);
+        if (status === "denied")
+            throw new CliError("The request was denied in the browser. Nothing was changed.", "http");
+        if (status === "expired")
+            throw new CliError("The request expired. Run setup again.", "http");
+        const me = await request({ url, token: req.token }, "GET", "/v1/me");
+        console.log(`✓ Approved by ${me.json.github_login}`);
+        const file = saveConfig(env, url === DEFAULT_URL ? { token: req.token } : { token: req.token, url });
+        console.log(`✓ Saved token "${name}" to ${tilde(file)}`);
+    }
+    let installFailed = false;
+    if (!values["no-install"]) {
+        const run = spawnSync(install[0], install.slice(1), { encoding: "utf8" });
+        installFailed = run.status !== 0;
+        if (!installFailed)
+            console.log(`✓ Installed berliner ${version}`);
+        else
+            console.error(`✗ Could not install the berliner command:\n${(run.error?.message ?? run.stdout + run.stderr).trimEnd()}`);
+    }
+    // A file that can't be written (read-only, say) is reported and skipped, so the other tools still get theirs.
+    let unwritten = false;
+    const cantWrite = (what, path, err) => {
+        unwritten = true;
+        console.error(`✗ ${what}: ${tilde(path)} can't be written (${err.message.split(",")[0]})`);
+    };
+    const skill = readFileSync(new URL("../../skill/SKILL.md", import.meta.url), "utf8");
+    for (const t of targets) {
+        const what = `${tools.find((tool) => tool.id === t.tool).name} skill`;
+        try {
+            mkdirSync(dirname(t.path), { recursive: true });
+            writeFileSync(t.path, skill);
+            console.log(`✓ ${what}: ${tilde(t.path)}`);
+        }
+        catch (err) {
+            cantWrite(what, t.path, err);
+        }
+    }
+    let codexAdded = false;
+    for (const h of hooks) {
+        let result;
+        try {
+            result = h.install(h.path);
+        }
+        catch (err) {
+            cantWrite(`${h.name} hook`, h.path, err);
+            continue;
+        }
+        if (result === "unreadable")
+            console.error(`✗ ${h.name} hook: ${tilde(h.path)} can't be read, so it was left unchanged`);
+        else
+            console.log(`✓ ${h.name} hook: ${tilde(h.path)}${result === "present" ? " (already installed)" : ""}`);
+        codexAdded ||= h.id === "codex" && result === "added";
+    }
+    const summary = [
+        targets.length ? "Done. Your agents' sessions are now reported after each reply." : "Done. No agent tools were found, so no skill was added.",
+    ];
+    if (unwritten)
+        summary.push("Some files can't be written. Fix the ones marked ✗ above, then run setup again.");
+    if (codexAdded)
+        summary.push("Open `codex` once in a terminal and trust the Berliner hook; `codex exec` skips hooks you haven't approved. Once trusted, Codex sessions are reported automatically.");
+    // The hooks run `berliner` by name: skipped or failed installs, and a global bin directory missing from PATH, all stop them.
+    // npx and bunx put their package's node_modules/.bin first on setup's PATH, which the agent tools never see; a global
+    // install never lands in one.
+    const toolPath = env.PATH?.split(":")
+        .filter((dir) => !/(^|\/)node_modules\/\.bin\/?$/.test(dir))
+        .join(":");
+    if (hooks.length && !onPath("berliner", { PATH: toolPath }))
+        summary.push(`The hooks can't run until the berliner command is on your PATH. Install it with:  ${install.join(" ")}`);
+    else if (installFailed)
+        summary.push(`Install the berliner command yourself:  ${install.join(" ")}`);
+    if (env.BERLINER_TOKEN)
+        summary.push("BERLINER_TOKEN is set in this shell and overrides the saved token.");
+    summary.push(`Send a test report:  ${TEST_REPORT}`);
+    console.log(`\n${summary.join("\n")}`);
+}

package/dist/commands/skill.js

@@ -0,0 +1,5 @@
+import { readFileSync } from "node:fs";
+// dist/commands/skill.js -> ../../skill/SKILL.md (the package's skill/ directory).
+export function skill() {
+    process.stdout.write(readFileSync(new URL("../../skill/SKILL.md", import.meta.url), "utf8"));
+}

package/dist/commands/summary.js

@@ -0,0 +1,25 @@
+import { request } from "../client.js";
+import { print, subscriptionLabel } from "../output.js";
+import { filterQuery } from "./query.js";
+export async function summary(cfg, values) {
+    const { json } = await request(cfg, "GET", `/v1/summary${filterQuery(values)}`);
+    const s = json.summary;
+    const text = [
+        `Estimated spend: $${s.spend_usd.toFixed(2)}`,
+        `Sessions: ${s.sessions}`,
+        `PRs merged: ${s.prs_merged} of ${s.prs_opened} opened`,
+        `Cost per merged PR: ${s.cost_per_merged_pr === null ? "n/a" : `$${s.cost_per_merged_pr.toFixed(2)}`}`,
+        `Commits: ${s.commits}`,
+        ...subscriptionLines(json.subscriptions),
+    ].join("\n");
+    print({ data: json, text }, values.json === true);
+}
+// One line per subscription, then the spend no listed plan covers; nothing when the user has no subscriptions.
+function subscriptionLines(c) {
+    if (!c)
+        return [];
+    const lines = c.rows.map((r) => `${subscriptionLabel(r)}: $${r.spend_usd.toFixed(2)} used of $${r.prorated_usd.toFixed(2)} paid (${r.multiple.toFixed(1)}×), ${r.sessions} session(s)`);
+    if (c.unmatched.sessions > 0)
+        lines.push(`On no listed plan: $${c.unmatched.spend_usd.toFixed(2)}, ${c.unmatched.sessions} session(s)`);
+    return lines;
+}

package/dist/commands/update.js

@@ -0,0 +1,21 @@
+import { CliError } from "../client.js";
+import { print } from "../output.js";
+import { fromTool, saveSession, sessionBody } from "./body.js";
+import { inTool } from "./hook.js";
+export async function update(cfg, values, positionals, env) {
+    const tool = inTool(env);
+    // Inside a tool the session id is the tool's, so a positional one is ignored like --session-id.
+    if (positionals.length !== 1 && !(tool && positionals.length === 0)) {
+        throw new CliError("usage: berliner update <session-id> [flags]; quote values that contain spaces", "usage");
+    }
+    if (values.evidence?.length)
+        throw new CliError("update does not upload evidence; use report --evidence", "usage");
+    if (tool)
+        values = await fromTool(tool, { ...values, "session-id": positionals[0] ?? values["session-id"] }, env, "update");
+    const id = tool ? tool.sessionId : positionals[0];
+    // A plan is only sent when --plan is passed, so an update never changes it unasked; BERLINER_PLAN then replaces it.
+    const body = { ...sessionBody(values), plan: values.plan === undefined ? undefined : (cfg.plan ?? values.plan) };
+    const { json: saved, dropped } = await saveSession(cfg, "PATCH", `/v1/sessions/${encodeURIComponent(id)}`, body, values.plan);
+    const json = dropped.length ? { ...saved, dropped } : saved;
+    print({ data: json, text: `Updated session ${json.session.id}. ${json.session.pr_count} PR(s) linked.` }, values.json === true);
+}

package/dist/config.js

@@ -0,0 +1,33 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const DEFAULT_URL = "https://berliner.app";
+export function configPath(env) {
+    return join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "berliner", "config.json");
+}
+export const stateDir = (env) => join(env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "berliner");
+export const cacheDir = (env) => join(env.XDG_CACHE_HOME || join(homedir(), ".cache"), "berliner");
+// A missing or unreadable file is the same as no file: the environment may still hold the token.
+export function readConfigFile(env) {
+    try {
+        const parsed = JSON.parse(readFileSync(configPath(env), "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const { token, url } = parsed;
+        return { token: typeof token === "string" ? token : undefined, url: typeof url === "string" ? url : undefined };
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConfig(env, value) {
+    const file = configPath(env);
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(file, 0o600); // the mode above only applies when the file is created
+    return file;
+}
+export function readConfig(env) {
+    const file = readConfigFile(env);
+    return { url: env.BERLINER_URL || file?.url || DEFAULT_URL, token: env.BERLINER_TOKEN || file?.token || null, plan: env.BERLINER_PLAN || null };
+}