@bakers-build/addon-herdr 0.0.0-stage → 0.1.0-next.38

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @bakers-build/addon-herdr
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+bakers.build herdr integration: spawn executor + per-ticket worktree workspace.
+
+Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://git.key-tec.de/bakers-build/bakers-build (bakers-cli/).

package/dist/src/agent-host.d.ts

@@ -0,0 +1,45 @@
+/** A hosted agent as reported by the host. `id` is the host-owned stable handle
+ *  (survives a TUI restart); `group` is the opaque grouping key it was launched
+ *  under; `label` is a human tag for the list. */
+export interface HostedAgent {
+    id: string;
+    group: string;
+    label: string;
+}
+/**
+ * The INTENT-level agent host herdr provides. The caller says "launch an agent
+ * in this group", "show that agent", "list this group" — it never names panes,
+ * tabs, splits or zoom. The host (herdr) owns the whole layout policy. `group`
+ * is OPAQUE (bakers passes the project slug). `command` is the resolved shell
+ * command the agent runs (the renderer's prompt is turned into a command by the
+ * `bakers ui` entry before it reaches here — herdr stays agent-binary-agnostic).
+ */
+export interface AgentLaunchHost {
+    /**
+     * Start an agent and return its stable handle. The host decides where the
+     * session is placed and shows it; the caller only supplies intent + a group.
+     */
+    launch(opts: {
+        group: string;
+        cwd: string;
+        command: string;
+        env?: Record<string, string | undefined> | undefined;
+        label?: string | undefined;
+    }): Promise<HostedAgent>;
+    /** The live agents of a group — the source of truth for the list, rebuilt
+     *  from the host on demand so sessions survive a TUI restart. */
+    list(group: string): Promise<HostedAgent[]>;
+    /** Bring one agent to the foreground (the host zooms/switches as it sees fit). */
+    focus(id: string): Promise<void>;
+    /** Stop showing a group's agents and return focus to the caller. Durable —
+     *  the agents keep running; this never terminates them. */
+    hide(group: string): Promise<void>;
+    /** Terminate one agent for good. */
+    kill(id: string): Promise<void>;
+    /** Send literal text to an agent's input. */
+    sendText(id: string, text: string): Promise<void>;
+}
+/** A workspace (or other plugin) that can host agents at the intent level. */
+export interface AgentLaunchHostProvider {
+    agentHost: AgentLaunchHost;
+}

package/dist/src/agent-host.js

@@ -0,0 +1,9 @@
+// Herdr's own agent-host contract (BB-194 AC-3). It used to live in
+// `@bakers-build/core` as `AgentLaunchHost`/`HostedAgent`, but the agent-host seam is
+// a TUI/renderer concern, not a conductor-engine one — so core dropped it and
+// herdr types its impl LOCALLY. This interface imports nothing removed and
+// nothing from `@bakers-build/addon-bakers-ui`: the renderer owns its own
+// prompt-level `TuiAgentService`, and the conductor `bakers ui` entry adapts this
+// mechanism-level (`command`-based) host to it. Structurally compatible, no
+// cross-package type coupling.
+export {};

package/dist/src/agents.d.ts

@@ -0,0 +1,3 @@
+import type { AgentLaunchHost } from './agent-host.js';
+import type { HerdrExec } from './pane-layout.js';
+export declare function herdrAgentHost(execHerdr: HerdrExec): AgentLaunchHost;

package/dist/src/agents.js

