@bakers-build/addon-herdr 0.6.1-next.5 → 0.6.1-next.7

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.
@@ -1,3 +1,4 @@
1
+ import type { OpenLayout } from './open-layout.js';
1
2
  import type { RootGitExec } from './root-anchor.js';
2
3
  export interface PaneSpec {
3
4
  direction: 'right' | 'down';
@@ -26,18 +27,11 @@ export interface HerdrExecutorOptions {
26
27
  /** Legacy fallback for input.command. */
27
28
  command?: string;
28
29
  /**
29
- * Lifecycle-hook commands, keyed like `config.hooks` (after_create,
30
- * before_run, after_run, after_done, on_freeze, on_resume). The factory copies `config.hooks` here
31
- * so the executor — the single best-effort catch point — can run them.
30
+ * Startup layout for a fresh worktree's initial pane, applied by
31
+ * `openWorkspace` (BB-139). Unset → `DEFAULT_OPEN_LAYOUT`
32
+ * (`bakers ui --ticket <ID>`, BB-234); `{}` → the bare empty tab.
32
33
  */
33
- hooks?: {
34
- after_create?: string;
35
- before_run?: string;
36
- after_run?: string;
37
- after_done?: string;
38
- on_freeze?: string;
39
- on_resume?: string;
40
- };
34
+ open?: OpenLayout;
41
35
  /**
42
36
  * The parent repo root (main clone) — herdr `--cwd` target for reattaching a
43
37
  * closed worktree. herdr rejects a `worktree open` whose --cwd is a linked
package/dist/src/fs.d.ts CHANGED
@@ -1,18 +1,5 @@
1
- /**
2
- * Recursively re-add the owner-write bit to a directory tree.
3
- *
4
- * A bakers.build worktree is a Drupal install, and Drupal hardens `web/sites/default`
5
- * to `0555` and `settings.php` / `files/.htaccess` to `0444`. A directory
6
- * without its write bit cannot have its entries unlinked, so removing the
7
- * worktree (`git worktree remove --force` / `rm -rf`, however herdr does it)
8
- * gets EACCES. Restoring `u+w` on every dir/file first is what makes removal
9
- * succeed — this is not an ownership problem, only the permission bits.
10
- *
11
- * Best-effort per entry: a single un-chmod-able entry (already gone, foreign
12
- * owner) must not abort the walk. Symlinks are never followed — chmod would
13
- * touch the link target, which may live outside the tree.
14
- */
15
- export declare function restoreWritable(path: string): void;
1
+ import { restoreWritable } from '@bakers-build/addon-workspace-git';
2
+ export { restoreWritable };
16
3
  /**
17
4
  * Remove a directory tree that may be hardened read-only by Drupal:
18
5
  * {@link restoreWritable} first, then `rm -rf`. Used where the conductor owns
package/dist/src/fs.js CHANGED
@@ -1,51 +1,8 @@
1
- import { chmodSync, lstatSync, readdirSync, rmSync } from 'node:fs';
2
- import { join } from 'node:path';
3
- /**
4
- * Recursively re-add the owner-write bit to a directory tree.
5
- *
6
- * A bakers.build worktree is a Drupal install, and Drupal hardens `web/sites/default`
7
- * to `0555` and `settings.php` / `files/.htaccess` to `0444`. A directory
8
- * without its write bit cannot have its entries unlinked, so removing the
9
- * worktree (`git worktree remove --force` / `rm -rf`, however herdr does it)
10
- * gets EACCES. Restoring `u+w` on every dir/file first is what makes removal
11
- * succeed — this is not an ownership problem, only the permission bits.
12
- *
13
- * Best-effort per entry: a single un-chmod-able entry (already gone, foreign
14
- * owner) must not abort the walk. Symlinks are never followed — chmod would
15
- * touch the link target, which may live outside the tree.
16
- */
17
- export function restoreWritable(path) {
18
- let stat;
19
- try {
20
- stat = lstatSync(path);
21
- }
22
- catch {
23
- return; // gone / inaccessible — nothing to restore
24
- }
25
- if (stat.isSymbolicLink()) {
26
- return; // don't follow: the target lives elsewhere
27
- }
28
- try {
29
- // Add owner-write, preserving every other bit (read/execute stay intact so
30
- // a directory remains traversable and readable for the recursion below).
31
- chmodSync(path, stat.mode | 0o200);
32
- }
33
- catch {
34
- // best-effort: one un-chmod-able entry must not abort the walk
35
- }
36
- if (stat.isDirectory()) {
37
- let entries;
38
- try {
39
- entries = readdirSync(path);
40
- }
41
- catch {
42
- return;
43
- }
44
- for (const entry of entries) {
45
- restoreWritable(join(path, entry));
46
- }
47
- }
48
- }
1
+ import { rmSync } from 'node:fs';
2
+ import { restoreWritable } from '@bakers-build/addon-workspace-git';
3
+ // The write-bit restore lives with the shared git teardown; re-exported here
4
+ // for herdr's own callers and `@bakers-build/addon-herdr/shared`.
5
+ export { restoreWritable };
49
6
  /**
50
7
  * Remove a directory tree that may be hardened read-only by Drupal:
51
8
  * {@link restoreWritable} first, then `rm -rf`. Used where the conductor owns
@@ -1,59 +1,20 @@
1
- import type { BbExecutor, ExecutorCapabilities, ExecutorPlugin, HookContext, HookName, HookResult, SpawnedSession, SpawnRunInput, WorktreeTeardown } from '@bakers-build/conductor/contract';
1
+ import type { BbExecutor, ExecutorCapabilities, ExecutorPlugin, OpenWorkspaceContext, SpawnedSession, SpawnRunInput } from '@bakers-build/conductor/contract';
2
2
  import type { ConductorLogger } from '@bakers-build/core';
3
3
  import { type HerdrExecutorOptions } from './config.js';
4
4
  import { type HerdrExec } from './pane-layout.js';
5
- export type { AgentLaunchHost, AgentLaunchHostProvider, HostedAgent, } from './agent-host.js';
6
- export { herdrAgentHost } from './agents.js';
5
+ export { DEFAULT_OPEN_LAYOUT, type OpenLayout } from './open-layout.js';
7
6
  export type { HerdrExec } from './pane-layout.js';
8
- export { envArgs, findTabIdByLabel, parsePaneInfo, parsePanesInTab, parseTabCreate, } from './panes.js';
9
- export { herdrProcessHost } from './process-host.js';
10
- export { HerdrWorkspace, type HerdrWorkspaceOptions, herdrWorkspace, type OpenLayout, } from './workspace.js';
7
+ export { envArgs } from './panes.js';
8
+ export { HerdrWorkspace, type HerdrWorkspaceOptions, herdrWorkspace, } from './workspace.js';
11
9
  export { parseWorkspaceList, type WorkspaceEntry, } from './workspace-list.js';
12
- /** Runs a lifecycle-hook shell command in a cwd; rejects on non-zero exit. */
13
- export type ShellRunner = (command: string, cwd: string, env?: Record<string, string>) => Promise<void>;
14
- /** Runs `git <args>` in a cwd; resolves with stdout, rejects on non-zero exit. */
15
- export type GitRunner = (args: string[], cwd: string) => Promise<string>;
16
10
  export declare class HerdrExecutor implements BbExecutor {
17
11
  private readonly options;
18
12
  private readonly execHerdr;
19
13
  private readonly logger;
20
- private readonly runShell;
21
- private readonly runGit;
22
14
  readonly id = "herdr";
23
- constructor(options: HerdrExecutorOptions, execHerdr?: HerdrExec, logger?: ConductorLogger, runShell?: ShellRunner, runGit?: GitRunner);
15
+ constructor(options: HerdrExecutorOptions, execHerdr?: HerdrExec, logger?: ConductorLogger);
24
16
  capabilities(): ExecutorCapabilities;
25
- /**
26
- * Run the lifecycle hook `name` best-effort — the single catch point for all
27
- * lifecycle hooks (see {@link BbExecutor.runHook}). No configured command →
28
- * silent no-op. A failing command → log loudly (hook + worktree + ticket +
29
- * err) and return. NEVER throws, so a hook failure can't abort dispatch or
30
- * wedge a run.
31
- *
32
- * BB-237: it also RETURNS what happened ({@link HookResult}). Not throwing
33
- * kept a hook from wedging a run, but swallowing the outcome entirely left the
34
- * caller unable to tell a provisioned worktree from a broken one — so an agent
35
- * was dispatched into a worktree whose bootstrap had aborted, with nothing but
36
- * a log line (which, on a TTY, went nowhere) to say so.
37
- */
38
- runHook(name: HookName, cwd: string, ctx: HookContext, env?: Record<string, string>): Promise<HookResult>;
39
- /**
40
- * List worktrees, ALWAYS anchored to the configured parent repo root
41
- * (BB-211). `herdr worktree list` is machine-global, but run WITHOUT
42
- * `--cwd` it resolves herdr's own ambient (previously selected / persisted /
43
- * process / shell / daemon) repository context. When a preceding
44
- * `bakers-cleanup-*` integration test selected then deleted a
45
- * `/tmp/bakers-cleanup-*` repo, that stale context survives and the unanchored
46
- * list exits (`cannot change to '/tmp/bakers-cleanup-…'`), aborting dispatch.
47
- * Anchoring every list with `--cwd this.options.root` makes listing
48
- * independent of that ambient context. This is the SINGLE choke point for
49
- * all executor `worktree list` call paths — the sibling
50
- * {@link HerdrWorkspace.ensure} anchors identically. The `--cwd` is only
51
- * omitted when no root is configured (rootless test callers).
52
- *
53
- * On a herdr failure it throws an error naming the explicit configured root
54
- * and the operation (AC-9) instead of surfacing herdr's raw stale-context
55
- * message, so a future context failure is diagnosable.
56
- */
17
+ /** List worktrees anchored to the parent repo root (see {@link listWorktrees}). */
57
18
  private listWorktrees;
58
19
  /**
59
20
  * Find the worktree entry (path + open_workspace_id) for a branch via
@@ -73,126 +34,15 @@ export declare class HerdrExecutor implements BbExecutor {
73
34
  * worktree is not listed as open.
74
35
  */
75
36
  private findOpenWorkspace;
76
- /** Parent repo root for git worktree admin ops (falls back to `fallback`). */
77
- private gitRoot;
78
- /**
79
- * Sweep orphaned `.git/worktrees/<name>` admin entries at the parent repo
80
- * root — the ones whose on-disk dir has vanished (BB-141: they show up as
81
- * `prunable` in `git worktree list`). Best-effort: a prune failure must never
82
- * fail teardown.
83
- */
84
- private pruneWorktrees;
85
- /**
86
- * Remove an on-disk worktree GIT-AWARELY (BB-141 RC-1). The old fallback
87
- * raw-`rm`'d the directory and left the parent repo's `.git/worktrees/<name>`
88
- * admin entry behind → a `prunable` orphan. This:
89
- * 1. restores owner-write (Drupal hardens web/sites/default 0555 +
90
- * settings.php 0444 — chmod-restorable by the owning user, no sudo);
91
- * 2. `git worktree remove --force <path>` from the PARENT repo root, which
92
- * unlinks the directory AND drops the `.git/worktrees/<name>` entry —
93
- * but ONLY when the path really is a registered worktree (BB-293):
94
- * against an unregistered path git exits 128 and the shared exec helper
95
- * logs `ERROR: exec failed` for a condition this code expects and
96
- * handles. The guard lives here rather than at the caller because this
97
- * method has a second call site (the path resolved via
98
- * {@link findGitWorktree});
99
- * 3. guarantees the directory is gone (a raw force-remove) in case git
100
- * refused or was skipped — a no-op if git already removed it;
101
- * 4. prunes the repo so any now-stale admin entry is swept.
102
- *
103
- * Returns whether the directory is gone afterwards. A reclaim that cannot
104
- * remove it REPORTS instead of throwing (BB-293, spec D5): the raw EACCES
105
- * used to propagate all the way out of {@link removeWorktree} and reach the
106
- * reaper as an opaque exception.
107
- */
108
- private gitAwareRemove;
109
- /**
110
- * When herdr has lost track of a worktree and its `worktreePath` was never
111
- * persisted, the PARENT repo's `git worktree list` still knows it (BB-141
112
- * RC-2 — the ~28 never-touched leftovers). Resolve the lost worktree's on-disk
113
- * path there, preferring an exact `worktreePath` match, then a branch match;
114
- * never the main worktree. Returns null when nothing matches. Best-effort: a
115
- * git failure resolves to null.
116
- *
117
- * `cwd` is only where git is RUN. The main worktree is excluded by git's own
118
- * porcelain ordering (it is always the first record) rather than by comparing
119
- * against `cwd`, because the two coincide only when a parent root is
120
- * configured. Without one the probe falls back to running git inside the
121
- * worktree itself, and a `path !== cwd` filter then dropped the very entry
122
- * being asked about — so `registered: true` was unreachable for a rootless
123
- * executor (BB-293 review, finding 1). The configured root is excluded too,
124
- * belt and braces, so a caller that anchors elsewhere still never resolves the
125
- * main checkout as a ticket worktree.
126
- */
127
- private findGitWorktree;
128
- /**
129
- * Ask — passively — whether this worktree still exists, in BOTH dimensions
130
- * that can come apart (BB-293): git's registration, and the directory on
131
- * disk. The reported failure was exactly a case where they disagreed — the
132
- * directory was there, the registration was not — so a single-dimension
133
- * check cannot decide what to do.
134
- *
135
- * Passive by construction: it writes nothing, calls no herdr, and NEVER
136
- * throws. A git failure yields `registered: false`, degrading the verdict to
137
- * the on-disk answer rather than failing the teardown.
138
- *
139
- * The persisted `worktreePath` is the stable key and wins when given;
140
- * `registered` then describes THAT path, never a branch match pointing
141
- * somewhere else (the checked-out branch is mutable — BB-114).
142
- *
143
- * git is run at the configured parent root when there is one, else inside the
144
- * worktree itself — `git worktree list` enumerates the whole repo from any of
145
- * its worktrees, so the rootless answer is the same list.
146
- */
147
- private probeWorktree;
148
- /**
149
- * BB-166 focus guard. herdr's `worktree remove` deletes the ticket
150
- * worktree's on-disk directory; if that workspace is the CURRENTLY FOCUSED
151
- * one, the interactive client is left in a now-deleted `cwd` and herdr spawns
152
- * a stray empty workspace for the dead path. So before the remove, if the
153
- * target workspace is focused, switch focus to the main-checkout (non-linked)
154
- * workspace of the SAME repo. A background reap of a non-focused worktree
155
- * (or one herdr no longer lists) focuses nothing.
156
- *
157
- * Returns whether it is SAFE to proceed with the remove: `false` when a
158
- * required focus switch cannot be resolved or verified — the caller then
159
- * aborts (returns `false` → `cleaned_up=0`) so the reaper retries later,
160
- * rather than deleting the focused path out from under the user.
161
- */
162
- private ensureFocusSafeToRemove;
163
37
  /**
164
- * Tear down a ticket's entire worktree (git worktree + hosted workspace).
165
- * `herdr worktree remove` is keyed by an open workspace id, so resolve the
166
- * worktree first — by its stable `worktreePath`, falling back to `branch`
167
- * (see {@link resolveWorktreeEntry}): if its workspace is already open use
168
- * that id; otherwise open the on-disk worktree to obtain one (mirrors
169
- * startRun's open-if-needed).
170
- *
171
- * `herdr worktree list` is machine-global — it enumerates every repo's
172
- * worktrees on the host, most of which are not ours. So a no-match does NOT
173
- * mean "error"; it means herdr no longer tracks this ticket's worktree. When
174
- * herdr has lost track, teardown is resolved off git itself (never a foreign
175
- * worktree), git-awarely so no `.git/worktrees/<name>` metadata is orphaned
176
- * (BB-141 RC-1). Since BB-293 that resolution starts by ASKING — a passive
177
- * {@link probeWorktree} reads both dimensions of existence and the four cases
178
- * branch explicitly:
179
- * - neither registered nor on disk → nothing to do at all;
180
- * - registered but gone from disk → sweep the prunable admin entry;
181
- * - on disk but not registered → reclaim the directory, WITHOUT asking git
182
- * to remove a worktree it does not know (the bogus `ERROR: exec failed`);
183
- * - both → reclaim it git-awarely, `git worktree remove` included.
184
- * A path that resolves in NEITHER dimension is not "absent" — it is
185
- * unresolved, and still reported `unverified` (BB-141 RC-2).
186
- *
187
- * Reports what the teardown DID (BB-293): `removed` when the worktree is
188
- * gone because this host removed it (or reclaimed an on-disk orphan, or swept
189
- * the prunable admin entry it left behind), `already_absent` when a RESOLVED
190
- * worktree existed in neither dimension, and `unverified` ONLY when nothing
191
- * was resolvable or the directory could not be reclaimed — the reaper then
192
- * leaves the ticket on its work list for a later retry instead of falsely
193
- * flagging it cleaned (BB-141 RC-2).
38
+ * Lay out a freshly created worktree's herdr workspace with the `open`
39
+ * layout (BB-139/BB-234) — after `after_create`, which builds what the layout
40
+ * command may name (BB-237). The worktree may come from any workspace: its
41
+ * herdr workspace is found by path (falling back to `branch`), or opened from
42
+ * the parent repo root when none is open yet. Best-effort: nothing resolvable
43
+ * is a silent no-op, a failure is logged and swallowed.
194
44
  */
195
- removeWorktree(branch: string, worktreePath?: string): Promise<WorktreeTeardown>;
45
+ openWorkspace(path: string, ctx: OpenWorkspaceContext): Promise<void>;
196
46
  startRun(input: SpawnRunInput): Promise<SpawnedSession>;
197
47
  /** Best-effort cleanup: close only the just-created tab. Swallows errors. */
198
48
  private rollback;
@@ -209,8 +59,7 @@ export declare class HerdrExecutor implements BbExecutor {
209
59
  * tab and any non-run tab in the same workspace are left untouched, and a
210
60
  * missing match is a quiet no-op. Best-effort: a failing close is swallowed.
211
61
  * No `/exit`/C-c and no `(done)` rename — the matched tab simply goes away.
212
- * The branch worktree is untouched (that is the reap/{@link removeWorktree}
213
- * lifecycle).
62
+ * The branch worktree is untouched (that is `HerdrWorkspace.remove`).
214
63
  */
215
64
  cleanupRun(branch: string, runId: number): Promise<void>;
216
65
  private commandFor;