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

package/dist/src/launch-script.d.ts

@@ -0,0 +1,34 @@
+export interface LaunchScript {
+    dir: string;
+    wrapPath: string;
+    commandPath: string;
+    startedPath: string;
+    exitPath: string;
+    typedCommand: string;
+}
+/**
+ * Write a run-scoped launch script so a fresh pane is typed only `sh '<file>'`.
+ *
+ * The assembled command (env prefixes + agent argv) lives in a `0600` file
+ * inside a fresh `0700` directory under the OS temp dir. The typed line stays
+ * well under the tty canonical cap (macOS 1024, Linux 4096). The wrapper
+ * deletes the command file as its first step so secrets never linger in the
+ * pane's shell history or on disk after launch.
+ */
+export declare function writeLaunchScript(command: string): LaunchScript;
+export interface LaunchWatchOptions {
+    /** Window after `started` in which an immediate agent exit fails the launch. */
+    timeoutMs?: number;
+    /** How long to wait for the wrapper to write `started`. Default 60s. */
+    startTimeoutMs?: number;
+    pollMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    readPane?: () => Promise<string>;
+}
+/**
+ * Poll the launch markers in two phases. Wait up to `startTimeoutMs` for
+ * `started` (shell start-up), then apply a short `timeoutMs` exit window from
+ * that moment. An immediate exit or a script that never starts fails the
+ * launch; an agent still running at the exit deadline is treated as started.
+ */
+export declare function watchLaunch(script: LaunchScript, opts?: LaunchWatchOptions): Promise<void>;

package/dist/src/launch-script.js

