@paxnax/berliner 0.7.0 → 0.8.0

package/README.md

@@ -21,7 +21,7 @@ With Bun, run `bunx --bun @paxnax/berliner@latest setup`. To install only the co
    npx @paxnax/berliner@latest setup
    ```
 
-   It shows what it will do and asks once, then opens your browser so you can approve the connection. After you approve, it saves the token, installs the CLI globally, and installs the agent skill and a reporting hook for each of Claude Code, Codex and OpenCode that it finds. `--yes` skips the question, `--no-install` skips the global install, and `--no-browser` only prints the URL (over SSH, for example). Run `berliner upgrade` to update the CLI, the skill and any Berliner hook an older setup installed to the latest release: it shows its plan and asks first, and a second question (or `--no-skill`) keeps your skill as it is.
+   It shows what it will do and asks once, then opens your browser so you can approve the connection. After you approve, it saves the token, installs the CLI globally, and installs the agent skill and a reporting hook for each of Claude Code, Codex and OpenCode that it finds. `--yes` skips the question, `--no-install` skips the global install, and `--no-browser` only prints the URL (over SSH, for example). Run `berliner upgrade` to update the CLI, the skill and any Berliner hook an older setup installed to the latest release: it shows its plan and asks first, and a second question (or `--no-skill`) keeps your skill as it is. Once a day, the first `berliner` command or agent session start checks for a newer release and says so.
 
 3. From then on, the hooks report each session's cost, model, repository, commits and start and end times after every reply. They also fill in a ticket from a Linear or Jira URL in your prompts while the session has none, and refresh up to 5 open pull requests the Berliner GitHub App doesn't track with your `gh` (skipped when `gh` is missing or signed out). When a session starts, the hook reminds your agent to name the session and report its ticket. Your agent adds the title, ticket, pull requests, coverage and evidence with `berliner report` and `berliner update`, as the skill tells it to. Codex runs a new hook only once you trust it: open `codex` once in a terminal and trust the Berliner hook.
 4. On **Settings**, list the subscriptions you pay for. Overview then compares each one with the sessions that ran on it.
@@ -121,7 +121,7 @@ Other commands:
 - `berliner delete <session-id>`: delete a session, or one item with `--evidence <id>`. Asks to confirm unless `--yes`.
 - `berliner evidence public <id>`: let anyone with the link view one file, and print its public URL and Markdown line. `berliner evidence private <id>` makes it private again. `berliner session` shows the ids, and the URL of each public file.
 - `berliner skill`: print the agent skill (`SKILL.md`) to install in your agent.
-- `berliner upgrade [--yes] [--no-skill]`: install the latest CLI and skill. It shows its plan (the versions, the exact install command, each skill file and each Berliner hook it updates) and asks before changing anything; a second question, or `--no-skill`, leaves your skill as it is. It brings a Berliner hook an older setup installed up to date, but never adds one; your token and config are never touched.
+- `berliner upgrade [--yes] [--no-skill] [--no-hooks]`: install the latest CLI and skill. It shows its plan (the versions, the exact install command, each skill file and each Berliner hook it updates) and asks before changing anything; a second question, or `--no-skill`, leaves your skill as it is, and `--no-hooks` leaves your hooks as they are. It brings a Berliner hook an older setup installed up to date, but never adds one; your token and config are never touched. When it updated a skill or hook, its last line names the tools to start a new session in so they load it.
 - `berliner hook <tool>`: run by the hooks setup installs, with the tool's payload on stdin. It never fails and never makes the agent wait, and prints only the reminder when a session starts; errors go to `${XDG_STATE_HOME:-~/.local/state}/berliner/hook.log`.
 
 `report` and `update` exit 0 even when something fails, printing a warning that starts with `berliner:` to stderr, so reporting never breaks an agent's pipeline. Pass `--strict` to make them exit 1 on failure, including a file that could not be uploaded or made public; the session is still saved. The other commands exit 1 on failure.

package/dist/args.js

@@ -28,6 +28,7 @@ const config = {
         "no-install": { type: "boolean" },
         "no-browser": { type: "boolean" },
         "no-skill": { type: "boolean" },
+        "no-hooks": { type: "boolean" },
         none: { type: "boolean" },
         all: { type: "boolean" },
         run: { type: "string" },

package/dist/commands/hook.js

@@ -13,6 +13,7 @@ import { estimateCost, loadPrices } from "../prices.js";
 import { noteRefusal, resolveTeam, teamWarning } from "../team.js";
 import { checkTests } from "../tests/check.js";
 import { nudge } from "../tests/nudge.js";
+import { upgradeNotice } from "../version.js";
 // Same text in the OpenCode plugin (cli/opencode/berliner.js).
 const REMINDER = 'This session reports to Berliner. Once you know the task, name it: berliner update --title "<short title>". When a Linear or Jira ticket comes up, report it: berliner update --task <ID> --task-url <URL>. Before your final message, run berliner report with the PRs.';
 const TOOLS = ["claude-code", "codex", "opencode"];
@@ -103,9 +104,11 @@ async function start(tool, env) {
     }
     else {
         // In the agent's context from the start, whether or not the skill triggers; after a compaction or /clear it may have lost
-        // the task and PRs it hasn't reported yet.
-        if (p.hook_event_name === "SessionStart" && SESSION_STARTS.includes(p.source))
-            return console.log(REMINDER);
+        // the task and PRs it hasn't reported yet. The day's upgrade check goes with it, so the agent can tell the user.
+        if (p.hook_event_name === "SessionStart" && SESSION_STARTS.includes(p.source)) {
+            const notice = await upgradeNotice(env);
+            return console.log(notice ? `${REMINDER}\n${notice}` : REMINDER);
+        }
         if (!REPORT_EVENTS.includes(p.hook_event_name))
             return;
         id = p.session_id;

package/dist/commands/upgrade.js

@@ -6,24 +6,9 @@ import { gunzipSync } from "node:zlib";
 import { CliError } from "../client.js";
 import { hookPath, updatedHooks } from "../setup/hooks.js";
 import { detectTools, skillTargets } from "../setup/targets.js";
+import { currentVersion, latestVersion, newer, registryOf } from "../version.js";
 import { askNudge } from "./nudge.js";
 import { confirm, installCommand, showPlan, tilde } from "./setup.js";
-const registryOf = (env) => (env.npm_config_registry || "https://registry.npmjs.org").replace(/\/+$/, "");
-async function latestVersion(env) {
-    const registry = registryOf(env);
-    try {
-        const res = await fetch(`${registry}/@paxnax/berliner/latest`);
-        if (!res.ok)
-            throw new Error(`HTTP ${res.status}`);
-        const { version } = (await res.json());
-        if (typeof version !== "string")
-            throw new Error("no version in the reply");
-        return version;
-    }
-    catch (err) {
-        throw new CliError(`Could not look up the latest berliner on ${registry} (${err.message}). Nothing was changed.`, "network");
-    }
-}
 // The skill and the OpenCode plugin come from the release being installed, so the plan's "already up to date" and what is
 // written match it. They are read out of the release tarball as data: running the release (npx) would load the cwd's .npmrc
 // and node_modules.
@@ -63,12 +48,6 @@ async function releaseFiles(version, bundled, env) {
         throw new CliError(`Could not read the skill and OpenCode plugin of berliner ${version} (${err.message}). Nothing was changed.`, "network");
     }
 }
-// Release versions only (x.y.z): the registry's latest tag never points at a prerelease.
-const newer = (a, b) => {
-    const [x, y] = [a, b].map((v) => v.split("-")[0].split(".").map(Number));
-    const i = x.findIndex((n, j) => n !== y[j]);
-    return i >= 0 && x[i] > y[i];
-};
 const sameAs = (path, text) => {
     try {
         return readFileSync(path, "utf8") === text;
@@ -85,7 +64,7 @@ const HOOK_CHANGE = {
 };
 // The command, the skill, and Berliner hooks already installed: the token and config are setup's, as is adding a hook.
 export async function upgrade(env, values) {
-    const current = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+    const current = currentVersion();
     const latest = await latestVersion(env);
     // A CLI ahead of the registry (a local build, a release still propagating) is never taken backwards, nor is its skill.
     const installing = newer(latest, current);
@@ -94,11 +73,12 @@ export async function upgrade(env, values) {
     const tools = detectTools(env);
     const targets = values["no-skill"] ? [] : skillTargets(tools, env);
     // The plugin too, so --no-skill still brings it up to date.
-    const release = targets.length || tools.some((t) => t.id === "opencode" && t.found) ? await releaseFiles(target, !installing, env) : null;
+    const plugin = !values["no-hooks"] && tools.some((t) => t.id === "opencode" && t.found);
+    const release = targets.length || plugin ? await releaseFiles(target, !installing, env) : null;
     const skill = release?.skill ?? "";
     let stale = targets.filter((t) => !sameAs(t.path, skill));
     // Computed now, for the plan.
-    const hooks = tools.flatMap((tool) => {
+    const hooks = (values["no-hooks"] ? [] : tools).flatMap((tool) => {
         const path = hookPath(tool.id, env);
         const text = updatedHooks(tool.id, path, release?.plugin);
         return text === null ? [] : [{ ...tool, path, text }];
@@ -126,13 +106,15 @@ export async function upgrade(env, values) {
                     return `${tool.name.padEnd(14)}${where}`;
                 }),
             },
-        ...(hooks.length
-            ? [{ label: "Update the Berliner hook for:", detail: hooks.map((h) => `${h.name.padEnd(14)}${tilde(h.path)} (${HOOK_CHANGE[h.id]})`) }]
-            : []),
+        ...(values["no-hooks"]
+            ? [{ label: "Leave the Berliner hooks as they are (--no-hooks)", detail: [] }]
+            : hooks.length
+                ? [{ label: "Update the Berliner hook for:", detail: hooks.map((h) => `${h.name.padEnd(14)}${tilde(h.path)} (${HOOK_CHANGE[h.id]})`) }]
+                : []),
     ]);
     if (!values.yes) {
         if (!process.stdin.isTTY)
-            throw new CliError("There is no terminal to ask on. Run upgrade again with --yes to continue without asking.", "usage");
+            throw new CliError("There is no terminal to ask on, so nothing was changed. To go ahead without asking, run upgrade again with --yes. If you are an AI agent, show the user this plan and get their approval first.", "usage");
         if (!(await confirm(process.stdin, process.stdout)))
             throw new CliError("Cancelled. Nothing was changed.", "usage");
         // Without an install, the skill is all Continue covered.
@@ -152,12 +134,15 @@ export async function upgrade(env, values) {
     }
     // A file that can't be written (read-only, say) is reported and skipped, so the other tools still get theirs.
     let unwritten = false;
+    // The tools that load what was written, for the reload line.
+    const reload = { skill: new Set(), hooks: new Set() };
     for (const t of stale) {
         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)}`);