@@ -0,0 +1,132 @@
+// Herdr-backed AgentLaunchHost (BB-190) — the INTENT-level agent host. It owns
+// the whole layout policy the bakers-ui plugin used to drive from the conductor:
+// one durable herdr tab per group, a new agent splits off a live pane, the shown
+// agent is zoomed, hiding un-zooms and returns to the caller. The caller speaks
+// only launch/list/focus/hide/kill/sendText — never panes, tabs or zoom.
+//
+// `group` is opaque (bakers passes a project slug); it maps to one tab labelled
+// `bakers-agents:<group>`, so a group's agents are listed + hidden together and
+// survive a TUI restart (rediscovered from the live tab).
+import { rmSync } from 'node:fs';
+import { writeLaunchScript } from './launch-script.js';
+import { AGENT_SHELL_ENV, envArgs, findTabIdByLabel, parsePaneInfo, parsePanesInTab, parseTabCreate, } from './panes.js';
+/** The single tab that holds a group's agent panes. */
+const groupTabLabel = (group) => `bakers-agents:${group}`;
+export function herdrAgentHost(execHerdr) {
+    // The caller's home tab, returned to on hide. Captured lazily on the first
+    // launch — that is when the caller is focused on its own tab (pressing `n`),
+    // and it keeps construction side-effect-free. Best-effort: a probe failure
+    // just leaves hide without a home to return to.
+    let homeTab = null;
+    const captureHome = async () => {
+        if (homeTab !== null)
+            return;
+        try {
+            homeTab = parsePaneInfo(await execHerdr(['pane', 'current'])).tabId;
+        }
+        catch {
+            // no home tab known; hide() becomes a no-op focus
+        }
+    };
+    // Cache each group's tab id to skip the `tab list` round-trip once known.
+    const tabByGroup = new Map();
+    const resolveTab = async (group) => {
+        const cached = tabByGroup.get(group);
+        if (cached)
+            return cached;
+        const found = findTabIdByLabel(await execHerdr(['tab', 'list']), groupTabLabel(group));
+        if (found)
+            tabByGroup.set(group, found);
+        return found;
+    };
+    return {
+        async launch({ group, cwd, command, env, label }) {
+            await captureHome();
+            // Every pane this host opens holds an agent, so all of them carry the
+            // agent-shell marker (BB-64) — this is the pane a `bakers ui` user actually
+            // attaches to. The caller's own env wins on a key clash; the marker is
+            // merged in, never substituted for it.
+            const e = { ...AGENT_SHELL_ENV, ...(env ?? {}) };
+            // Find the group's tab and split off a LIVE pane (newest-first; a stale
+            // pane — a previous agent died/was closed — is skipped). None survive, or
+            // no tab yet → create the group tab (its root pane is the agent).
+            let pane = null;
+            const tabId = await resolveTab(group);
+            if (tabId) {
+                const panes = parsePanesInTab(await execHerdr(['pane', 'list']), tabId);
+                for (const p of [...panes].reverse()) {
+                    try {
+                        pane = parsePaneInfo(await execHerdr([
+                            'pane',
+                            'split',
+                            p.paneId,
+                            '--direction',
+                            'right',
+                            '--no-focus',
+                            '--cwd',
+                            cwd,
+                            ...envArgs(e),
+                        ]));
+                        break;
+                    }
+                    catch {
+                        // stale pane — try the next
+                    }
+                }
+                if (!pane)
+                    tabByGroup.delete(group);
+            }
+            if (!pane) {
+                pane = parseTabCreate(await execHerdr([
+                    'tab',
+                    'create',
+                    '--cwd',
+                    cwd,
+                    '--no-focus',
+                    '--label',
+                    groupTabLabel(group),
+                    ...envArgs(e),
+                ]));
+                tabByGroup.set(group, pane.tabId);
+            }
+            const launch = writeLaunchScript(command);
+            // ponytail: on success the wrapper's started/exit markers stay in tmp
+            // (no secrets); a sweep is only worth it if they ever pile up.
+            await execHerdr(['pane', 'run', pane.paneId, launch.typedCommand]).catch((err) => {
+                rmSync(launch.dir, { recursive: true, force: true });
+                throw err;
+            });
+            const human = label ?? 'agent';
+            await execHerdr(['pane', 'rename', pane.paneId, human]).catch(() => { });
+            await execHerdr(['pane', 'zoom', pane.paneId, '--on']).catch(() => { });
+            return { id: pane.paneId, group, label: human };
+        },
+        async list(group) {
+            const tabId = await resolveTab(group);
+            if (!tabId)
+                return [];
+            return parsePanesInTab(await execHerdr(['pane', 'list']), tabId).map((p) => ({ id: p.paneId, group, label: p.label }));
+        },
+        async focus(id) {
+            await execHerdr(['pane', 'zoom', id, '--on']);
+        },
+        async hide(group) {
+            // Un-zoom the group's panes (so it reads as the tiled overview next time)
+            // and return focus to the caller's home tab. The agents keep running.
+            const tabId = await resolveTab(group);
+            if (tabId) {
+                for (const p of parsePanesInTab(await execHerdr(['pane', 'list']), tabId)) {
+                    await execHerdr(['pane', 'zoom', p.paneId, '--off']).catch(() => { });
+                }
+            }
+            if (homeTab)
+                await execHerdr(['tab', 'focus', homeTab]).catch(() => { });
+        },
+        async kill(id) {
+            await execHerdr(['pane', 'close', id]);
+        },
+        async sendText(id, text) {
+            await execHerdr(['pane', 'send-text', id, text]);
+        },
+    };
+}

package/dist/src/config.d.ts

