@bakers-build/addon-herdr-core 0.0.0-stage → 0.6.1-next.7

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-core
 
-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-core integration: executor running each agent in a herdr-core (hc) terminal.
+
+Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://github.com/bakers-build/bakers-build (bakers-cli/).

package/dist/src/index.d.ts

@@ -0,0 +1,56 @@
+import { type LaunchWatchOptions } from '@bakers-build/addon-herdr/shared';
+import type { BbExecutor, ExecutorCapabilities, ExecutorPlugin, SpawnedSession, SpawnRunInput } from '@bakers-build/conductor/contract';
+import { type ConductorLogger } from '@bakers-build/core';
+/** Runs `hc <args>`; resolves with stdout, rejects on a non-zero exit. */
+export type HcExec = (args: string[]) => Promise<string>;
+export interface HerdrCoreExecutorOptions {
+    /** Fallback agent command when the conductor supplies none. Default `claude`. */
+    command?: string;
+    /** As for herdr: `startTimeoutMs` (default 60 s), then `timeoutMs` (4 s). */
+    launchWatch?: Omit<LaunchWatchOptions, 'readPane'>;
+}
+/** The oldest `hc` whose `run --bg --no-parent --outlive-parent` this addon uses. */
+export declare const MIN_HC_VERSION = "0.1.18";
+/** `hc` is not on PATH. */
+export declare class HcNotFound extends Error {
+    constructor();
+}
+/** The real CLI, resolved through PATH. */
+export declare const defaultHc: HcExec;
+/** Rejects unless `hc --version` reports at least {@link MIN_HC_VERSION}. */
+export declare function assertHcVersion(hc: HcExec): Promise<void>;
+/**
+ * The run's terminal name, `<identifier>-<runId>`: hc allows 1-32 of
+ * `a-z0-9-_`, unique among live terminals. The run id suffix is never cut.
+ */
+export declare function terminalName(identifier: string, runId: number): string;
+/**
+ * Executor hosting each run's agent in a herdr-core terminal (`hc`). The
+ * terminal lives in the herdr-core server, so it survives the Herdr app quitting
+ * or crashing. It is found again by its `bakers.branch` and `bakers.run` labels.
+ * herdr-core has no workspace notion: the worktree comes from the workspace
+ * slot, and there is no `openWorkspace`.
+ */
+export declare class HerdrCoreExecutor implements BbExecutor {
+    private readonly options;
+    private readonly hc;
+    private readonly logger;
+    readonly id = "herdr-core";
+    constructor(options: HerdrCoreExecutorOptions, hc?: HcExec, logger?: ConductorLogger);
+    capabilities(): ExecutorCapabilities;
+    startRun(input: SpawnRunInput): Promise<SpawnedSession>;
+    /** No-op: `cleanupRun` ends the program; the transcript is already on disk. */
+    stopRun(_branch: string): Promise<void>;
+    /**
+     * End and remove the terminals of ONE run, found by its branch and run
+     * labels; a sibling run's terminal is left alone. Best-effort: a failure is
+     * logged, never thrown, and a missing match is warned about, since it may
+     * leave an agent running.
+     */
+    cleanupRun(branch: string, runId: number): Promise<void>;
+    /** `hc kill` (when live) then `hc rm`; each step best-effort. */
+    private drop;
+    private commandFor;
+}
+export declare function herdrCoreExecutor(options?: HerdrCoreExecutorOptions): ExecutorPlugin;
+export default herdrCoreExecutor;

package/dist/src/index.js