+            reload.skill.add(t.tool);
         }
         catch (err) {
             unwritten = true;
@@ -175,11 +160,16 @@ export async function upgrade(env, values) {
             // In place, so a settings file that is a symlink stays one.
             writeFileSync(h.path, text);
             console.log(`✓ ${h.name} hook: ${tilde(h.path)}`);
+            reload.hooks.add(h.id);
         }
         catch (err) {
             unwritten = true;
             console.error(`✗ ${h.name} hook: ${tilde(h.path)} can't be written (${err.message.split(",")[0]})`);
         }
     }
-    console.log(unwritten ? "\nSome files can't be written. Fix the ones marked ✗ above, then run upgrade again." : "\nDone.");
+    // A running agent keeps the skill and hooks it started with; the command itself is new from the next call.
+    const names = tools.filter((t) => reload.skill.has(t.id) || reload.hooks.has(t.id)).map((t) => t.name);
+    const what = [reload.skill.size && "skill", reload.hooks.size && "hooks"].filter(Boolean).join(" and ");
+    const again = names.length ? ` Start a new session in ${names.join(", ").replace(/, ([^,]*)$/, " and $1")} to load the updated ${what}.` : "";
+    console.log(unwritten ? `\nSome files can't be written. Fix the ones marked ✗ above, then run upgrade again.${again}` : `\nDone.${again}`);
 }