@@ -0,0 +1,77 @@
+import type { RootGitExec } from './root-anchor.js';
+export interface PaneSpec {
+    direction: 'right' | 'down';
+    command: string;
+    focus?: boolean;
+}
+export interface StateConfig {
+    /**
+     * Tab label template. Must contain {identifier} — the conductor matches a
+     * run's tab by its ticket identifier (stop/state), so the identifier is the
+     * stable anchor in the visible name. Other vars: {title}, {titleSlug},
+     * {runUuid}, {repoName}, {workspacePath}.
+     */
+    tabLabel?: string;
+    workspaceLabel?: string;
+    /**
+     * Root-pane (panel) label template applied via `herdr pane rename` after the
+     * state tab is created (BB-374). Default `{title}`. Distinct from
+     * {@link tabLabel}: stop/state matching still anchors on the tab label.
+     */
+    panelLabel?: string;
+    /** Extra layout panes (diff/logs); NOT the agent command. */
+    panes?: PaneSpec[];
+}
+export interface HerdrExecutorOptions {
+    /** Legacy fallback for input.command. */
+    command?: string;
+    /**
+     * Lifecycle-hook commands, keyed like `config.hooks` (after_create,
+     * before_run, after_run, after_done, on_freeze, on_resume). The factory copies `config.hooks` here
+     * so the executor — the single best-effort catch point — can run them.
+     */
+    hooks?: {
+        after_create?: string;
+        before_run?: string;
+        after_run?: string;
+        after_done?: string;
+        on_freeze?: string;
+        on_resume?: string;
+    };
+    /**
+     * The parent repo root (main clone) — herdr `--cwd` target for reattaching a
+     * closed worktree. herdr rejects a `worktree open` whose --cwd is a linked
+     * worktree (`linked_worktree_source`): open/new must start from the parent
+     * workspace. When unset the factory derives it from the git common dir
+     * (BB-177), exactly like the sibling `herdrWorkspace` plugin; this override
+     * always wins.
+     */
+    root?: string;
+    /** Overrideable git exec for root derivation (tests). */
+    execGit?: RootGitExec;
+    default?: StateConfig;
+    states?: Record<string, StateConfig>;
+    /**
+     * Launch-watch windows. `startTimeoutMs` is how long startRun waits for the
+     * wrapper to write `started` (default 60s, so a slow interactive shell can
+     * finish rc). `timeoutMs` is the short window after `started` in which an
+     * immediate agent exit fails the launch (default 4000 ms). Tests inject
+     * shorter windows, including `timeoutMs: 0` to skip the exit wait.
+     */
+    launchWatch?: {
+        timeoutMs?: number;
+        startTimeoutMs?: number;
+        pollMs?: number;
+        sleep?: (ms: number) => Promise<void>;
+    };
+}
+export interface ResolvedConfig {
+    tabLabel: string;
+    workspaceLabel: string;
+    panelLabel: string;
+    panes: PaneSpec[];
+}
+export declare const BUILTIN_DEFAULTS: ResolvedConfig;
+export declare function resolveStateConfig(options: HerdrExecutorOptions, state: string): ResolvedConfig;
+export declare function renderTemplate(tpl: string, vars: Record<string, string>): string;
+export declare function assertTabLabelTemplate(tabLabel: string): void;

package/dist/src/config.js

@@ -0,0 +1,29 @@
+export const BUILTIN_DEFAULTS = {
+    tabLabel: '{identifier} · {titleSlug}',
+    workspaceLabel: '{repoName}',
+    panelLabel: '{title}',
+    panes: [],
+};
+export function resolveStateConfig(options, state) {
+    const base = options.default ?? {};
+    const stateCfg = options.states?.[state] ?? {};
+    return {
+        tabLabel: stateCfg.tabLabel ?? base.tabLabel ?? BUILTIN_DEFAULTS.tabLabel,
+        workspaceLabel: stateCfg.workspaceLabel ??
+            base.workspaceLabel ??
+            BUILTIN_DEFAULTS.workspaceLabel,
+        panelLabel: stateCfg.panelLabel ?? base.panelLabel ?? BUILTIN_DEFAULTS.panelLabel,
+        panes: stateCfg.panes ?? base.panes ?? BUILTIN_DEFAULTS.panes,
+    };
+}
+export function renderTemplate(tpl, vars) {
+    return tpl.replace(/\{(\w+)\}/g, (whole, key) => {
+        const value = vars[key];
+        return value === undefined ? whole : value;
+    });
+}
+export function assertTabLabelTemplate(tabLabel) {
+    if (!tabLabel.includes('{identifier}')) {
+        throw new Error(`herdr tabLabel must contain {identifier} for stop/state matching: ${tabLabel}`);
+    }
+}

package/dist/src/frozen-marker.d.ts