@@ -0,0 +1,98 @@
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { shellQuote } from '@bakers-build/core';
+/**
+ * Write a run-scoped launch script so a fresh pane is typed only `sh '<file>'`.
+ *
+ * The assembled command (env prefixes + agent argv) lives in a `0600` file
+ * inside a fresh `0700` directory under the OS temp dir. The typed line stays
+ * well under the tty canonical cap (macOS 1024, Linux 4096). The wrapper
+ * deletes the command file as its first step so secrets never linger in the
+ * pane's shell history or on disk after launch.
+ */
+export function writeLaunchScript(command) {
+    const dir = mkdtempSync(join(tmpdir(), 'bakers-run-'));
+    chmodSync(dir, 0o700);
+    try {
+        const commandPath = join(dir, 'command');
+        const wrapPath = join(dir, 'run.sh');
+        const startedPath = join(dir, 'started');
+        const exitPath = join(dir, 'exit');
+        writeFileSync(commandPath, command, { encoding: 'utf8', mode: 0o600 });
+        chmodSync(commandPath, 0o600);
+        const wrap = `#!/bin/sh
+dir=${shellQuote(dir)}
+cmd=$(cat -- "$dir/command")
+rm -f -- "$dir/command" "$0"
+printf started > "$dir/started"
+trap : INT QUIT
+( eval "$cmd" )
+code=$?
+printf 'exit %s\\n' "$code" > "$dir/exit"
+exit "$code"
+`;
+        writeFileSync(wrapPath, wrap, { encoding: 'utf8', mode: 0o600 });
+        chmodSync(wrapPath, 0o600);
+        return {
+            dir,
+            wrapPath,
+            commandPath,
+            startedPath,
+            exitPath,
+            typedCommand: `sh ${shellQuote(wrapPath)}`,
+        };
+    }
+    catch (err) {
+        rmSync(dir, { recursive: true, force: true });
+        throw err;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 4000;
+const DEFAULT_START_TIMEOUT_MS = 60_000;
+const DEFAULT_POLL_MS = 50;
+/**
+ * Poll the launch markers in two phases. Wait up to `startTimeoutMs` for
+ * `started` (shell start-up), then apply a short `timeoutMs` exit window from
+ * that moment. An immediate exit or a script that never starts fails the
+ * launch; an agent still running at the exit deadline is treated as started.
+ */
+export async function watchLaunch(script, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const startTimeoutMs = opts.startTimeoutMs ?? DEFAULT_START_TIMEOUT_MS;
+    const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const startDeadline = Date.now() + startTimeoutMs;
+    let exitDeadline = 0;
+    let sawStarted = false;
+    for (;;) {
+        if (existsSync(script.exitPath)) {
+            const line = readFileSync(script.exitPath, 'utf8').trim();
+            if (line) {
+                throw new Error(await launchFailure(line, opts.readPane));
+            }
+        }
+        if (!sawStarted && existsSync(script.startedPath)) {
+            sawStarted = true;
+            exitDeadline = Date.now() + timeoutMs;
+            if (timeoutMs === 0)
+                return;
+        }
+        const now = Date.now();
+        if (sawStarted) {
+            if (now >= exitDeadline)
+                return;
+        }
+        else if (now >= startDeadline) {
+            throw new Error(await launchFailure('agent did not start', opts.readPane));
+        }
+        await sleep(pollMs);
+    }
+}
+async function launchFailure(reason, readPane) {
+    const tail = readPane ? await readPane().catch(() => '') : '';
+    const trimmed = tail.trim();
+    return trimmed
+        ? `Launch failed: ${reason}\n${trimmed}`
+        : `Launch failed: ${reason}`;
+}

package/dist/src/pane-layout.d.ts

@@ -0,0 +1,45 @@
+import { type PaneSpec } from './config.js';
+export type HerdrExec = (args: string[], opts?: {
+    redactArgs?: (args: string[]) => string[];
+}) => Promise<string>;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function parseJson(output: string, command: string): unknown;
+export declare function parsePaneSplit(output: string): string;
+/**
+ * A pane layout: an optional command run in the root/main pane, plus optional
+ * split panes. Shared by the executor's per-run tab (`startRun`) and the
+ * workspace's initial open pane (`herdrWorkspace` `open`) — one code path, no
+ * duplication. The per-state `StateConfig` (executor) and the workspace `open`
+ * option both narrow to this shape (the executor adds `tabLabel`; there is only
+ * one open layout, not a per-state map).
+ */
+export interface PaneLayout {
+    /** Command run in the initial root/main pane (typed verbatim, not templated). */
+    command?: string;
+    /** Extra split panes off the root; each command is `renderTemplate`'d. */
+    panes?: PaneSpec[];
+}
+/**
+ * Apply a {@link PaneLayout} to an existing root pane: run `command` in the root
+ * pane, then split each configured pane (with `--cwd cwd`) and run its
+ * `renderTemplate`'d command. The root command is typed VERBATIM (the caller
+ * pre-assembles it — e.g. the executor's env-prefixed agent command, BB-101/128);
+ * only split commands are templated from `vars`.
+ *
+ * `opts.redactCommand` supplies a log-safe rewrite of the root command (env
+ * VALUES masked, key names kept — BB-99): when it returns a different string a
+ * `redactArgs` scrubber is passed so a failed `pane run` exec-log never carries a
+ * secret, while the command herdr actually runs stays real. An empty layout
+ * (`{}`) issues no calls at all — the caller's unconfigured default is preserved.
+ *
+ * `opts.env` is forwarded to each split pane as `--env` args (BB_* only, see
+ * {@link envArgs}). It is deliberately per-CALLER rather than baked in: this
+ * primitive serves both the executor's agent tab and the workspace's own open
+ * pane, and only the former's panes are agent-owned (BB-64). The ROOT pane is
+ * not touched — it already exists when we get here, so its environment came from
+ * whoever created it. Omitted ⇒ no `--env` at all.
+ */
+export declare function applyPaneLayout(execHerdr: HerdrExec, rootPaneId: string, layout: PaneLayout, cwd: string, vars: Record<string, string>, opts?: {
+    redactCommand?: (command: string) => string;
+    env?: Record<string, string | undefined>;
+}): Promise<void>;

package/dist/src/pane-layout.js

@@ -0,0 +1,78 @@
+import { renderTemplate } from './config.js';
+import { envArgs } from './panes.js';
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function parseJson(output, command) {
+    try {
+        return JSON.parse(output);
+    }
+    catch {
+        throw new Error(`herdr ${command} returned invalid JSON`);
+    }
+}
+export function parsePaneSplit(output) {
+    const parsed = parseJson(output, 'pane split');
+    const paneId = isRecord(parsed)
+        ? parsed.result?.pane
+            ?.pane_id
+        : undefined;
+    if (typeof paneId !== 'string') {
+        throw new Error('herdr pane split returned invalid schema');
+    }
+    return paneId;
+}
+/**
+ * Apply a {@link PaneLayout} to an existing root pane: run `command` in the root
+ * pane, then split each configured pane (with `--cwd cwd`) and run its
+ * `renderTemplate`'d command. The root command is typed VERBATIM (the caller
+ * pre-assembles it — e.g. the executor's env-prefixed agent command, BB-101/128);
+ * only split commands are templated from `vars`.
+ *
+ * `opts.redactCommand` supplies a log-safe rewrite of the root command (env
+ * VALUES masked, key names kept — BB-99): when it returns a different string a
+ * `redactArgs` scrubber is passed so a failed `pane run` exec-log never carries a
+ * secret, while the command herdr actually runs stays real. An empty layout
+ * (`{}`) issues no calls at all — the caller's unconfigured default is preserved.
+ *
+ * `opts.env` is forwarded to each split pane as `--env` args (BB_* only, see
+ * {@link envArgs}). It is deliberately per-CALLER rather than baked in: this
+ * primitive serves both the executor's agent tab and the workspace's own open
+ * pane, and only the former's panes are agent-owned (BB-64). The ROOT pane is
+ * not touched — it already exists when we get here, so its environment came from
+ * whoever created it. Omitted ⇒ no `--env` at all.
+ */
+export async function applyPaneLayout(execHerdr, rootPaneId, layout, cwd, vars, opts) {
+    if (layout.command) {
+        const command = layout.command;
+        const runArgs = ['pane', 'run', rootPaneId, command];
+        const redacted = opts?.redactCommand?.(command);
+        if (redacted !== undefined && redacted !== command) {
+            await execHerdr(runArgs, {
+                redactArgs: (args) => args.map((a) => (a === command ? redacted : a)),
+            });
+        }
+        else {
+            await execHerdr(runArgs);
+        }
+    }
+    for (const spec of layout.panes ?? []) {
+        const splitPaneId = parsePaneSplit(await execHerdr([
+            'pane',
+            'split',
+            rootPaneId,
+            '--direction',
+            spec.direction,
+            '--cwd',
+            cwd,
+            spec.focus ? '--focus' : '--no-focus',
+            ...envArgs(opts?.env ?? {}),
+        ]));
+        await execHerdr([
+            'pane',
+            'run',
+            splitPaneId,
+            renderTemplate(spec.command, vars),
+        ]);
+    }
+}

package/dist/src/panes.d.ts

@@ -0,0 +1,31 @@
+/** A herdr pane and the tab it sits in. */
+export interface HerdrPaneRef {
+    paneId: string;
+    tabId: string;
+}
+/** A herdr pane plus its label. */
+export interface HerdrPaneInfo extends HerdrPaneRef {
+    label: string;
+}
+/**
+ * Marker exported into an AGENT pane's interactive shell, so a user's opt-in
+ * shell init can recognise an agent-run pane at startup and isolate its history
+ * (BB-64). It is a plain `BB_*` env entry on purpose: it rides {@link envArgs}
+ * like every other pane var instead of adding a second mechanism.
+ *
+ * AGENT panes only — the executor's per-run tab and its layout panes, plus the
+ * TUI-hosted agents. NOT the workspace's own open-layout pane: that one is the
+ * human's landing pane, and the opt-in unsets `HISTFILE`. See
+ * `docs/conductor/node.md` § Agent-pane shell marker.
+ */
+export declare const AGENT_SHELL_ENV: Record<string, string>;
+/** BB_* env vars as `--env KEY=VALUE` args (never dump the full environment). */
+export declare function envArgs(env: Record<string, string | undefined>): string[];
+/** `{ paneId, tabId }` from a `herdr tab create` envelope. */
+export declare function parseTabCreate(output: string): HerdrPaneRef;
+/** `{ paneId, tabId }` from a `result.pane` envelope (pane current / split). */
+export declare function parsePaneInfo(output: string): HerdrPaneRef;
+/** The id of the first tab whose label equals `label`, else null. */
+export declare function findTabIdByLabel(output: string, label: string): string | null;
+/** Panes in `tabId` as `[{ paneId, tabId, label }]` from a `pane list` envelope. */
+export declare function parsePanesInTab(output: string, tabId: string): HerdrPaneInfo[];

package/dist/src/panes.js

@@ -0,0 +1,87 @@
+// Herdr pane/tab CLI envelope parsers (BB-190) — the building blocks the
+// intent-level `herdrAgentHost` (agents.ts) uses to talk to herdr. Kept small
+// and herdr-internal; the conductor/TUI never see these pane shapes.
+function isRecord(v) {
+    return typeof v === 'object' && v !== null;
+}
+/**
+ * Marker exported into an AGENT pane's interactive shell, so a user's opt-in
+ * shell init can recognise an agent-run pane at startup and isolate its history
+ * (BB-64). It is a plain `BB_*` env entry on purpose: it rides {@link envArgs}
+ * like every other pane var instead of adding a second mechanism.
+ *
+ * AGENT panes only — the executor's per-run tab and its layout panes, plus the
+ * TUI-hosted agents. NOT the workspace's own open-layout pane: that one is the
+ * human's landing pane, and the opt-in unsets `HISTFILE`. See
+ * `docs/conductor/node.md` § Agent-pane shell marker.
+ */
+export const AGENT_SHELL_ENV = {
+    BB_AGENT_SHELL: '1',
+};
+/** BB_* env vars as `--env KEY=VALUE` args (never dump the full environment). */
+export function envArgs(env) {
+    const out = [];
+    for (const [key, value] of Object.entries(env)) {
+        if (key.startsWith('BB_') && value != null) {
+            out.push('--env', `${key}=${value}`);
+        }
+    }
+    return out;
+}
+/** `{ paneId, tabId }` from a `herdr tab create` envelope. */
+export function parseTabCreate(output) {
+    const parsed = JSON.parse(output);
+    const result = isRecord(parsed)
+        ? parsed.result
+        : undefined;
+    const paneId = result?.root_pane?.pane_id;
+    const tabId = result?.tab?.tab_id;
+    if (typeof paneId !== 'string' || typeof tabId !== 'string') {
+        throw new Error('herdr tab create returned invalid schema');
+    }
+    return { paneId, tabId };
+}
+/** `{ paneId, tabId }` from a `result.pane` envelope (pane current / split). */
+export function parsePaneInfo(output) {
+    const parsed = JSON.parse(output);
+    const pane = isRecord(parsed)
+        ? parsed.result
+            ?.pane
+        : undefined;
+    const paneId = pane?.pane_id;
+    const tabId = pane?.tab_id;
+    if (typeof paneId !== 'string' || typeof tabId !== 'string') {
+        throw new Error('herdr returned no pane info');
+    }
+    return { paneId, tabId };
+}
+/** The id of the first tab whose label equals `label`, else null. */
+export function findTabIdByLabel(output, label) {
+    const parsed = JSON.parse(output);
+    const tabs = isRecord(parsed)
+        ? parsed.result?.tabs
+        : undefined;
+    if (!Array.isArray(tabs))
+        return null;
+    const match = tabs
+        .filter(isRecord)
+        .find((t) => t.label === label && typeof t.tab_id === 'string');
+    return match ? match.tab_id : null;
+}
+/** Panes in `tabId` as `[{ paneId, tabId, label }]` from a `pane list` envelope. */
+export function parsePanesInTab(output, tabId) {
+    const parsed = JSON.parse(output);
+    const panes = isRecord(parsed)
+        ? parsed.result?.panes
+        : undefined;
+    if (!Array.isArray(panes))
+        return [];
+    return panes
+        .filter(isRecord)
+        .filter((p) => typeof p.pane_id === 'string' && p.tab_id === tabId)
+        .map((p) => ({
+        paneId: p.pane_id,
+        tabId,
+        label: typeof p.label === 'string' ? p.label : '',
+    }));
+}

package/dist/src/preset.d.ts

@@ -0,0 +1,6 @@
+import type { Preset } from '@bakers-build/conductor/contract';
+export declare const executors: Preset['executors'];
+export declare const workspaces: Preset['workspaces'];
+export declare const processHosts: Preset['processHosts'];
+export declare const hooks: Preset['hooks'];
+export declare const scopes: Preset['scopes'];

package/dist/src/preset.js

@@ -0,0 +1,18 @@
+import { herdrFrozenMarker } from './frozen-marker.js';
+import { herdrExecutor, herdrWorkspace } from './index.js';
+import { herdrProcessHost } from './process-host.js';
+export const executors = (acc, opts) => [
+    ...acc,
+    herdrExecutor(opts),
+];
+export const workspaces = (acc, opts) => [
+    ...acc,
+    herdrWorkspace(opts),
+];
+export const processHosts = (acc) => [
+    ...acc,
+    herdrProcessHost,
+];
+export const hooks = (acc) => [...acc, herdrFrozenMarker];
+// Hook listeners and the process host belong to one project (no machine hook listeners, BB-599).
+export const scopes = ['project'];

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

@@ -0,0 +1,6 @@
+import type { HerdrHost } from '@bakers-build/conductor/contract';
+/**
+ * Close every herdr workspace whose label equals the conductor handle, then
+ * create one and `exec env` the pane command so herdr auto-closes on exit.
+ */
+export declare const herdrProcessHost: HerdrHost;

package/dist/src/process-host.js

@@ -0,0 +1,46 @@
+import { exec } from '@bakers-build/core';
+import { isRecord, parseJson } from './pane-layout.js';
+import { parseWorkspaceList } from './workspace-list.js';
+function parseWorkspaceCreate(output) {
+    const parsed = parseJson(output, 'workspace create');
+    const paneId = isRecord(parsed)
+        ? parsed.result
+            ?.root_pane?.pane_id
+        : undefined;
+    if (typeof paneId !== 'string' || paneId === '') {
+        throw new Error('herdr workspace create returned no pane id');
+    }
+    return paneId;
+}
+/**
+ * Close every herdr workspace whose label equals the conductor handle, then
+ * create one and `exec env` the pane command so herdr auto-closes on exit.
+ */
+export const herdrProcessHost = {
+    async spawn(label, cwd, cmd) {
+        const listed = parseWorkspaceList(await exec('herdr', ['workspace', 'list']));
+        for (const ws of listed) {
+            if (ws.label === label) {
+                try {
+                    await exec('herdr', ['workspace', 'close', ws.workspaceId]);
+                }
+                catch {
+                    // herdr may already have auto-closed it after a previous stop
+                }
+            }
+        }
+        const paneId = parseWorkspaceCreate(await exec('herdr', [
+            'workspace',
+            'create',
+            '--cwd',
+            cwd,
+            '--label',
+            label,
+            '--no-focus',
+        ]));
+        // `exec env` replaces the pane's login shell (fish-safe VAR=value form)
+        // so herdr closes the workspace when the conductor exits by any path.
+        // `env` needs a real `bakers` executable on PATH.
+        await exec('herdr', ['pane', 'run', paneId, `exec env ${cmd}`]);
+    },
+};

package/dist/src/root-anchor.d.ts

@@ -0,0 +1,13 @@
+import { defaultRootGitExec, deriveCheckoutRoot, type RootGitExec } from '@bakers-build/core';
+export type { RootGitExec };
+export { defaultRootGitExec };
+/**
+ * herdr's own name for the shared checkout-root anchor (BB-177), kept as a
+ * thin alias so `index.ts` and `workspace.ts` need no rename. The behaviour —
+ * including the injected git-exec seam — now lives in `@bakers-build/core` as
+ * `deriveCheckoutRoot()` (BB-450 D2): two other call sites
+ * (`@bakers-build/conductor`'s `checkoutRootOf()` and `addon-workspace-git`'s
+ * `gitWorkspace` fallback) needed the same derivation and neither may import
+ * this addon, so the helper moved to the kernel rather than staying herdr-owned.
+ */
+export declare const deriveHerdrRoot: typeof deriveCheckoutRoot;

package/dist/src/root-anchor.js

@@ -0,0 +1,12 @@
+import { defaultRootGitExec, deriveCheckoutRoot, } from '@bakers-build/core';
+export { defaultRootGitExec };
+/**
+ * herdr's own name for the shared checkout-root anchor (BB-177), kept as a
+ * thin alias so `index.ts` and `workspace.ts` need no rename. The behaviour —
+ * including the injected git-exec seam — now lives in `@bakers-build/core` as
+ * `deriveCheckoutRoot()` (BB-450 D2): two other call sites
+ * (`@bakers-build/conductor`'s `checkoutRootOf()` and `addon-workspace-git`'s
+ * `gitWorkspace` fallback) needed the same derivation and neither may import
+ * this addon, so the helper moved to the kernel rather than staying herdr-owned.
+ */
+export const deriveHerdrRoot = deriveCheckoutRoot;

package/dist/src/workspace-list.d.ts

@@ -0,0 +1,19 @@
+/** One `herdr workspace list` entry. */
+export interface WorkspaceEntry {
+    workspaceId: string;
+    /** Workspace label; null when herdr omits it. */
+    label: string | null;
+    focused: boolean;
+    isLinkedWorktree: boolean;
+    /** The worktree's parent repo root — the shared key between a linked
+     * ticket worktree and its main checkout. Null when herdr reports none. */
+    repoRoot: string | null;
+    /** The workspace's checkout directory. Null when herdr reports none. */
+    checkoutPath: string | null;
+}
+/**
+ * Parse `herdr workspace list` (which always emits JSON; it takes no `--json`
+ * flag). Enumerates every workspace on the host with its `label`, `focused`
+ * flag and its `worktree.{is_linked_worktree,repo_root}`.
+ */
+export declare function parseWorkspaceList(output: string): WorkspaceEntry[];

package/dist/src/workspace-list.js

@@ -0,0 +1,29 @@
+import { isRecord, parseJson } from './pane-layout.js';
+/**
+ * Parse `herdr workspace list` (which always emits JSON; it takes no `--json`
+ * flag). Enumerates every workspace on the host with its `label`, `focused`
+ * flag and its `worktree.{is_linked_worktree,repo_root}`.
+ */
+export function parseWorkspaceList(output) {
+    const parsed = parseJson(output, 'workspace list');
+    const workspaces = isRecord(parsed)
+        ? parsed.result?.workspaces
+        : undefined;
+    if (!Array.isArray(workspaces)) {
+        return [];
+    }
+    return workspaces
+        .filter(isRecord)
+        .filter((w) => typeof w.workspace_id === 'string')
+        .map((w) => {
+        const wt = isRecord(w.worktree) ? w.worktree : undefined;
+        return {
+            workspaceId: w.workspace_id,
+            label: typeof w.label === 'string' ? w.label : null,
+            focused: w.focused === true,
+            isLinkedWorktree: wt?.is_linked_worktree === true,
+            repoRoot: typeof wt?.repo_root === 'string' ? wt.repo_root : null,
+            checkoutPath: typeof wt?.checkout_path === 'string' ? wt.checkout_path : null,
+        };
+    });
+}