package/dist/index.js

@@ -19,6 +19,7 @@ import { update } from "./commands/update.js";
 import { upgrade } from "./commands/upgrade.js";
 import { readConfig } from "./config.js";
 import { warn } from "./output.js";
+import { upgradeNotice } from "./version.js";
 const usage = `Usage: berliner <command> [flags]
 
 Commands:
@@ -43,7 +44,7 @@ Commands:
   delete <session-id>   [--evidence <id>] [--yes]
   evidence public <id>  let anyone with the link view one file; prints its URL and Markdown [--json]
   evidence private <id> make it viewable only by you again [--json]
-  upgrade               install the latest CLI and skill [--yes --no-skill]
+  upgrade               install the latest CLI, skill and hooks [--yes --no-skill --no-hooks]
   skill                 print the bundled SKILL.md
   hook <tool>           run by the hooks of claude-code, codex or opencode; reads the payload on stdin
 
@@ -114,3 +115,9 @@ catch (err) {
         console.error(usage);
     process.exitCode = softFail ? 0 : 1;
 }
+// The hook carries it in the session-start reminder instead, and upgrade looks for itself.
+if (args.command !== "hook" && args.command !== "upgrade") {
+    const notice = await upgradeNotice(process.env);
+    if (notice)
+        console.error(notice);
+}

package/dist/version.js

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CliError } from "./client.js";
+import { stateDir } from "./config.js";
+export const registryOf = (env) => (env.npm_config_registry || "https://registry.npmjs.org").replace(/\/+$/, "");
+export const currentVersion = () => JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export async function latestVersion(env, timeoutMs) {
+    const registry = registryOf(env);
+    try {
+        const res = await fetch(`${registry}/@paxnax/berliner/latest`, { signal: timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const { version } = (await res.json());
+        if (typeof version !== "string")
+            throw new Error("no version in the reply");
+        return version;
+    }
+    catch (err) {
+        throw new CliError(`Could not look up the latest berliner on ${registry} (${err.message}). Nothing was changed.`, "network");
+    }
+}
+// Release versions only (x.y.z): the registry's latest tag never points at a prerelease.
+export const newer = (a, b) => {
+    const [x, y] = [a, b].map((v) => v.split("-")[0].split(".").map(Number));
+    const i = x.findIndex((n, j) => n !== y[j]);
+    return i >= 0 && x[i] > y[i];
+};
+const DAY_MS = 24 * 3600_000;
+// Short, as it runs inline: the first command or session start of the day waits for it.
+const CHECK_TIMEOUT_MS = 1500;
+// Once a day per machine: the check file's mtime is when the last check started. A failed check counts too, so an
+// offline machine doesn't wait on every run. Never throws; null unless the registry has a newer release.
+export async function upgradeNotice(env) {
+    const stamp = join(stateDir(env), "version-check");
+    try {
+        if (Date.now() - statSync(stamp).mtimeMs < DAY_MS)
+            return null;
+    }
+    catch {
+        // Never checked on this machine.
+    }
+    try {
+        // Before the lookup, so runs started meanwhile don't check again.
+        mkdirSync(stateDir(env), { recursive: true, mode: 0o700 });
+        writeFileSync(stamp, "");
+        const latest = await latestVersion(env, CHECK_TIMEOUT_MS);
+        if (!newer(latest, currentVersion()))
+            return null;
+        return `New berliner CLI version ${latest} is out, run berliner upgrade to update it. If you are an AI agent, bring this to the user for approval instead of taking action yourself.`;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paxnax/berliner",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Report coding-agent sessions to Berliner",
   "keywords": [
     "claude-code",

package/skill/SKILL.md

@@ -171,6 +171,23 @@ After the evidence line, it prints one line per file: `![Login page after the fi
 
 If the `berliner` command is not found, carry on with your work and say in your final message that `npx @paxnax/berliner@latest setup` needs to run. Do not try to install it yourself.
 
+## When a newer berliner is out
+
+Once a day the CLI checks for a newer release. When there is one, the session-start reminder or a `berliner` command's output says: `New berliner CLI version X.Y.Z is out, run berliner upgrade to update it. If you are an AI agent, bring this to the user for approval instead of taking action yourself.` Never upgrade on your own:
+
+1. Run `berliner upgrade` with no flags. Without a terminal it prints its plan and stops, changing nothing.
+2. Show the user the plan, then ask them to approve each part separately: the berliner command, the skill and the hooks.
+3. If they decline the command, run nothing. Otherwise run the command that matches their answers. It never stops to ask:
+
+| Skill | Hooks | Command |
+|---|---|---|
+| yes | yes | `berliner upgrade --yes` |
+| no | yes | `berliner upgrade --yes --no-skill` |
+| yes | no | `berliner upgrade --yes --no-hooks` |
+| no | no | `berliner upgrade --yes --no-skill --no-hooks` |
+
+4. Pass on the upgrade's last line. When it names tools to start a new session in, tell the user the updated skill or hooks load only in a new session there.
+
 ## Timeouts
 
 The session is saved first, then evidence is uploaded. Allow at least 10 minutes for the command when attaching videos.