@@ -0,0 +1,8 @@
+import type { HookListener } from '@bakers-build/conductor/contract';
+/** The sidebar token; operators show it with `$bb_frozen` in a row. */
+export declare const FROZEN_TOKEN = "bb_frozen";
+/**
+ * Marks a frozen ticket's workspace in herdr's sidebar with display-only
+ * metadata. A rename is avoided on purpose: run teardown matches labels.
+ */
+export declare const herdrFrozenMarker: HookListener;

package/dist/src/frozen-marker.js

@@ -0,0 +1,26 @@
+import { exec } from '@bakers-build/core';
+import { parseWorkspaceList } from './workspace-list.js';
+/** The sidebar token; operators show it with `$bb_frozen` in a row. */
+export const FROZEN_TOKEN = 'bb_frozen';
+async function reportOnWorktree(ctx, token) {
+    const workspace = parseWorkspaceList(await exec('herdr', ['workspace', 'list'])).find((w) => w.checkoutPath === ctx.worktreePath);
+    if (!workspace)
+        return;
+    await exec('herdr', [
+        'workspace',
+        'report-metadata',
+        workspace.workspaceId,
+        '--source',
+        'bakers',
+        ...token,
+    ]);
+}
+/**
+ * Marks a frozen ticket's workspace in herdr's sidebar with display-only
+ * metadata. A rename is avoided on purpose: run teardown matches labels.
+ */
+export const herdrFrozenMarker = {
+    id: 'herdr-frozen-marker',
+    on_freeze: (ctx) => reportOnWorktree(ctx, ['--token', `${FROZEN_TOKEN}=frozen`]),
+    on_resume: (ctx) => reportOnWorktree(ctx, ['--clear-token', FROZEN_TOKEN]),
+};

package/dist/src/fs.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Recursively re-add the owner-write bit to a directory tree.
+ *
+ * A bakers.build worktree is a Drupal install, and Drupal hardens `web/sites/default`
+ * to `0555` and `settings.php` / `files/.htaccess` to `0444`. A directory
+ * without its write bit cannot have its entries unlinked, so removing the
+ * worktree (`git worktree remove --force` / `rm -rf`, however herdr does it)
+ * gets EACCES. Restoring `u+w` on every dir/file first is what makes removal
+ * succeed — this is not an ownership problem, only the permission bits.
+ *
+ * Best-effort per entry: a single un-chmod-able entry (already gone, foreign
+ * owner) must not abort the walk. Symlinks are never followed — chmod would
+ * touch the link target, which may live outside the tree.
+ */
+export declare function restoreWritable(path: string): void;
+/**
+ * Remove a directory tree that may be hardened read-only by Drupal:
+ * {@link restoreWritable} first, then `rm -rf`. Used where the conductor owns
+ * the unlink; when herdr performs the removal, call {@link restoreWritable}
+ * alone beforehand. A missing path is a no-op.
+ */
+export declare function forceRemoveDir(path: string): void;

package/dist/src/fs.js

@@ -0,0 +1,58 @@
+import { chmodSync, lstatSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Recursively re-add the owner-write bit to a directory tree.
+ *
+ * A bakers.build worktree is a Drupal install, and Drupal hardens `web/sites/default`
+ * to `0555` and `settings.php` / `files/.htaccess` to `0444`. A directory
+ * without its write bit cannot have its entries unlinked, so removing the
+ * worktree (`git worktree remove --force` / `rm -rf`, however herdr does it)
+ * gets EACCES. Restoring `u+w` on every dir/file first is what makes removal
+ * succeed — this is not an ownership problem, only the permission bits.
+ *
+ * Best-effort per entry: a single un-chmod-able entry (already gone, foreign
+ * owner) must not abort the walk. Symlinks are never followed — chmod would
+ * touch the link target, which may live outside the tree.
+ */
+export function restoreWritable(path) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch {
+        return; // gone / inaccessible — nothing to restore
+    }
+    if (stat.isSymbolicLink()) {
+        return; // don't follow: the target lives elsewhere
+    }
+    try {
+        // Add owner-write, preserving every other bit (read/execute stay intact so
+        // a directory remains traversable and readable for the recursion below).
+        chmodSync(path, stat.mode | 0o200);
+    }
+    catch {
+        // best-effort: one un-chmod-able entry must not abort the walk
+    }
+    if (stat.isDirectory()) {
+        let entries;
+        try {
+            entries = readdirSync(path);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            restoreWritable(join(path, entry));
+        }
+    }
+}
+/**
+ * Remove a directory tree that may be hardened read-only by Drupal:
+ * {@link restoreWritable} first, then `rm -rf`. Used where the conductor owns
+ * the unlink; when herdr performs the removal, call {@link restoreWritable}
+ * alone beforehand. A missing path is a no-op.
+ */
+export function forceRemoveDir(path) {
+    restoreWritable(path);
+    rmSync(path, { recursive: true, force: true });
+}