but-axi 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -24,10 +24,10 @@ It is built for agents that drive version control through a shell.
24
24
  | 1 | Token-efficient output | TOON tables such as `branches[2]{name,commits,state}:` instead of raw JSON |
25
25
  | 2 | Minimal default schemas | 3-4 fields per row. `--fields a,b` adds more |
26
26
  | 3 | Content truncation | Patches over 3000 chars and commit bodies over 800 chars are cut, with a size hint and `--full` |
27
- | 4 | Pre-computed aggregates | A `count:` line first: stacks, branches, commits, uncommitted, conflicts |
27
+ | 4 | Pre-computed aggregates | A `count:` line first: stacks, branches, commits, uncommitted, conflicts, worktrees |
28
28
  | 5 | Definitive empty states | `branches: 0 applied branches`, `hunks: 0 matching hunks`, `pushed 0 branches (already up to date)` |
29
29
  | 6 | Structured errors and exit codes | `error:`, `code:`, `help[]` on stdout. Exit 0 ok, 1 runtime error, 2 usage error. Never prompts. Idempotent commit, branch new, push |
30
- | 7 | Ambient context | `but-axi setup hooks` installs a SessionStart dashboard for Claude Code, Codex, and Cursor |
30
+ | 7 | Ambient context | `but-axi setup hooks` installs a SessionStart dashboard for Claude Code, Codex, OpenCode, Cursor, and omp |
31
31
  | 8 | Content first | Bare `but-axi` shows live workspace state, not help text |
32
32
  | 9 | Contextual disclosure | Every output ends with `help[]` command templates. `-C <path>` is carried forward and runtime values stay placeholders like `<branch>` |
33
33
  | 10 | Consistent help | `but-axi <command> --help` is short |
@@ -72,7 +72,7 @@ npm install -g but-axi
72
72
  but-axi setup hooks
73
73
  ```
74
74
 
75
- This installs a `SessionStart` hook for **Claude Code**, **Codex**, **Cursor**, and **omp** that surfaces the current GitButler workspace state at the start of each session.
75
+ This installs a `SessionStart` hook for **Claude Code**, **Codex**, **OpenCode**, **Cursor**, and **omp** that surfaces the current GitButler workspace state at the start of each session.
76
76
  **Restart your agent session after running this** so the new hook takes effect.
77
77
 
78
78
  ### Clone (development)
@@ -89,7 +89,7 @@ but-axi setup hooks
89
89
  ### Session hook
90
90
 
91
91
  ```sh
92
- but-axi setup hooks # install for every agent found (claude, codex, cursor, omp)
92
+ but-axi setup hooks # install for every agent found (claude, codex, opencode, cursor, omp)
93
93
  but-axi setup hooks --agents claude # only some agents
94
94
  but-axi setup hooks --dry-run # show what would change
95
95
  but-axi setup hooks --status # installed or not, per agent
@@ -100,13 +100,14 @@ but-axi setup hooks --uninstall # remove the managed entries
100
100
  | ----- | ----------- | ---- |
101
101
  | Claude Code | `~/.claude/settings.json` | `hooks.SessionStart` group, plain text output |
102
102
  | Codex | `~/.codex/hooks.json` | `hooks.SessionStart` group, plain text output (needs `[features] hooks = true` in `~/.codex/config.toml`) |
103
+ | OpenCode | `~/.config/opencode/plugins/but-axi.js` | Managed plugin that adds the dashboard to the session's system context (OpenCode 1 and 2) |
103
104
  | Cursor | `~/.cursor/hooks.json` | `hooks.sessionStart` entry, output `{"additional_context": "..."}` |
104
105
  | omp | `~/.omp/agent/extensions/but-axi.ts` | Auto-discovered TypeScript extension (no config edit), see below |
105
106
 
106
107
  Setup merges into the existing file and never replaces it. Each file it edits is first copied to `<file>.bak-but-axi-<timestamp>`.
107
108
  Running setup again changes nothing (`already installed (no change)`), and a stale entry is repaired in place.
108
109
  Install and uninstall find the entry by the marker `# but-axi hook session-start` in the command.
109
- The hook command uses absolute paths to `node` and the script, so it works when an app starts with a short `PATH`.
110
+ The hook command is plain `but-axi` when that name on `PATH` resolves to the running script. Otherwise it uses absolute paths to `node` (a `PATH` symlink such as Homebrew's, which survives upgrades, when one points at the running node) and the script. Rerun setup after moving or reinstalling to repair it.
110
111
  The hook reads the session directory from the hook's stdin JSON (`cwd`, or Cursor's `workspace_roots`) and prints nothing outside a GitButler workspace or on any error.
111
112
 
112
113
  omp has no shell hook config, so but-axi writes a small extension instead, rendered from [`omp/but-axi.ts`](omp/but-axi.ts) with the absolute `node` and script paths baked in.
@@ -115,6 +116,8 @@ Before the first agent turn it appends the dashboard to the system prompt. Outsi
115
116
  The file carries the marker `but-axi-omp-extension`. Setup only overwrites or removes a `but-axi.ts` that has the marker, and refuses to touch one that does not.
116
117
  Before it updates or removes the file, setup copies it to `~/.omp/agent/but-axi.ts.bak-but-axi-<timestamp>`. The copy goes outside `extensions/` so omp does not load it.
117
118
 
119
+ The OpenCode plugin follows the same rules: marker `but-axi managed opencode plugin`, foreign files are refused, backups go to `~/.config/opencode/` (outside `plugins/`). It runs the hook once per session (5 second timeout) and adds nothing outside a GitButler workspace.
120
+
118
121
  Not covered: jcode (its `session_start` setting is a single command that is already in use).