@@ -0,0 +1,198 @@
+import { rmSync } from 'node:fs';
+import { watchLaunch, writeLaunchScript, } from '@bakers-build/addon-herdr/shared';
+import { ExecError, exec, shellQuote, } from '@bakers-build/core';
+/** The oldest `hc` whose `run --bg --no-parent --outlive-parent` this addon uses. */
+export const MIN_HC_VERSION = '0.1.18';
+/** `hc` is not on PATH. */
+export class HcNotFound extends Error {
+    constructor() {
+        super(`hc not found on PATH: install herdr-core ${MIN_HC_VERSION} or later (https://herdr.dev/core/)`);
+        this.name = 'HcNotFound';
+    }
+}
+/** The real CLI, resolved through PATH. */
+export const defaultHc = async (args) => {
+    try {
+        return await exec('hc', args);
+    }
+    catch (err) {
+        const cause = (err instanceof ExecError ? err.cause : err);
+        if (cause?.code === 'ENOENT')
+            throw new HcNotFound();
+        throw err;
+    }
+};
+const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+function versionParts(version) {
+    return version.split('.').map(Number);
+}
+/** Rejects unless `hc --version` reports at least {@link MIN_HC_VERSION}. */
+export async function assertHcVersion(hc) {
+    const out = await hc(['--version']);
+    const found = out.match(/(\d+)\.(\d+)\.(\d+)/)?.[0];
+    if (!found) {
+        throw new Error(`hc --version printed no version: ${out.trim()}`);
+    }
+    const have = versionParts(found);
+    const need = versionParts(MIN_HC_VERSION);
+    for (let i = 0; i < need.length; i++) {
+        if ((have[i] ?? 0) > (need[i] ?? 0))
+            return;
+        if ((have[i] ?? 0) < (need[i] ?? 0)) {
+            throw new Error(`hc ${found} is too old: upgrade herdr-core to ${MIN_HC_VERSION} or later (hc update)`);
+        }
+    }
+}
+/**
+ * The run's terminal name, `<identifier>-<runId>`: hc allows 1-32 of
+ * `a-z0-9-_`, unique among live terminals. The run id suffix is never cut.
+ */
+export function terminalName(identifier, runId) {
+    const suffix = `-${runId}`;
+    const key = identifier.toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+    return `${key.slice(0, Math.max(1, 32 - suffix.length))}${suffix}`;
+}
+/**
+ * `hc ls --json` prints `{hidden_finished, terminals: [{address, name, state}]}`
+ * (hc 0.1.18); `address` (`t4`) is unique even among finished terminals.
+ */
+function parseTerminals(output) {
+    const list = JSON.parse(output)
+        ?.terminals;
+    if (!Array.isArray(list))
+        return [];
+    return list.flatMap((t) => {
+        const r = t;
+        return typeof r?.address === 'string' && r.address
+            ? [{ id: r.address, live: r.state !== 'finished' }]
+            : [];
+    });
+}
+/**
+ * Executor hosting each run's agent in a herdr-core terminal (`hc`). The
+ * terminal lives in the herdr-core server, so it survives the Herdr app quitting
+ * or crashing. It is found again by its `bakers.branch` and `bakers.run` labels.
+ * herdr-core has no workspace notion: the worktree comes from the workspace
+ * slot, and there is no `openWorkspace`.
+ */
+export class HerdrCoreExecutor {
+    options;
+    hc;
+    logger;
+    id = 'herdr-core';
+    constructor(options, hc = defaultHc, logger = noopLogger) {
+        this.options = options;
+        this.hc = hc;
+        this.logger = logger;
+    }
+    capabilities() {
+        return { persistent: true };
+    }
+    async startRun(input) {
+        await assertHcVersion(this.hc);
+        const name = terminalName(input.ticket.identifier, input.run.id);
+        let launch;
+        let started = false;
+        try {
+            // The run's env travels inside the 0600 launch script, never in argv.
+            launch = writeLaunchScript(this.commandFor(input));
+            await this.hc([
+                'run',
+                '--bg',
+                '--no-parent',
+                '--outlive-parent',
+                '--cwd',
+                input.workspacePath,
+                '--name',
+                name,
+                '--label',
+                `bakers.branch=${input.ticket.branchName}`,
+                '--label',
+                `bakers.run=${input.run.id}`,
+                '--label',
+                `bakers.ticket=${input.ticket.identifier}`,
+                '--json',
+                'sh',
+                launch.wrapPath,
+            ]);
+            started = true;
+            await watchLaunch(launch, {
+                ...(this.options.launchWatch ?? {}),
+                readPane: () => this.hc(['read', name, '--lines', '40']),
+            });
+            return { sessionRef: name };
+        }
+        catch (err) {
+            if (launch)
+                rmSync(launch.dir, { recursive: true, force: true });
+            if (started)
+                await this.drop(name, true);
+            throw err;
+        }
+    }
+    /** No-op: `cleanupRun` ends the program; the transcript is already on disk. */
+    async stopRun(_branch) { }
+    /**
+     * End and remove the terminals of ONE run, found by its branch and run
+     * labels; a sibling run's terminal is left alone. Best-effort: a failure is
+     * logged, never thrown, and a missing match is warned about, since it may
+     * leave an agent running.
+     */
+    async cleanupRun(branch, runId) {
+        try {
+            const terminals = parseTerminals(await this.hc([
+                'ls',
+                '--all',
+                '--label',
+                `bakers.branch=${branch}`,
+                '--label',
+                `bakers.run=${runId}`,
+                '--json',
+            ]));
+            if (terminals.length === 0) {
+                this.logger.warn({ branch, runId }, 'no herdr-core terminal found for this run; its agent may still be running');
+                return;
+            }
+            for (const t of terminals)
+                await this.drop(t.id, t.live);
+        }
+        catch (err) {
+            this.logger.warn({ branch, runId, err: String(err) }, 'herdr-core cleanup failed (best-effort)');
+        }
+    }
+    /** `hc kill` (when live) then `hc rm`; each step best-effort. */
+    async drop(terminal, live) {
+        if (live) {
+            await this.hc(['kill', terminal, '--json']).catch(() => { });
+        }
+        await this.hc(['rm', terminal, '--json']).catch(() => { });
+    }
+    commandFor(input) {
+        const env = Object.entries(input.env ?? {}).map(([key, value]) => {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+                throw new Error(`invalid environment variable name for herdr-core: ${key}`);
+            }
+            return `${key}=${shellQuote(value)}`;
+        });
+        const command = input.command ?? this.options.command ?? 'claude';
+        return [...env, command].join(' ');
+    }
+}
+export function herdrCoreExecutor(options = {}) {
+    return {
+        kind: 'executor',
+        id: 'herdr-core',
+        requiredModules: [],
+        async createExecutor(_config, deps) {
+            return new HerdrCoreExecutor({ ...options, command: options.command ?? 'claude' }, defaultHc, deps.logger);
+        },
+    };
+}
+// The class is exported too, so the default export is what lets the config
+// resolver pick the factory without an `export:` key.
+export default herdrCoreExecutor;

package/dist/src/preset.d.ts

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

package/dist/src/preset.js

@@ -0,0 +1,6 @@
+import { herdrCoreExecutor } from './index.js';
+export const executors = (acc, opts) => [
+    ...acc,
+    herdrCoreExecutor(opts),
+];
+export const scopes = ['machine', 'project'];

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@bakers-build/addon-herdr-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.1-next.7",
+  "description": "bakers.build herdr-core integration: executor running each agent in a herdr-core (hc) terminal.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./preset": "./dist/src/preset.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bakers-build/bakers-build.git",
+    "directory": "bakers-cli/addons/herdr-core"
+  },
+  "dependencies": {
+    "@bakers-build/addon-herdr": "^0.6.1-next.7"
+  },
+  "peerDependencies": {
+    "@bakers-build/conductor": "^0.6.1-next.7",
+    "@bakers-build/core": "^0.6.1-next.7"
+  },
+  "bakersBuild": {
+    "commit": "b89398b187bf51f4f9ca5bfc1150469f73a879e6",
+    "channel": "next"
+  }
+}