@bakers-build/addon-herdr 0.6.1-next.6 → 0.6.1-next.8

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