119
122
  Cursor note: Cursor has a [known issue](https://forum.cursor.com/t/sessionstart-hook-additional-context-is-never-injected-into-agents-initial-system-context/158452) where `sessionStart` `additional_context` can be dropped.
120
123
 
@@ -138,6 +141,8 @@ but-axi undo | but-axi redo # oplog undo/redo, return compact summa
138
141
  but-axi oplog [--limit 20] # operation history
139
142
  but-axi oplog snapshot -m "<msg>" # snapshot id + compact summary
140
143
  but-axi oplog restore <id> # restore, return compact summary
144
+ but-axi log [-n 20] [--path <file>] # commit history (grit when installed, else git)
145
+ but-axi blame <file> -L 1,40 # line ranges grouped by commit
141
146
  but-axi -C ~/code/app status # any command against another directory
142
147
  ```
143
148
 
@@ -209,13 +214,15 @@ patch_note: "(truncated, 24979 chars total — use --full to see complete diff)"
209
214
  | `status` | `uncommitted{id,path,change}`, `branches{id,name,commits,state}`, `commits{id,branch,subject}` |
210
215
  | `diff [<id>]` | `hunks{id,path,status,lines}` plus a truncated `patch` |
211
216
  | `show <id\|branch>` | Commit: id, sha, author, date, subject, body, files. Branch: commits, base, stackedOn |
212
- | `commit` | `-m` (repeatable), `-b <branch>`, optional change IDs. Never opens an editor. With nothing to commit it prints `skipped` and exits 0 |
217
+ | `commit` | `-m` (repeatable), `-b <branch>`, `-n`/`--no-hooks`, optional change IDs. Never opens an editor. With nothing to commit it prints `skipped` and exits 0. A failing Git hook gives `HOOK_FAILED` |
213
218
  | `branch [list\|new\|show]` | List, create (an existing branch is reported as `already exists (no change)`), show |
214
- | `push [<branch>]` | `--dry-run`, `--with-force`, `--no-verify`. Already pushed gives `pushed 0 branches` and exit 0 |
219
+ | `push [<branch>]` | `--dry-run`, `--with-force`, `--no-verify`. Already pushed gives `pushed 0 branches` and exit 0. A dry run that `but` would refuse (conflicted commits) exits 1 with `PUSH_REFUSED` and the reason per branch |
215
220
  | `undo`, `redo` | Oplog undo or redo plus the compact workspace summary |
216
221
  | `oplog [list\|snapshot\|restore]` | list: `--limit <n>`. snapshot: `-m <msg>`, returns the snapshot id and compact summary. restore: `<id>` and that summary. A flag from the wrong subcommand is a usage error |
222
+ | `log [<rev>]` | `commits{sha,subject,when}` (+`author,date,refs`), `-n`/`--limit`, `--path` (repeatable). Read-only |
223
+ | `blame <file>` | `blame{lines,sha,author,summary}` (+`date,when`), `-L a,b`, `--rev`. Uncommitted lines show `uncommitted`. Read-only |
217
224
  | `setup hooks` | `--status`, `--uninstall`, `--agents`, `--dry-run` |
218
- | `hook session-start` | Hook entrypoint (`--agent claude\|codex\|cursor\|omp`). Any other agent name is a usage error |
225
+ | `hook session-start` | Hook entrypoint (`--agent claude\|codex\|opencode\|cursor\|omp`). Any other agent name is a usage error |
219
226
  | `version` | Print the version. Extra arguments are a usage error |
220
227
 
221
228
  ### Global flags
@@ -253,19 +260,24 @@ Fixed context (`-C <path>`) is carried forward. Values the agent has to choose s
253
260
  ### Environment
254
261
 
255
262
  - `BUT_AXI_BUT=/path/to/but` sets which `but` binary to use. By default but-axi looks on `PATH`, then in `/opt/homebrew/bin`, `/usr/local/bin`, and `~/.local/bin`.
256
- - `BUT_AXI_NODE=/path/to/node` sets the node binary written into hook commands. The default is `/opt/homebrew/bin/node` when it exists.
257
- - `BUT_AXI_DEBUG=1` writes the `but` invocations to stderr.
263
+ - `BUT_AXI_GRIT=/path/to/grit` sets which `grit` to use for `log` and `blame`. By default but-axi looks on `PATH`, then in `~/.local/bin` (where the grit install script puts it). `BUT_AXI_NO_GRIT=1` forces plain `git`.
264
+ - `BUT_AXI_DEBUG=1` writes the `but`, `grit`, and `git` invocations to stderr.
265
+
266
+ ## History with grit
267
+
268
+ [grit](https://github.com/gitbutlerapp/grit) is GitButler's Git engine in Rust. Its `grit` CLI has `--json` output, which `log` and `blame` use when it is installed (`curl -fsSL https://grit-scm.com/install | sh`). Without it they fall back to `git` with the same output shape, and the `engine:` line says which one ran.
269
+ but-axi only runs grit's read-only `log` and `blame`. grit's own `commit`, `switch`, and `reset` move `HEAD` without GitButler, so do not use them inside a GitButler workspace.
258
270
 
259
271
  ## Fallback to raw `but`
260
272
 
261
273
  but-axi wraps the core loop: inspect, commit, branch, push, and undo.
262
- For everything else, use `but` directly: `amend`, `absorb`, `squash`, `move`, `reword`, `uncommit`, `discard`, `resolve`, `apply`, `unapply`, `pull`, `pr`, `land`, `pick`, `worktree`, `setup`, `teardown`.
274
+ For everything else, use `but` directly: `amend`, `absorb`, `squash`, `move`, `reword`, `uncommit`, `discard`, `resolve`, `apply`, `unapply`, `pull`, `pr`, `merge`, `pick`, `split`, `worktree`, `init`, `teardown`.
263
275
  If you call one of these on but-axi, it exits 2 and tells you to use `but <command> --help`.
264
276
  CLI IDs from `but-axi status` and `but-axi diff` are the same IDs `but` uses, so you can pass them straight to `but`.
265
277
 
266
278
  ## Agent skill
267
279
 
268
- The `gitbutler-axi` Agent Skill (`~/.agents/skills/gitbutler-axi/SKILL.md` on the author's machine) teaches agents when to use but-axi, how to read its output, and when to fall back to raw `but`.
280
+ The `but-axi` Agent Skill ([`skills/but-axi/SKILL.md`](skills/but-axi/SKILL.md), generated by `src/skill.ts` and checked by `npm run skill:check`) tells agents when to use but-axi and sends them to `npx -y but-axi --help` for current usage.
269
281
  The hook gives an agent context at the start of every session. The skill gives it the full guide when it needs one.
270
282
 
271
283
  ## Development
@@ -276,7 +288,7 @@ npm run build # tsc -> dist/
276
288
  npm test # build + vitest (unit tests + CLI exit-code tests + a real `but` flow in /tmp)
277
289
  ```
278
290
 
279
- The integration suite creates a throwaway repo and a bare remote under `/tmp`, runs `but setup`, then commits, pushes, and undoes there. It is skipped when `but` is not installed.
291
+ The integration suite creates a throwaway repo and a bare remote under `/tmp`, then commits, pushes, and undoes there. It is skipped when `but` is not installed.
280
292
 
281
293
  ## License
282
294
 
package/dist/src/but.js CHANGED
@@ -97,7 +97,9 @@ export function cleanMessage(text) {
97
97
  .map((l) => l.trim())
98
98
  .filter(Boolean)
99
99
  .filter((l) => !/^(Usage:|For more information)/.test(l));
100
- const first = (lines[0] ?? "").replace(/^Error:\s*/i, "").replace(/^error:\s*/, "");
100
+ let first = (lines[0] ?? "").replace(/^Error:\s*/i, "").replace(/^error:\s*/, "");
101
+ if (first.endsWith(":") && lines[1])
102
+ first = `${first} ${lines.slice(1, 4).join(" | ")}`;
101
103
  return first;
102
104
  }
103
105
  /** Convert a failed `but` invocation into a structured error. */
@@ -123,7 +125,7 @@ export function butError(r, args) {
123
125
  if (/No GitButler project|No git repository|setup required/i.test(message) || code === "SETUP_REQUIRED") {
124
126
  code = "NOT_A_WORKSPACE";
125
127
  help.length = 0;
126
- help.push("Run `but setup` in the repository to enable GitButler (raw but; not wrapped)");
128
+ help.push("Run `but init` to create a git repo (GitButler 0.23+ needs no `but setup`; raw but, not wrapped)");
127
129
  help.push("Or pass `-C <path>` to point at a GitButler workspace");
128
130
  }
129
131
  else {
package/dist/src/cli.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { resolve } from "node:path";
2
2
  import { bool, maxPositionals, parseArgs, rejectFlags, str } from "./args.js";
3
- import { branchList, branchNew, commit, diffView, homeView, makeCtx, oplogList, oplogRestore, oplogSnapshot, push, run, showView, statusView, undoRedo, } from "./commands.js";
3
+ import { branchList, branchNew, commit, diffView, homeView, makeCtx, blameView, logView, oplogList, oplogRestore, oplogSnapshot, push, run, showView, statusView, undoRedo, } from "./commands.js";
4
4
  import { AxiError, UsageError } from "./errors.js";
5
5
  import { plural, render, renderError, tildify } from "./format.js";
6
6
  import { COMMAND_HELP, TOP_HELP } from "./help.js";
@@ -8,7 +8,7 @@ import { AGENTS, hookCwd, hookStatus, installHooks, parseAgents, readHookInput }
8
8
  import { isBareVersion, VERSION } from "./version.js";
9
9
  const RAW_BUT = new Set([
10
10
  "amend", "absorb", "squash", "move", "reword", "uncommit", "discard", "resolve", "apply", "unapply",
11
- "pull", "pr", "land", "pick", "worktree", "teardown", "clean", "open", "gui", "tui", "config", "alias", "skill", "agent", "update", "completions",
11
+ "pull", "pr", "merge", "land", "pick", "split", "worktree", "init", "teardown", "clean", "gui", "tui", "config", "alias", "skill", "agent", "update", "completions",
12
12
  ]);
13
13
  export function version() {
14
14
  return VERSION;
@@ -18,12 +18,14 @@ const SPECS = {
18
18
  status: {},
19
19
  diff: {},
20
20
  show: {},
21
- commit: { message: { type: "strings", short: "m" }, branch: { type: "string", short: "b" } },
21
+ commit: { message: { type: "strings", short: "m" }, branch: { type: "string", short: "b" }, "no-hooks": { type: "boolean", short: "n", aliases: ["no-verify"] } },
22
22
  branch: { above: { type: "string", short: "A" }, below: { type: "string", short: "B" } },
23
23
  push: { "dry-run": { type: "boolean", short: "d" }, "with-force": { type: "boolean", short: "f" }, "no-verify": { type: "boolean" } },
24
24
  undo: {},
25
25
  redo: {},
26
26
  oplog: { limit: { type: "string", short: "n" }, message: { type: "string", short: "m" } },
27
+ log: { limit: { type: "string", short: "n" }, path: { type: "strings", short: "p" } },
28
+ blame: { lines: { type: "string", short: "L" }, rev: { type: "string" } },
27
29
  setup: { uninstall: { type: "boolean" }, status: { type: "boolean" }, agents: { type: "string" }, "dry-run": { type: "boolean" } },
28
30
  hook: { agent: { type: "string" } },
29
31
  version: { version: { type: "boolean", short: "v", shorts: ["V"] } },
@@ -124,6 +126,10 @@ export async function main(argv, bin = process.argv[1] ?? "but-axi") {
124
126
  return ok(oplogRestore(ctx));
125
127
  throw new UsageError(`unknown oplog subcommand ${sub}`, ["Run `but-axi oplog --help`"], "UNKNOWN_COMMAND");
126
128
  }
129
+ case "log":
130
+ return ok(logView(ctx));
131
+ case "blame":
132
+ return ok(blameView(ctx));
127
133
  case "setup":
128
134
  return setup(ctx.p.positionals, bool(ctx.p, "uninstall"), bool(ctx.p, "status"), str(ctx.p, "agents"), bool(ctx.p, "dry-run"));
129
135
  case "hook":
@@ -165,6 +171,8 @@ function setup(pos, uninstall, status, agentsFlag, dryRun) {
165
171
  : ["Start a new agent session inside a GitButler repo to see the dashboard", "Run `but-axi setup hooks --status`", "Run `but-axi setup hooks --uninstall` to remove"];
166
172
  if (!uninstall && rows.some((r) => r.agent === "codex" && r.action === "installed"))
167
173
  help.push("Codex may ask you to trust the new hook on its next start");
174
+ if (!uninstall && rows.some((r) => r.agent === "opencode" && r.action === "installed"))
175
+ help.push("OpenCode loads plugins at startup: restart OpenCode to see the dashboard");
168
176
  if (!uninstall && rows.some((r) => r.agent === "omp" && r.action === "installed"))
169
177
  help.push("omp loads extensions at startup: restart omp, then `/but-axi` shows the dashboard");
170
178
  return ok({
@@ -3,10 +3,11 @@ import { bool, fieldsOf, maxPositionals, parseArgs, rejectFlags, str, strs } fro
3
3
  import { butJson, runBut, butError } from "./but.js";
4
4
  import { AxiError, UsageError } from "./errors.js";
5
5
  import { ago, body, filterLines, filterRows, plural, project, putList, subject, tildify, truncate, truncationHint, validateFields, } from "./format.js";
6
- import { loadWorkspace, workspaceBlock } from "./workspace.js";
6
+ import { historyBlame, historyLog } from "./grit.js";
7
+ import { gitRoot, loadWorkspace, workspaceBlock } from "./workspace.js";
7
8
  export const DESCRIPTION = "Agent-ergonomic GitButler CLI that wraps `but --json` with compact TOON views and combined actions";
8
9
  export const HOME_BRANCHES = 12;
9
- export const LIMITS = { patch: 3000, body: 800, commits: 20, oplog: 10 };
10
+ export const LIMITS = { patch: 3000, body: 800, commits: 20, oplog: 10, log: 20, blame: 60 };
10
11
  /** Build a help template: `Run \`but-axi [-C <dir>] <rest>\``. */
11
12
  export function run(ctx, rest, why) {
12
13
  const pre = ctx.cwdFlag ? `but-axi -C ${quoteArg(ctx.cwdFlag)} ` : "but-axi ";
@@ -63,7 +64,7 @@ export function homeView(ctx, bin) {
63
64
  data.workspace = `none — ${tildify(ctx.cwd)} is not a GitButler workspace`;
64
65
  return {
65
66
  data,
66
- help: ["Run `but setup` inside a git repo to enable GitButler (raw but)", run(ctx, "-C <path>", "to view another workspace"), run(ctx, "--help")],
67
+ help: ["Run `but init` to create a repo, or run but-axi inside any git repo (GitButler 0.23+ needs no setup)", run(ctx, "-C <path>", "to view another workspace"), run(ctx, "--help")],
67
68
  };
68
69
  }
69
70
  throw e;
@@ -92,7 +93,7 @@ export function statusView(ctx, ws) {
92
93
  const unc = filterRows(ws.uncommitted, ctx.query);
93
94
  const br = filterRows(ws.branches, ctx.query);
94
95
  const cm = filterRows(ws.commits, ctx.query);
95
- data.count = `${plural(ws.branches.length, "branch", "branches")}; ${plural(ws.commits.length, "commit")}; ${ws.uncommitted.length} uncommitted; ${plural(ws.conflicts, "conflict")}`;
96
+ data.count = `${plural(ws.branches.length, "branch", "branches")}; ${plural(ws.commits.length, "commit")}; ${ws.uncommitted.length} uncommitted; ${plural(ws.conflicts, "conflict")}${ws.worktrees.length ? `; ${plural(ws.worktrees.length, "worktree")}` : ""}`;
96
97
  data.upstream = ws.behind > 0 ? `behind ${ws.behind} (run \`but pull\` to update)` : "up to date";
97
98
  if (ctx.query) {
98
99
  data.query = ctx.query;
@@ -105,6 +106,9 @@ export function statusView(ctx, ws) {
105
106
  putList(data, "commits", project(shown, COMMITS, ctx.fields), none("commits on applied branches"));
106
107
  if (shown.length < cm.length)
107
108
  data.commits_note = `(showing ${shown.length} of ${cm.length} — use --full to see all commits)`;
109
+ const wt = filterRows(ws.worktrees, ctx.query);
110
+ if (wt.length)
111
+ data.worktrees = wt;
108
112
  const help = [];
109
113
  if (ws.uncommitted.length)
110
114
  help.push(run(ctx, "diff <id>"), run(ctx, `commit -b <branch> -m "<message>" <id>...`));
@@ -296,12 +300,17 @@ export function commit(ctx) {
296
300
  workspaceBlock(before, data);
297
301
  return { data, help: [run(ctx, "status"), run(ctx, "push <branch>")] };
298
302
  }
299
- const args = ["commit", ...changes, ...messages.flatMap((m) => ["-m", m]), ...(branch ? ["-b", branch] : [])];
303
+ const noHooks = bool(ctx.p, "no-hooks");
304
+ const args = ["commit", ...changes, ...messages.map((m) => `--message=${m}`), ...(branch ? ["-b", branch] : []), ...(noHooks ? ["--no-hooks"] : [])];
300
305
  let res;
301
306
  try {
302
307
  res = butJson(args, ctx.cwd);
303
308
  }
304
309
  catch (e) {
310
+ if (e instanceof AxiError && /hook failed/i.test(e.message)) {
311
+ const again = `commit --no-hooks -m "<message>"${branch ? ` -b ${branch}` : ""}${changes.length ? " " + changes.join(" ") : ""}`;
312
+ throw new AxiError(e.message, "HOOK_FAILED", ["Fix what the hook reported, then rerun the same commit", run(ctx, again, "to skip Git hooks")]);
313
+ }
305
314
  if (e instanceof AxiError && !branch && /branch|stack|--above|--below/i.test(e.message)) {
306
315
  e.help.unshift(run(ctx, `commit -b <branch> -m "<message>"${changes.length ? " " + changes.join(" ") : ""}`));
307
316
  }
@@ -332,8 +341,16 @@ export function push(ctx) {
332
341
  const force = bool(ctx.p, "with-force");
333
342
  const extra = [...(force ? ["--with-force"] : []), ...(bool(ctx.p, "no-verify") ? ["--no-verify"] : [])];
334
343
  if (dry) {
335
- const raw = butJson(["push", ...(branch ? [branch] : []), "--dry-run", ...extra], ctx.cwd);
336
- const rows = (raw.branches ?? []).map((b) => ({ branch: b.branchName, commits: b.unpushedCommits ?? 0, remote: b.remote ?? "", force: !!b.requiresForce }));
344
+ const args = ["push", ...(branch ? [branch] : []), "--dry-run", ...extra];
345
+ const r = runBut(args, ctx.cwd);
346
+ const raw = r.json;
347
+ if (r.code !== 0 && !Array.isArray(raw?.branches))
348
+ throw butError(r, args);
349
+ const rows = (raw?.branches ?? []).map((b) => ({ branch: b.branchName, commits: b.unpushedCommits ?? 0, remote: b.remote ?? "", force: !!b.requiresForce, ...(b.warning ? { warning: b.warning } : {}) }));
350
+ if (r.code !== 0) {
351
+ const refused = rows.filter((x) => x.warning);
352
+ throw new AxiError(`${butError(r, args).message}: ${refused.map((x) => `${x.branch} (${String(x.warning).split("\n")[0]})`).join("; ").slice(0, 600) || "see `but push --dry-run`"}`, "PUSH_REFUSED", [run(ctx, "status", "to find conflicted commits"), "Run `but resolve conflicts <commit-id>` to fix a conflicted commit (raw but)", ...(rows.length > refused.length ? [run(ctx, "push <branch>", "to push a clean branch alone")] : [])]);
353
+ }
337
354
  const data = { dry_run: true, count: `${plural(rows.length, "branch", "branches")} would be pushed` };
338
355
  putList(data, "would_push", rows, "0 branches — nothing to push");
339
356
  return { data, help: rows.length ? [run(ctx, `push ${branch ?? "<branch>"}`)] : [run(ctx, "status")] };
@@ -413,3 +430,72 @@ export function oplogRestore(ctx) {
413
430
  workspaceBlock(ws, data);
414
431
  return { data, help: [run(ctx, "undo", "to undo the restore"), run(ctx, "status")] };
415
432
  }
433
+ /* ---------------------------------------------------------------- history (grit or git, read-only) */
434
+ const LOG = { name: "commits", defaults: ["sha", "subject", "when"], extras: ["author", "date", "refs"] };
435
+ /** `log [<rev>] [--limit N] [--path <file>...]`: commit history via grit --json when installed, else git. */
436
+ export function logView(ctx) {
437
+ maxPositionals(ctx.p, 1, "log");
438
+ validateFields(ctx.fields, [LOG], "log");
439
+ const limitRaw = str(ctx.p, "limit");
440
+ const limit = limitRaw ? Number(limitRaw) : LIMITS.log;
441
+ if (!Number.isInteger(limit) || limit < 1)
442
+ throw new UsageError(`--limit must be a positive integer, got "${limitRaw}"`, [run(ctx, "log --limit 50")], "INVALID_VALUE");
443
+ const rev = ctx.p.positionals[0];
444
+ rejectOptionLike(ctx, rev, "log");
445
+ const paths = strs(ctx.p, "path");
446
+ const { engine, commits } = historyLog(gitRoot(ctx.cwd), { rev, limit, paths });
447
+ const more = commits.length > limit;
448
+ const all = commits.slice(0, limit).map((c) => ({ sha: c.sha.slice(0, 7), subject: c.subject, when: ago(Date.parse(c.date)), author: c.author, date: c.date, refs: c.refs }));
449
+ const rows = filterRows(all, ctx.query);
450
+ const data = { engine, count: `${plural(all.length, "commit")}${more ? ` (more available — use --limit ${limit * 2})` : ""}` };
451
+ if (rev)
452
+ data.rev = rev;
453
+ if (paths.length)
454
+ data.paths = paths.join(" ");
455
+ queryNote(data, ctx, rows.length, all.length, "commit");
456
+ putList(data, "commits", project(rows, LOG, ctx.fields), ctx.query ? "0 matching commits" : "0 commits");
457
+ const help = [run(ctx, "show <sha>"), run(ctx, "blame <file>")];
458
+ if (more)
459
+ help.unshift(run(ctx, `log${rev ? ` ${rev}` : ""} --limit ${limit * 2}`));
460
+ return { data, help };
461
+ }
462
+ function rejectOptionLike(ctx, rev, cmd) {
463
+ if (rev?.startsWith("-"))
464
+ throw new UsageError(`revision must not start with "-", got "${rev}"`, [run(ctx, `${cmd} --help`)], "INVALID_VALUE");
465
+ }
466
+ const BLAME = { name: "blame", defaults: ["lines", "sha", "author", "summary"], extras: ["date", "when"] };
467
+ /** `blame <file> [-L a,b] [--rev <rev>]`: who last changed each line range, grouped by commit. */
468
+ export function blameView(ctx) {
469
+ maxPositionals(ctx.p, 1, "blame");
470
+ validateFields(ctx.fields, [BLAME], "blame");
471
+ const file = ctx.p.positionals[0];
472
+ if (!file)
473
+ throw new UsageError("blame needs a <file> (repository-relative)", [run(ctx, "blame <file> -L 1,40")], "MISSING_ARGUMENT");
474
+ const range = str(ctx.p, "lines");
475
+ if (range !== undefined && !/^\d+(,(\+?\d+)?)?$/.test(range))
476
+ throw new UsageError(`-L must look like 10,20 or 10,+5, got "${range}"`, [run(ctx, `blame ${file} -L 1,40`)], "INVALID_VALUE");
477
+ const brev = str(ctx.p, "rev");
478
+ rejectOptionLike(ctx, brev, "blame");
479
+ const { engine, lines } = historyBlame(gitRoot(ctx.cwd), file, { range, rev: brev });
480
+ const groups = [];
481
+ for (const l of lines) {
482
+ const last = groups[groups.length - 1];
483
+ if (last && last.full === l.sha && last.end === l.line - 1) {
484
+ last.end = l.line;
485
+ continue;
486
+ }
487
+ groups.push({ full: l.sha, start: l.line, end: l.line, sha: l.uncommitted ? "uncommitted" : l.sha.slice(0, 7), author: l.author, summary: l.summary, date: l.date, when: l.date ? ago(Date.parse(l.date)) : "" });
488
+ }
489
+ for (const g of groups)
490
+ g.lines = g.start === g.end ? String(g.start) : `${g.start}-${g.end}`;
491
+ const rows = filterRows(groups, ctx.query);
492
+ const shas = new Set(lines.filter((l) => !l.uncommitted).map((l) => l.sha));
493
+ const uncommitted = lines.filter((l) => l.uncommitted).length;
494
+ const data = { engine, file, count: `${plural(lines.length, "line")}; ${plural(shas.size, "commit")}; ${uncommitted} uncommitted` };
495
+ queryNote(data, ctx, rows.length, groups.length, "range");
496
+ const shown = ctx.full ? rows : rows.slice(0, LIMITS.blame);
497
+ putList(data, "blame", project(shown, BLAME, ctx.fields), ctx.query ? "0 matching ranges" : "0 lines");
498
+ if (shown.length < rows.length)
499
+ data.blame_note = `(showing ${shown.length} of ${rows.length} ranges — use -L a,b or --full)`;
500
+ return { data, help: [run(ctx, "show <sha>"), run(ctx, `log --path ${file}`)] };
501
+ }
@@ -0,0 +1,145 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import { existsSync } from "node:fs";
3
+ import { homedir } from "node:os";
4
+ import { delimiter, join } from "node:path";
5
+ import { debug } from "./but.js";
6
+ import { AxiError } from "./errors.js";
7
+ /**
8
+ * Read-only history engine. Uses GitButler's `grit` (Git in Rust, `--json`) when installed, else plain `git`.
9
+ * Only these grit verbs are ever run: grit mutations (commit, switch, reset, ...) move HEAD behind GitButler's back.
10
+ */
11
+ const GRIT_READ_ONLY = new Set(["log", "blame"]);
12
+ let cachedGrit;
13
+ /** Locate `grit`: $BUT_AXI_GRIT, then PATH, then the install script's ~/.local/bin. BUT_AXI_NO_GRIT=1 disables it. */
14
+ export function resolveGrit(env = process.env) {
15
+ if (env.BUT_AXI_NO_GRIT)
16
+ return undefined;
17
+ if (env.BUT_AXI_GRIT)
18
+ return env.BUT_AXI_GRIT;
19
+ if (cachedGrit !== undefined)
20
+ return cachedGrit ?? undefined;
21
+ const dirs = [...(env.PATH ?? "").split(delimiter).filter(Boolean), join(homedir(), ".local", "bin")];
22
+ cachedGrit = dirs.map((d) => join(d, "grit")).find((p) => existsSync(p)) ?? null;
23
+ return cachedGrit ?? undefined;
24
+ }
25
+ function exec(bin, args, cwd) {
26
+ debug(`exec ${bin} ${args.join(" ")} (cwd ${cwd})`);
27
+ const r = spawnSync(bin, args, {
28
+ cwd,
29
+ encoding: "utf8",
30
+ stdio: ["ignore", "pipe", "pipe"],
31
+ timeout: 60_000,
32
+ maxBuffer: 64 * 1024 * 1024,
33
+ env: { ...process.env, NO_COLOR: "1", GIT_PAGER: "cat", PAGER: "cat", GIT_TERMINAL_PROMPT: "0" },
34
+ });
35
+ if (r.error)
36
+ throw new AxiError(`failed to run ${bin}: ${r.error.message}`, "HISTORY_EXEC_FAILED");
37
+ return { code: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
38
+ }
39
+ function grit(bin, args, cwd) {
40
+ if (!GRIT_READ_ONLY.has(args[0] ?? ""))
41
+ throw new AxiError(`refusing to run grit ${args[0]}: but-axi only runs read-only grit verbs`, "GRIT_NOT_ALLOWED");
42
+ const r = exec(bin, [args[0], "--json", ...args.slice(1)], cwd);
43
+ let j;
44
+ try {
45
+ j = JSON.parse(r.stdout || r.stderr);
46
+ }
47
+ catch {
48
+ j = undefined;
49
+ }
50
+ if (r.code !== 0) {
51
+ const e = j;
52
+ throw historyError(e?.error ?? (r.stderr.trim().split("\n")[0] || `grit ${args[0]} exited ${r.code}`), e?.kind);
53
+ }
54
+ return j;
55
+ }
56
+ function git(args, cwd) {
57
+ const r = exec("git", args, cwd);
58
+ if (r.code !== 0)
59
+ throw historyError(r.stderr.trim().split("\n")[0]?.replace(/^(fatal|error):\s*/, "") || `git ${args[0]} exited ${r.code}`);
60
+ return r.stdout;
61
+ }
62
+ function historyError(message, kind) {
63
+ if (kind === "not_a_repository" || /not a git repository/i.test(message)) {
64
+ return new AxiError(message, "NOT_A_REPOSITORY", ["Pass `-C <path>` to point at a Git repository"]);
65
+ }
66
+ if (kind === "path_not_found" || /no such path|does not exist/i.test(message))
67
+ return new AxiError(message, "PATH_NOT_FOUND", ["Paths are repository-relative"]);
68
+ return new AxiError(message, "HISTORY_ERROR", ["Run with BUT_AXI_NO_GRIT=1 to retry with plain git"]);
69
+ }
70
+ /** Up to `limit + 1` commits so the caller can tell whether more exist. */
71
+ export function historyLog(cwd, opts) {
72
+ assertRev(opts.rev);
73
+ const bin = resolveGrit();
74
+ const want = opts.limit + 1;
75
+ const tail = opts.paths?.length ? ["--", ...opts.paths] : [];
76
+ if (bin) {
77
+ const j = grit(bin, ["log", "-n", String(want), ...(opts.rev ? [opts.rev] : []), ...tail], cwd);
78
+ const commits = (j.commits ?? []).map((c) => ({
79
+ sha: c.oid,
80
+ subject: c.subject ?? "",
81
+ author: c.author?.name ?? "",
82
+ date: c.author?.date ?? "",
83
+ refs: (c.refs ?? []).filter((r) => r.kind !== "head").map((r) => r.name).join(" "),
84
+ }));
85
+ return { engine: "grit", commits };
86
+ }
87
+ const out = git(["log", "-n", String(want), "--format=%H%x1f%s%x1f%an%x1f%aI%x1f%D%x1e", ...(opts.rev ? [opts.rev] : []), ...tail], cwd);
88
+ const commits = out
89
+ .split("\x1e")
90
+ .map((s) => s.trim())
91
+ .filter(Boolean)
92
+ .map((s) => {
93
+ const [sha = "", subject = "", author = "", date = "", refs = ""] = s.split("\x1f");
94
+ return { sha, subject, author, date, refs: refs.split(", ").map((r) => r.replace(/^HEAD -> /, "")).filter((r) => r && r !== "HEAD").join(" ") };
95
+ });
96
+ return { engine: "git", commits };
97
+ }
98
+ const ZERO = /^0+$/;
99
+ function assertRev(rev) {
100
+ if (rev?.startsWith("-"))
101
+ throw new AxiError(`revision must not start with "-", got "${rev}"`, "INVALID_VALUE");
102
+ }
103
+ /** Per-line blame of the working tree file (uncommitted lines marked), or of `rev` when given. */
104
+ export function historyBlame(cwd, file, opts) {
105
+ assertRev(opts.rev);
106
+ const bin = resolveGrit();
107
+ const range = opts.range ? ["-L", opts.range] : [];
108
+ if (bin) {
109
+ const j = grit(bin, ["blame", ...range, ...(opts.rev ? ["--rev", opts.rev] : []), "--", file], cwd);
110
+ const lines = (j.lines ?? []).map((l) => {
111
+ const c = j.commits?.[l.commit];
112
+ const uncommitted = !!l.not_committed || ZERO.test(l.commit);
113
+ return { line: l.final_line, sha: l.commit, author: uncommitted ? "" : (c?.author?.name ?? ""), date: uncommitted ? "" : (c?.author?.date ?? ""), summary: uncommitted ? "" : (c?.summary ?? ""), uncommitted };
114
+ });
115
+ return { engine: "grit", lines };
116
+ }
117
+ const out = git(["blame", "--porcelain", ...range, ...(opts.rev ? [opts.rev] : []), "--", file], cwd);
118
+ const meta = new Map();
119
+ const lines = [];
120
+ let cur;
121
+ for (const l of out.split("\n")) {
122
+ const head = /^([0-9a-f]{40}) \d+ (\d+)/.exec(l);
123
+ if (head) {
124
+ cur = { sha: head[1], line: Number(head[2]) };
125
+ if (!meta.has(cur.sha))
126
+ meta.set(cur.sha, { author: "", date: "", summary: "" });
127
+ continue;
128
+ }
129
+ if (!cur)
130
+ continue;
131
+ const m = meta.get(cur.sha);
132
+ if (l.startsWith("author "))
133
+ m.author = l.slice(7);
134
+ else if (l.startsWith("author-time "))
135
+ m.date = new Date(Number(l.slice(12)) * 1000).toISOString();
136
+ else if (l.startsWith("summary "))
137
+ m.summary = l.slice(8);
138
+ else if (l.startsWith("\t")) {
139
+ const uncommitted = ZERO.test(cur.sha);
140
+ lines.push({ line: cur.line, sha: cur.sha, author: uncommitted ? "" : m.author, date: uncommitted ? "" : m.date, summary: uncommitted ? "" : m.summary, uncommitted });
141
+ cur = undefined;
142
+ }
143
+ }
144
+ return { engine: "git", lines };
145
+ }
package/dist/src/help.js CHANGED
@@ -1,28 +1,31 @@
1
1
  export const TOP_HELP = `usage: but-axi [command] [flags]
2
2
  description: Agent-ergonomic GitButler CLI. Wraps \`but ... --json\` with TOON output, counts, help[] hints.
3
3
  no command: home view (bin, workspace state, branches, next steps)
4
- commands[12]:
4
+ commands[14]:
5
5
  status Uncommitted files, branches, commits with IDs
6
6
  diff [<id>] Changed files + truncated patch (uncommitted, or one commit/file/branch id)
7
7
  show <commit|branch> Commit details or branch commit list
8
- commit -m <msg> [-b <branch>] [<id>...] Commit (all or selected changes); returns compact summary
8
+ commit -m <msg> [-b <branch>] [-n] [<id>...] Commit (all or selected changes); returns compact summary
9
9
  branch [list] Applied + unapplied branches
10
10
  branch new <name> Create branch (idempotent); returns compact summary
11
11
  push [<branch>] [--dry-run] Push branch(es); returns pushed refs + summary
12
12
  undo | redo Undo/redo last operation; returns compact summary
13
13
  oplog [list|snapshot|restore] Operation history
14
- setup hooks [--uninstall|--status] Install session-start dashboard (Claude Code, Codex, Cursor, omp)
14
+ log [<rev>] [-n <n>] [--path <file>] Commit history (read-only; grit --json when installed, else git)
15
+ blame <file> [-L a,b] [--rev <rev>] Who last changed each line range (read-only; grit or git)
16
+ setup hooks [--uninstall|--status] Install session-start dashboard (Claude Code, Codex, OpenCode, Cursor, omp)
15
17
  hook session-start Hook entrypoint (quiet outside GitButler workspaces)
16
18
  version Print version (-v, -V, --version)
17
19
  global flags: -C <path>, --fields a,b, --full, --query <text> (-q), --help (-h)
18
20
  exit codes: 0 ok, 1 runtime error, 2 usage (unknown command/flag/field, missing or invalid argument, extra argument)
19
- not wrapped (use raw \`but\`): amend absorb squash move reword uncommit discard resolve apply unapply pull pr land pick worktree setup teardown
21
+ not wrapped (use raw \`but\`): amend absorb squash move reword uncommit discard resolve apply unapply pull pr merge pick split worktree init teardown
20
22
  `;
21
23
  export const COMMAND_HELP = {
22
24
  status: `usage: but-axi status [--fields <f,...>] [--query <text>] [--full]
23
25
  Lists uncommitted changes, applied branches and their commits with CLI IDs.
24
26
  fields: uncommitted(id,path,change +branch,conflicted) branches(id,name,commits,state +stack,upstream,review,conflicts) commits(id,branch,subject +sha,author,date,conflicted,changeId)
25
27
  --full shows all commits (default first 20). --query filters every list.
28
+ Linked worktrees (GitButler 0.23+) are listed as worktrees(id,name,commits,uncommitted,behind) when present.
26
29
  `,
27
30
  diff: `usage: but-axi diff [<id>] [--full] [--query <text>] [--fields range]
28
31
  No id: all uncommitted changes, one row per hunk (id <file>:<hunk>, usable with commit).
@@ -36,6 +39,7 @@ Branch: commits (id,subject,files +sha,author,when,lines), base, stackedOn.
36
39
  commit: `usage: but-axi commit -m <message> [-m <paragraph>...] [-b <branch>] [<change-id>...]
37
40
  Commits all uncommitted changes, or only the listed file/hunk ids (from \`but-axi diff\`/\`status\`).
38
41
  -b creates the branch if missing. Never opens an editor. Nothing to commit => exit 0, "skipped".
42
+ Git commit hooks run; a failing hook returns code HOOK_FAILED. -n/--no-hooks (alias --no-verify) skips them.
39
43
  Returns the new commit plus a compact workspace summary (counts and applied branches).
40
44
  `,
41
45
  branch: `usage: but-axi branch [list] [--query <text>] [--fields author,mergesCleanly,local,reviews]
@@ -46,7 +50,8 @@ Returns the new commit plus a compact workspace summary (counts and applied bran
46
50
  `,
47
51
  push: `usage: but-axi push [<branch>] [--dry-run] [--with-force] [--no-verify]
48
52
  No branch: pushes every branch with unpushed commits. Already pushed => "pushed 0 branches", exit 0.
49
- --dry-run lists what would be pushed. A real push returns pushed refs plus a compact workspace summary.
53
+ --dry-run lists what would be pushed; if but would refuse a branch (conflicted commits) it exits 1 with code PUSH_REFUSED.
54
+ A real push returns pushed refs plus a compact workspace summary.
50
55
  `,
51
56
  undo: `usage: but-axi undo
52
57
  Reverts the last GitButler operation (oplog). Returns a compact workspace summary. See also: redo, oplog.
@@ -60,19 +65,28 @@ Re-applies the last undone operation. Returns a compact workspace summary.
60
65
  Lists recent operations (default 10). -m is snapshot-only; --limit is list-only.
61
66
  snapshot returns the snapshot id plus a compact workspace summary. restore returns that summary.
62
67
  `,
63
- setup: `usage: but-axi setup hooks [--agents claude,codex,cursor,omp] [--dry-run]
68
+ setup: `usage: but-axi setup hooks [--agents claude,codex,opencode,cursor,omp] [--dry-run]
64
69
  but-axi setup hooks --status
65
70
  but-axi setup hooks --uninstall [--agents ...]
66
71
  Installs a SessionStart hook that prints the home view at the start of each agent session
67
72
  (silent outside GitButler workspaces). Merges into existing config, backs up each file it edits
68
73
  (<file>.bak-but-axi-<timestamp>), and is idempotent. Targets: ~/.claude/settings.json,
69
- ~/.codex/hooks.json, ~/.cursor/hooks.json, and the omp extension ~/.omp/agent/extensions/but-axi.ts
70
- (backups of it go to ~/.omp/agent/but-axi.ts.bak-but-axi-<timestamp>).
74
+ ~/.codex/hooks.json, ~/.cursor/hooks.json, the OpenCode plugin ~/.config/opencode/plugins/but-axi.js,
75
+ and the omp extension ~/.omp/agent/extensions/but-axi.ts (plugin backups go one level up).
76
+ Hooks run \`but-axi\` by name when it is on PATH, else absolute node + script paths; rerun to repair.
71
77
  `,
72
- hook: `usage: but-axi hook session-start [--agent claude|codex|cursor|omp]
78
+ hook: `usage: but-axi hook session-start [--agent claude|codex|opencode|cursor|omp]
73
79
  Hook entrypoint. Prints the compact home view for the session directory; prints nothing (exit 0)
74
80
  outside a GitButler workspace or on a runtime error. Unknown --agent is a usage error (exit 2).
75
81
  --agent cursor wraps output as {"additional_context": ...}.
82
+ `,
83
+ log: `usage: but-axi log [<rev>] [-n|--limit <n>] [--path <file>...] [--query <text>] [--fields author,date,refs]
84
+ Read-only commit history (default 20 from HEAD). Uses GitButler's grit (--json) when installed, else git.
85
+ Paths are repository-relative. BUT_AXI_NO_GRIT=1 forces git. but-axi never runs grit mutations.
86
+ `,
87
+ blame: `usage: but-axi blame <file> [-L <a,b>] [--rev <rev>] [--full] [--query <text>] [--fields date,when]
88
+ Line ranges grouped by commit (lines,sha,author,summary). Without --rev the working tree is blamed and
89
+ uncommitted lines show sha "uncommitted". Default first 60 ranges; -L narrows, --full shows all.
76
90
  `,
77
91
  version: `usage: but-axi version
78
92
  Prints the version. Same output as bare \`-v\`, \`-V\`, or \`--version\`. Extra arguments are a usage error.
package/dist/src/hooks.js CHANGED
@@ -1,13 +1,13 @@
1
- import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
1
+ import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
2
2
  import { homedir } from "node:os";
3
- import { dirname, join } from "node:path";
3
+ import { delimiter, dirname, join } from "node:path";
4
4
  import { AxiError } from "./errors.js";
5
5
  import { tildify } from "./format.js";
6
6
  import { ompInstalled, ompOps, ompPaths } from "./omp.js";
7
- export const AGENTS = ["claude", "codex", "cursor", "omp"];
8
- /** Stable symlink that survives Homebrew node upgrades. */
9
- export const STABLE_NODE = process.env.BUT_AXI_NODE ?? "/opt/homebrew/bin/node";
7
+ import { opencodeInstalled, opencodeOps, opencodePaths } from "./opencode.js";
8
+ export const AGENTS = ["claude", "codex", "opencode", "cursor", "omp"];
10
9
  export const MARKER = "but-axi hook session-start";
10
+ const BIN = "but-axi";
11
11
  export function targets(home = homedir()) {
12
12
  return [
13
13
  { agent: "claude", dir: join(home, ".claude"), file: join(home, ".claude", "settings.json") },
@@ -15,34 +15,44 @@ export function targets(home = homedir()) {
15
15
  { agent: "cursor", dir: join(home, ".cursor"), file: join(home, ".cursor", "hooks.json") },
16
16
  ];
17
17
  }
18
- /** Absolute, PATH-independent hook command (GUI-launched agents often have a thin PATH). */
19
- export function hookCommand(agent, nodePath = process.execPath, script = process.argv[1] ?? "") {
20
- const q = (s) => `'${s.replace(/'/g, "'\\''")}'`;
21
- const { node, js } = runtimePaths(nodePath, script);
22
- // The marker text must appear verbatim in the command so install/uninstall can find it.
23
- return `${q(node)} ${q(js)} hook session-start --agent ${agent} # ${MARKER}`;
18
+ /** Hook command: the PATH name when it resolves to this script (AXI §7), else absolute node + script paths. */
19
+ export function hookCommand(agent, nodePath = process.execPath, script = process.argv[1] ?? "", pathEnv = process.env.PATH ?? "") {
20
+ return `${launcher(nodePath, script, pathEnv).map(shq).join(" ")} hook session-start --agent ${agent} # ${MARKER}`;
24
21
  }
25
- /** Stable absolute node + script paths for hook commands and the omp extension. */
26
- export function runtimePaths(nodePath = process.execPath, script = process.argv[1] ?? "") {
27
- let node = nodePath;
28
- let js = script;
29
- if (existsSync(STABLE_NODE))
30
- node = STABLE_NODE;
31
- else if (/fnm_multishells|\/tmp\//.test(nodePath)) {
32
- try {
33
- node = realpathSync(nodePath);
34
- }
35
- catch {
36
- /* keep */
37
- }
22
+ function shq(s) {
23
+ return /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, "'\\''")}'`;
24
+ }
25
+ /** argv prefix that runs this but-axi: ["but-axi"] when PATH resolves to it, else [node, script]. */
26
+ export function launcher(nodePath = process.execPath, script = process.argv[1] ?? "", pathEnv = process.env.PATH ?? "") {
27
+ const self = real(script);
28
+ const first = pathEnv.split(delimiter).filter(Boolean).map((dir) => join(dir, BIN)).find(isExecutable);
29
+ if (self && first && real(first) === self)
30
+ return [BIN];
31
+ const { node, js } = runtimePaths(nodePath, script, pathEnv);
32
+ return [node, js];
33
+ }
34
+ function isExecutable(p) {
35
+ try {
36
+ accessSync(p, constants.X_OK);
37
+ return statSync(p).isFile();
38
+ }
39
+ catch {
40
+ return false;
38
41
  }
42
+ }
43
+ function real(p) {
39
44
  try {
40
- js = realpathSync(script);
45
+ return statSync(p).isFile() ? realpathSync(p) : undefined;
41
46
  }
42
47
  catch {
43
- /* keep */
48
+ return undefined;
44
49
  }
45
- return { node, js };
50
+ }
51
+ /** Stable absolute node + script paths: prefer a `node` on PATH that resolves to the running binary (survives version upgrades). */
52
+ export function runtimePaths(nodePath = process.execPath, script = process.argv[1] ?? "", pathEnv = process.env.PATH ?? "") {
53
+ const self = real(nodePath) ?? nodePath;
54
+ const onPath = pathEnv.split(delimiter).map((dir) => dir && join(dir, "node")).find((p) => p && real(p) === self);
55
+ return { node: onPath || (/fnm_multishells|\/tmp\//.test(nodePath) ? self : nodePath), js: real(script) ?? script };
46
56
  }
47
57
  export function isManaged(cmd) {
48
58
  return typeof cmd === "string" && cmd.includes(MARKER);
@@ -191,7 +201,7 @@ export function parseAgents(value) {
191
201
  export function installHooks(opts = {}) {
192
202
  const out = [];
193
203
  const timeout = opts.timeoutSec ?? 10;
194
- for (const t of [...targets(opts.home), ...ompTarget(opts.home)]) {
204
+ for (const t of [...targets(opts.home), ...pluginTargets(opts.home)]) {
195
205
  const explicit = opts.agents?.includes(t.agent) ?? false;
196
206
  if (opts.agents && !explicit)
197
207
  continue;
@@ -199,6 +209,10 @@ export function installHooks(opts = {}) {
199
209
  out.push({ agent: t.agent, action: "skipped (not installed)", file: tildify(t.file), backup: "" });
200
210
  continue;
201
211
  }
212
+ if (t.agent === "opencode") {
213
+ out.push({ agent: "opencode", ...opencodeOps({ home: opts.home, uninstall: opts.uninstall, dryRun: opts.dryRun, argv: launcher() }) });
214
+ continue;
215
+ }
202
216
  if (t.agent === "omp") {
203
217
  const { node, js } = runtimePaths();
204
218
  out.push({ agent: "omp", ...ompOps({ home: opts.home, uninstall: opts.uninstall, dryRun: opts.dryRun, node, script: js }) });
@@ -227,14 +241,19 @@ export function installHooks(opts = {}) {
227
241
  }
228
242
  return out;
229
243
  }
230
- function ompTarget(home = homedir()) {
231
- const { file } = ompPaths(home);
232
- return [{ agent: "omp", dir: join(home, ".omp"), file }];
244
+ function pluginTargets(home = homedir()) {
245
+ const oc = opencodePaths(home);
246
+ return [
247
+ { agent: "opencode", dir: oc.root, file: oc.file },
248
+ { agent: "omp", dir: join(home, ".omp"), file: ompPaths(home).file },
249
+ ];
233
250
  }
234
251
  export function hookStatus(home = homedir()) {
235
- return [...targets(home), ...ompTarget(home)].map((t) => {
252
+ return [...targets(home), ...pluginTargets(home)].map((t) => {
236
253
  if (!existsSync(t.dir))
237
254
  return { agent: t.agent, installed: false, file: tildify(t.file), note: "agent not installed" };
255
+ if (t.agent === "opencode")
256
+ return { agent: "opencode", installed: opencodeInstalled(home), file: tildify(t.file), note: "ok" };
238
257
  if (t.agent === "omp")
239
258
  return { agent: "omp", installed: ompInstalled(home), file: tildify(t.file), note: "ok" };
240
259
  let cur = {};
@@ -0,0 +1,135 @@
1
+ import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
2
+ import { homedir } from "node:os";
3
+ import { join } from "node:path";
4
+ import { AxiError } from "./errors.js";
5
+ import { tildify } from "./format.js";
6
+ /** Text every managed OpenCode plugin carries; used to recognize our file. */
7
+ export const OPENCODE_MARKER = "but-axi managed opencode plugin";
8
+ export function opencodePaths(home = homedir()) {
9
+ const root = join(home, ".config", "opencode");
10
+ const dir = join(root, "plugins");
11
+ return { root, dir, file: join(dir, "but-axi.js") };
12
+ }
13
+ /**
14
+ * One default export both OpenCode generations load: OpenCode 2 validates `id` and runs `setup(ctx)`,
15
+ * OpenCode 1 runs `server(input)` (same shape as axi-sdk-js's managed plugin).
16
+ */
17
+ export function renderOpencodePlugin(argv, timeoutMs = 5_000) {
18
+ const [cmd, ...pre] = argv;
19
+ return `// ${OPENCODE_MARKER} (marker: # but-axi hook session-start)
20
+ // Injects the but-axi home view (GitButler workspace dashboard) into OpenCode sessions.
21
+ // Remove with \`but-axi setup hooks --uninstall --agents opencode\`.
22
+ import { spawn } from "node:child_process";
23
+
24
+ const COMMAND = ${JSON.stringify(cmd)};
25
+ const ARGS = ${JSON.stringify([...pre, "hook", "session-start", "--agent", "opencode"])};
26
+ const TIMEOUT_MS = ${timeoutMs};
27
+ const MAX_BYTES = 64 * 1024;
28
+
29
+ export function runDashboard(cwd, timeoutMs = TIMEOUT_MS) {
30
+ return new Promise((resolve) => {
31
+ let out = "";
32
+ let done = false;
33
+ const finish = (v) => {
34
+ if (done) return;
35
+ done = true;
36
+ clearTimeout(timer);
37
+ resolve(v);
38
+ };
39
+ let child;
40
+ try {
41
+ child = spawn(COMMAND, ARGS, { cwd, stdio: ["pipe", "pipe", "ignore"], env: { ...process.env, NO_COLOR: "1" } });
42
+ } catch {
43
+ resolve("");
44
+ return;
45
+ }
46
+ const timer = setTimeout(() => {
47
+ try { child.kill("SIGKILL"); } catch {}
48
+ finish("");
49
+ }, timeoutMs);
50
+ child.stdout?.on("data", (c) => { if (out.length < MAX_BYTES) out += c.toString("utf8"); });
51
+ child.once("error", () => finish(""));
52
+ child.once("close", (code) => finish(code === 0 ? out.slice(0, MAX_BYTES).trim() : ""));
53
+ child.stdin?.on("error", () => {});
54
+ child.stdin?.end(JSON.stringify({ cwd }), "utf8");
55
+ });
56
+ }
57
+
58
+ function contextFor(directory) {
59
+ const cache = new Map();
60
+ return async (sessionID) => {
61
+ const key = sessionID ?? "__global__";
62
+ if (!cache.has(key)) cache.set(key, await runDashboard(typeof directory === "string" && directory ? directory : process.cwd()));
63
+ const text = cache.get(key);
64
+ return text ? "GitButler workspace (but-axi dashboard at session start; run \`but-axi\` for live state):\\n" + text : "";
65
+ };
66
+ }
67
+
68
+ export default {
69
+ id: "but-axi",
70
+ async setup(ctx) {
71
+ const context = contextFor(ctx?.location?.directory);
72
+ await ctx.session.hook("context", async (event) => {
73
+ const text = await context(event.sessionID);
74
+ if (text) event.system.push({ type: "text", text });
75
+ });
76
+ },
77
+ async server({ directory }) {
78
+ const context = contextFor(directory);
79
+ return {
80
+ "experimental.chat.system.transform": async (input, output) => {
81
+ const text = await context(input.sessionID);
82
+ if (text) output.system.push(text);
83
+ },
84
+ };
85
+ },
86
+ };
87
+ `;
88
+ }
89
+ export function opencodeInstalled(home = homedir()) {
90
+ const { file } = opencodePaths(home);
91
+ return existsSync(file) && readFileSync(file, "utf8").includes(OPENCODE_MARKER);
92
+ }
93
+ /** Backups go next to (not inside) the auto-loaded plugins dir so OpenCode never loads them. */
94
+ function backupPath(root) {
95
+ const d = new Date();
96
+ const p = (n) => String(n).padStart(2, "0");
97
+ const base = join(root, `but-axi.js.bak-but-axi-${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`);
98
+ let out = base;
99
+ for (let i = 1; existsSync(out); i++)
100
+ out = `${base}-${i}`;
101
+ return out;
102
+ }
103
+ export function opencodeOps(opts) {
104
+ const { root, dir, file } = opencodePaths(opts.home);
105
+ const shown = tildify(file);
106
+ const exists = existsSync(file);
107
+ const current = exists ? readFileSync(file, "utf8") : "";
108
+ if (exists && !current.includes(OPENCODE_MARKER)) {
109
+ throw new AxiError(`refusing to touch ${shown}: it exists and is not managed by but-axi`, "FOREIGN_FILE", ["Move or rename that file, then rerun `but-axi setup hooks --agents opencode`"]);
110
+ }
111
+ if (opts.uninstall) {
112
+ if (!exists)
113
+ return { action: "not installed (no change)", file: shown, backup: "" };
114
+ if (opts.dryRun)
115
+ return { action: "would remove", file: shown, backup: "" };
116
+ const bak = backupPath(root);
117
+ copyFileSync(file, bak);
118
+ rmSync(file);
119
+ return { action: "removed", file: shown, backup: tildify(bak) };
120
+ }
121
+ const next = renderOpencodePlugin(opts.argv);
122
+ if (exists && current === next)
123
+ return { action: "already installed (no change)", file: shown, backup: "" };
124
+ if (opts.dryRun)
125
+ return { action: exists ? "would update" : "would install", file: shown, backup: "" };
126
+ let backup = "(new file)";
127
+ if (exists) {
128
+ const bak = backupPath(root);
129
+ copyFileSync(file, bak);
130
+ backup = tildify(bak);
131
+ }
132
+ mkdirSync(dir, { recursive: true });
133
+ writeFileSync(file, next);
134
+ return { action: exists ? "updated" : "installed", file: shown, backup };
135
+ }
package/dist/src/skill.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /** Discovery stub only. Command guidance lives in `but-axi --help`, which does not go stale. */
2
- export const SKILL_DESCRIPTION = "Drive GitButler version control through the but-axi CLI — workspace status, diffs, commits, branches, push, undo/redo, and oplog. Use whenever a task touches GitButler or would otherwise use git write commands in a GitButler repo: inspecting stacks and uncommitted changes, committing all or selected hunks/files, creating branches, pushing, undo/redo, or reading the oplog. Prefer but-axi over raw `but` for covered operations and over `git add/commit/push/checkout/merge/rebase`.";
2
+ export const SKILL_DESCRIPTION = "Drive GitButler version control through the but-axi CLI — workspace status, diffs, commits, branches, push, undo/redo, oplog, and read-only log/blame history. Use whenever a task touches GitButler or would otherwise use git write commands in a GitButler repo: inspecting stacks, worktrees and uncommitted changes, reading commit history or blame, committing all or selected hunks/files, creating branches, pushing, undo/redo, or reading the oplog. Prefer but-axi over raw `but` for covered operations and over `git add/commit/push/checkout/merge/rebase`.";
3
3
  export const SKILL_AUTHOR = "Ed Heltzel (edheltzel)";
4
4
  export const HERMES_TAGS = ["gitbutler", "git", "version-control", "commits", "branches"];
5
5
  export const HERMES_CATEGORY = "devops";
@@ -9,7 +9,7 @@ const BODY = `# but-axi
9
9
 
10
10
  Agent ergonomic wrapper around the GitButler \`but\` CLI. Prefer this over raw \`but\` and over git write commands for GitButler workspaces.
11
11
 
12
- Use but-axi whenever a task touches GitButler: workspace status, diffs, commits, branches, push, undo/redo, oplog, or anything that would otherwise use \`git add\` / \`git commit\` / \`git push\` / \`git checkout\` / \`git merge\` / \`git rebase\` in a GitButler repo.
12
+ Use but-axi whenever a task touches GitButler: workspace status, diffs, commits, branches, push, undo/redo, oplog, log/blame history, or anything that would otherwise use \`git add\` / \`git commit\` / \`git push\` / \`git checkout\` / \`git merge\` / \`git rebase\` in a GitButler repo.
13
13
 
14
14
  ## Current guidance lives in the CLI
15
15
 
@@ -69,9 +69,17 @@ export function summarize(raw, cwd, root) {
69
69
  }
70
70
  }
71
71
  const conflicts = commits.filter((c) => c.conflicted).length + uncommitted.filter((c) => c.conflicted).length;
72
+ const worktrees = (raw.worktrees ?? []).map((w) => ({
73
+ id: w.cliId ?? "",
74
+ name: w.name,
75
+ commits: (w.branches ?? []).reduce((n, b) => n + (b.commits ?? []).length, 0),
76
+ uncommitted: (w.uncommittedChanges ?? []).length,
77
+ behind: w.base?.behind ?? 0,
78
+ }));
72
79
  return {
73
80
  cwd,
74
81
  root,
82
+ worktrees,
75
83
  uncommitted,
76
84
  branches,
77
85
  commits,
@@ -95,6 +103,7 @@ export function aggregate(ws) {
95
103
  `${plural(ws.commits.length, "commit")}${ws.commits.length ? ` (${unpushed} on unpushed branches)` : ""}`,
96
104
  `${ws.uncommitted.length} uncommitted`,
97
105
  plural(ws.conflicts, "conflict"),
106
+ ...(ws.worktrees.length ? [plural(ws.worktrees.length, "worktree")] : []),
98
107
  ].join("; ");
99
108
  }
100
109
  /** Shared workspace block used by home, status and every mutation result. */
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "but-axi",
3
- "version": "0.1.1",
4
- "description": "AXI-compliant GitButler `but` CLI wrapper \u2014 TOON output, counts, truncation, help[] next steps, combined mutations, session hooks",
3
+ "version": "0.2.0",
4
+ "description": "AXI-compliant GitButler `but` CLI wrapper — TOON output, counts, truncation, help[] next steps, combined mutations, session hooks",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "but-axi": "./dist/bin/but-axi.js"
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: but-axi
3
- description: "Drive GitButler version control through the but-axi CLI — workspace status, diffs, commits, branches, push, undo/redo, and oplog. Use whenever a task touches GitButler or would otherwise use git write commands in a GitButler repo: inspecting stacks and uncommitted changes, committing all or selected hunks/files, creating branches, pushing, undo/redo, or reading the oplog. Prefer but-axi over raw `but` for covered operations and over `git add/commit/push/checkout/merge/rebase`."
3
+ description: "Drive GitButler version control through the but-axi CLI — workspace status, diffs, commits, branches, push, undo/redo, oplog, and read-only log/blame history. Use whenever a task touches GitButler or would otherwise use git write commands in a GitButler repo: inspecting stacks, worktrees and uncommitted changes, reading commit history or blame, committing all or selected hunks/files, creating branches, pushing, undo/redo, or reading the oplog. Prefer but-axi over raw `but` for covered operations and over `git add/commit/push/checkout/merge/rebase`."
4
4
  user-invocable: false
5
5
  author: Ed Heltzel (edheltzel)
6
6
  metadata:
@@ -13,7 +13,7 @@ metadata:
13
13
 
14
14
  Agent ergonomic wrapper around the GitButler `but` CLI. Prefer this over raw `but` and over git write commands for GitButler workspaces.
15
15
 
16
- Use but-axi whenever a task touches GitButler: workspace status, diffs, commits, branches, push, undo/redo, oplog, or anything that would otherwise use `git add` / `git commit` / `git push` / `git checkout` / `git merge` / `git rebase` in a GitButler repo.
16
+ Use but-axi whenever a task touches GitButler: workspace status, diffs, commits, branches, push, undo/redo, oplog, log/blame history, or anything that would otherwise use `git add` / `git commit` / `git push` / `git checkout` / `git merge` / `git rebase` in a GitButler repo.
17
17
 
18
18
  ## Current guidance lives in the CLI
19
19