@bakers-build/addon-orca 0.0.0-stage → 0.1.2-next.194

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-orca
 
-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 Orca integration: executor + per-ticket worktree workspace hosted in Orca.
+
+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/config.d.ts

@@ -0,0 +1,39 @@
+import type { RootGitExec } from '@bakers-build/core';
+export interface OrcaStateConfig {
+    /**
+     * Terminal title template; must contain `{identifier}`. Other vars:
+     * `{title}`, `{titleSlug}`, `{runUuid}`, `{workspacePath}`. `startRun`
+     * appends ` #<run.id>`, the token `cleanupRun` finds the run's terminal by.
+     */
+    tabLabel?: string;
+}
+export interface OrcaExecutorOptions {
+    /** Fallback agent command when the conductor supplies none. */
+    command?: string;
+    /** Lifecycle-hook commands, copied from `config.hooks` by the factory. */
+    hooks?: {
+        after_create?: string;
+        before_run?: string;
+        after_run?: string;
+        after_done?: string;
+        on_freeze?: string;
+        on_resume?: string;
+    };
+    /** Main clone; otherwise derived from the git common dir by the factory. */
+    root?: string;
+    /** Overrideable git exec for root derivation (tests). */
+    execGit?: RootGitExec;
+    default?: OrcaStateConfig;
+    states?: Record<string, OrcaStateConfig>;
+    /** Same windows as herdr: wait for `started` (60 s), then an exit window (4 s). */
+    launchWatch?: {
+        timeoutMs?: number;
+        startTimeoutMs?: number;
+        pollMs?: number;
+        sleep?: (ms: number) => Promise<void>;
+    };
+    /** How long `startRun` waits for Orca to adopt the worktree. Default 35 s. */
+    adoptTimeoutMs?: number;
+}
+export declare const DEFAULT_TAB_LABEL = "{identifier} \u00B7 {titleSlug}";
+export declare function resolveTabLabel(options: OrcaExecutorOptions, state: string): string;

package/dist/src/config.js

@@ -0,0 +1,10 @@
+export const DEFAULT_TAB_LABEL = '{identifier} · {titleSlug}';
+export function resolveTabLabel(options, state) {
+    const tabLabel = options.states?.[state]?.tabLabel ??
+        options.default?.tabLabel ??
+        DEFAULT_TAB_LABEL;
+    if (!tabLabel.includes('{identifier}')) {
+        throw new Error(`orca tabLabel must contain {identifier}: ${tabLabel}`);
+    }
+    return tabLabel;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,44 @@
+import type { BbExecutor, ExecutorCapabilities, ExecutorPlugin, HookContext, HookName, HookResult, SpawnedSession, SpawnRunInput, WorktreeTeardown } from '@bakers-build/conductor/contract';
+import type { ConductorLogger } from '@bakers-build/core';
+import { type OrcaExecutorOptions } from './config.js';
+import { type OrcaExec } from './orca-cli.js';
+import { type GitExec, type Sleep } from './workspace.js';
+export type { OrcaExecutorOptions } from './config.js';
+export { OrcaError, type OrcaExec } from './orca-cli.js';
+export { type OrcaOpenLayout, OrcaWorkspace, type OrcaWorkspaceOptions, orcaWorkspace, } from './workspace.js';
+/** Runs a lifecycle-hook shell command in a cwd; rejects on non-zero exit. */
+export type ShellRunner = (command: string, cwd: string, env?: Record<string, string>) => Promise<void>;
+/**
+ * Executor hosting each run's agent in an Orca terminal of the ticket's
+ * worktree. Terminal handles do not survive an Orca restart, so none is kept
+ * beyond the call that obtained it: a run's terminal is found again by branch
+ * and the `#<runId>` token in its title.
+ */
+export declare class OrcaExecutor implements BbExecutor {
+    private readonly options;
+    private readonly execOrca;
+    private readonly logger;
+    private readonly runShell;
+    private readonly execGit;
+    private readonly sleep;
+    readonly id = "orca";
+    constructor(options: OrcaExecutorOptions, execOrca?: OrcaExec, logger?: ConductorLogger, runShell?: ShellRunner, execGit?: GitExec, sleep?: Sleep);
+    capabilities(): ExecutorCapabilities;
+    /** The single best-effort catch point for lifecycle hooks; never throws. */
+    runHook(name: HookName, cwd: string, ctx: HookContext, env?: Record<string, string>): Promise<HookResult>;
+    startRun(input: SpawnRunInput): Promise<SpawnedSession>;
+    private readTail;
+    /** Best-effort: a live or unverifiable stop must not abort the caller. */
+    private closeTerminal;
+    /**
+     * No-op, as for herdr: the transcript is captured after this call, and
+     * {@link cleanupRun} closing the terminal is what ends the agent.
+     */
+    stopRun(_branch: string): Promise<void>;
+    /** Close every terminal of this run on this branch; best-effort throughout. */
+    cleanupRun(branch: string, runId: number): Promise<void>;
+    removeWorktree(branch: string, worktreePath?: string): Promise<WorktreeTeardown>;
+    private commandFor;
+}
+export declare function orcaExecutor(options?: OrcaExecutorOptions): ExecutorPlugin;
+export default orcaExecutor;

package/dist/src/index.js

@@ -0,0 +1,328 @@
+import { existsSync, rmSync } from 'node:fs';
+import { renderTemplate, restoreWritable, watchLaunch, writeLaunchScript, } from '@bakers-build/addon-herdr/shared';
+import { deriveCheckoutRoot, exec, shellQuote, slugify, } from '@bakers-build/core';
+import { resolveTabLabel } from './config.js';
+import { assertOrcaReachable, createOrcaExec, isRecord, } from './orca-cli.js';
+import { DEFAULT_ADOPT_TIMEOUT_MS, defaultSleep, noopLogger, porcelainEntries, waitForAdoption, } from './workspace.js';
+export { OrcaError } from './orca-cli.js';
+export { OrcaWorkspace, orcaWorkspace, } from './workspace.js';
+const defaultShellRunner = async (command, cwd, env) => {
+    await exec('sh', ['-c', command], { cwd, ...(env ? { env } : {}) });
+};
+/** Exact trailing `#<runId>` token, so `#7` never matches `#77`. */
+function titleMatchesRun(title, runId) {
+    if (typeof title !== 'string')
+        return false;
+    const m = title.match(/#(\d+)$/);
+    return m !== null && Number(m[1]) === runId;
+}
+/** Tab id → tab title from `terminal list --include-visual-layouts`. */
+function visualTabTitles(layouts) {
+    const titles = new Map();
+    const walk = (node) => {
+        if (!isRecord(node))
+            return;
+        if (Array.isArray(node.tabs)) {
+            for (const tab of node.tabs) {
+                if (isRecord(tab) && typeof tab.tabId === 'string') {
+                    titles.set(tab.tabId, tab.title);
+                }
+            }
+        }
+        walk(node.first);
+        walk(node.second);
+    };
+    if (Array.isArray(layouts)) {
+        for (const layout of layouts) {
+            if (isRecord(layout))
+                walk(layout.root);
+        }
+    }
+    return titles;
+}
+function normPath(path) {
+    return path.replace(/\/+$/, '');
+}
+/**
+ * Executor hosting each run's agent in an Orca terminal of the ticket's
+ * worktree. Terminal handles do not survive an Orca restart, so none is kept
+ * beyond the call that obtained it: a run's terminal is found again by branch
+ * and the `#<runId>` token in its title.
+ */
+export class OrcaExecutor {
+    options;
+    execOrca;
+    logger;
+    runShell;
+    execGit;
+    sleep;
+    id = 'orca';
+    constructor(options, execOrca = createOrcaExec(), logger = noopLogger, runShell = defaultShellRunner, execGit = (args) => exec('git', args), sleep = defaultSleep) {
+        this.options = options;
+        this.execOrca = execOrca;
+        this.logger = logger;
+        this.runShell = runShell;
+        this.execGit = execGit;
+        this.sleep = sleep;
+    }
+    capabilities() {
+        return { persistent: true };
+    }
+    /** The single best-effort catch point for lifecycle hooks; never throws. */
+    async runHook(name, cwd, ctx, env) {
+        const command = this.options.hooks?.[name];
+        if (!command) {
+            return { hook: name, ran: false, ok: true };
+        }
+        try {
+            await this.runShell(command, cwd, env);
+            return { hook: name, ran: true, ok: true };
+        }
+        catch (err) {
+            this.logger.error({ hook: name, worktree: cwd, ticket: ctx.ticket, err: String(err) }, 'lifecycle hook failed');
+            return { hook: name, ran: true, ok: false, error: String(err) };
+        }
+    }
+    async startRun(input) {
+        const tabLabel = resolveTabLabel(this.options, input.ticket.state);
+        await assertOrcaReachable(this.execOrca);
+        await waitForAdoption(this.execOrca, input.workspacePath, this.options.adoptTimeoutMs ?? DEFAULT_ADOPT_TIMEOUT_MS, this.sleep);
+        const title = `${renderTemplate(tabLabel, {
+            identifier: input.ticket.identifier,
+            title: input.ticket.title,
+            titleSlug: slugify(input.ticket.title),
+            runUuid: input.run.uuid,
+            workspacePath: input.workspacePath,
+        })} #${input.run.id}`;
+        let launch;
+        let handle;
+        try {
+            // Orca's `terminal create` takes no env: the run's env travels inside the
+            // 0600 launch script, never in argv; the terminal is typed `sh '<file>'`.
+            launch = writeLaunchScript(this.commandFor(input));
+            const created = await this.execOrca([
+                'terminal',
+                'create',
+                '--worktree',
+                `path:${input.workspacePath}`,
+                '--title',
+                title,
+                '--command',
+                launch.typedCommand,
+            ]);
+            const terminal = isRecord(created) ? created.terminal : undefined;
+            handle =
+                isRecord(terminal) && typeof terminal.handle === 'string'
+                    ? terminal.handle
+                    : undefined;
+            if (!handle) {
+                throw new Error('orca terminal create returned no terminal handle');
+            }
+            // A create `--title` is only a launch title the agent's OSC title replaces;
+            // a rename is a manual name restarts keep (on the tab in desktop Orca, on
+            // the terminal headless), so cleanupRun can still find the `#<runId>` token.
+            await this.execOrca([
+                'terminal',
+                'rename',
+                '--terminal',
+                handle,
+                '--title',
+                title,
+            ]);
+            const readHandle = handle;
+            await watchLaunch(launch, {
+                ...(this.options.launchWatch ?? {}),
+                readPane: () => this.readTail(readHandle),
+            });
+            return { sessionRef: input.ticket.branchName };
+        }
+        catch (err) {
+            if (launch) {
+                rmSync(launch.dir, { recursive: true, force: true });
+            }
+            if (handle) {
+                await this.closeTerminal(handle);
+            }
+            throw err;
+        }
+    }
+    async readTail(handle) {
+        const read = await this.execOrca([
+            'terminal',
+            'read',
+            '--terminal',
+            handle,
+        ]);
+        const tail = isRecord(read) && isRecord(read.terminal)
+            ? read.terminal.tail
+            : undefined;
+        return Array.isArray(tail) ? tail.join('\n') : '';
+    }
+    /** Best-effort: a live or unverifiable stop must not abort the caller. */
+    async closeTerminal(handle) {
+        try {
+            await this.execOrca(['terminal', 'close', '--terminal', handle]);
+        }
+        catch (err) {
+            this.logger.warn({ terminal: handle, err: String(err) }, 'orca terminal close failed (best-effort, ignored)');
+        }
+    }
+    /**
+     * No-op, as for herdr: the transcript is captured after this call, and
+     * {@link cleanupRun} closing the terminal is what ends the agent.
+     */
+    async stopRun(_branch) { }
+    /** Close every terminal of this run on this branch; best-effort throughout. */
+    async cleanupRun(branch, runId) {
+        let listed;
+        try {
+            // Orca returns 200 rows unless told otherwise; a cut-off run terminal would leak.
+            listed = await this.execOrca([
+                'terminal',
+                'list',
+                '--include-visual-layouts',
+                '--limit',
+                '10000',
+            ]);
+        }
+        catch (err) {
+            this.logger.warn({ branch, runId, err: String(err) }, 'orca terminal list failed (best-effort, ignored)');
+            return;
+        }
+        const terminals = isRecord(listed) && Array.isArray(listed.terminals)
+            ? listed.terminals
+            : [];
+        // Desktop Orca keeps the rename on the tab while the terminal reports the
+        // agent's own title; headless Orca keeps it on the terminal.
+        const tabTitles = visualTabTitles(isRecord(listed) ? listed.visualLayouts : undefined);
+        let matched = false;
+        for (const t of terminals) {
+            if (isRecord(t) &&
+                typeof t.handle === 'string' &&
+                typeof t.branch === 'string' &&
+                t.branch.replace(/^refs\/heads\//, '') === branch &&
+                (titleMatchesRun(t.title, runId) ||
+                    (typeof t.tabId === 'string' &&
+                        titleMatchesRun(tabTitles.get(t.tabId), runId)))) {
+                matched = true;
+                await this.closeTerminal(t.handle);
+            }
+        }
+        // A missed match would otherwise leak a running agent without a trace.
+        if (!matched) {
+            this.logger.warn({ branch, runId }, 'no orca terminal found for this run; its agent may still be running');
+        }
+    }
+    async removeWorktree(branch, worktreePath) {
+        const root = this.options.root;
+        if (root && worktreePath && normPath(worktreePath) === normPath(root)) {
+            this.logger.warn({ branch, worktreePath, root }, 'refusing to tear down the main checkout');
+            return 'unverified';
+        }
+        const gitDir = root ?? worktreePath;
+        let entries = [];
+        if (gitDir) {
+            try {
+                // Record 0 is the main checkout — never a ticket worktree.
+                entries = porcelainEntries(await this.execGit(['-C', gitDir, 'worktree', 'list', '--porcelain'])).slice(1);
+            }
+            catch {
+                // Degrade to the on-disk answer below.
+            }
+        }
+        const path = worktreePath
+            ? normPath(worktreePath)
+            : entries.find((e) => e.branch === branch)?.path;
+        if (!path) {
+            return 'unverified';
+        }
+        const registered = entries.some((e) => normPath(e.path) === path);
+        let orcaKnows = false;
+        try {
+            await assertOrcaReachable(this.execOrca);
+            await this.execOrca(['worktree', 'show', '--worktree', `path:${path}`]);
+            orcaKnows = true;
+        }
+        catch {
+            // Orca is down or never adopted it: tear down with git alone.
+        }
+        // Drupal hardens web/sites/default (0555): restore owner-write first.
+        restoreWritable(path);
+        if (orcaKnows) {
+            await this.execOrca([
+                'worktree',
+                'rm',
+                '--worktree',
+                `path:${path}`,
+                '--force',
+            ]);
+        }
+        else {
+            if (!registered && !existsSync(path)) {
+                return 'already_absent';
+            }
+            if (registered) {
+                try {
+                    await this.execGit([
+                        '-C',
+                        gitDir,
+                        'worktree',
+                        'remove',
+                        '--force',
+                        path,
+                    ]);
+                }
+                catch (err) {
+                    this.logger.warn({ path, err: String(err) }, 'git worktree remove failed on a registered worktree');
+                }
+            }
+            try {
+                rmSync(path, { recursive: true, force: true });
+            }
+            catch (err) {
+                this.logger.warn({ path, err: String(err) }, 'worktree directory reclaim failed');
+            }
+        }
+        if (gitDir) {
+            try {
+                await this.execGit(['-C', gitDir, 'worktree', 'prune']);
+            }
+            catch {
+                // best-effort sweep
+            }
+        }
+        return existsSync(path) ? 'unverified' : 'removed';
+    }
+    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 orca: ${key}`);
+            }
+            return `${key}=${shellQuote(value)}`;
+        });
+        const command = input.command ?? this.options.command ?? 'claude';
+        return [...env, command].join(' ');
+    }
+}
+export function orcaExecutor(options = {}) {
+    return {
+        kind: 'executor',
+        id: 'orca',
+        requiredModules: [],
+        async createExecutor(config, deps) {
+            const root = await deriveCheckoutRoot(config.config_path, {
+                ...(options.root !== undefined ? { override: options.root } : {}),
+                ...(options.execGit ? { execGit: options.execGit } : {}),
+            });
+            return new OrcaExecutor({
+                ...options,
+                command: options.command ?? 'claude',
+                root,
+                ...(config.hooks ? { hooks: config.hooks } : {}),
+            }, createOrcaExec(), 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 orcaExecutor;

package/dist/src/orca-cli.d.ts

@@ -0,0 +1,22 @@
+/** Runs `orca <args> --json`; resolves with the envelope's `result`. */
+export type OrcaExec = (args: string[]) => Promise<unknown>;
+/** An Orca CLI failure, keyed by Orca's own error `code`. */
+export declare class OrcaError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+/**
+ * Parse Orca's `--json` envelope. Orca prints BOTH outcomes on stdout —
+ * `{ok:true,result}` or `{ok:false,error:{code,message}}` — so `ok` decides,
+ * not the exit code.
+ */
+export declare function parseEnvelope(stdout: string): unknown;
+/** The real CLI: `bin` (default `orca`, resolved through PATH). */
+export declare function createOrcaExec(bin?: string): OrcaExec;
+/**
+ * Fail fast when no Orca runtime answers on this machine. `orca status` never
+ * fails itself, so `runtime.reachable` is the signal. Orca is never started
+ * implicitly: on a headless oven host `orca open` would launch a desktop app.
+ */
+export declare function assertOrcaReachable(orca: OrcaExec): Promise<void>;

package/dist/src/orca-cli.js

@@ -0,0 +1,76 @@
+import { ExecError, exec } from '@bakers-build/core';
+/** An Orca CLI failure, keyed by Orca's own error `code`. */
+export class OrcaError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'OrcaError';
+    }
+}
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Parse Orca's `--json` envelope. Orca prints BOTH outcomes on stdout —
+ * `{ok:true,result}` or `{ok:false,error:{code,message}}` — so `ok` decides,
+ * not the exit code.
+ */
+export function parseEnvelope(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        throw new OrcaError('invalid_output', `orca returned non-JSON output: ${stdout.trim().slice(0, 200)}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new OrcaError('invalid_output', 'orca returned an invalid envelope');
+    }
+    if (parsed.ok === true) {
+        return parsed.result;
+    }
+    const error = isRecord(parsed.error) ? parsed.error : {};
+    const code = typeof error.code === 'string' ? error.code : 'unknown_error';
+    const message = typeof error.message === 'string' ? error.message : 'orca command failed';
+    throw new OrcaError(code, `orca ${code}: ${message}`);
+}
+/** The real CLI: `bin` (default `orca`, resolved through PATH). */
+export function createOrcaExec(bin = 'orca') {
+    return async (args) => {
+        let stdout;
+        try {
+            stdout = await exec(bin, [...args, '--json']);
+        }
+        catch (err) {
+            const cause = (err instanceof ExecError ? err.cause : err);
+            if (cause?.code === 'ENOENT') {
+                throw new OrcaError('orca_not_found', 'orca CLI not found in PATH');
+            }
+            // A non-zero exit still carries Orca's error envelope on stdout.
+            if (typeof cause?.stdout === 'string' && cause.stdout.trim()) {
+                stdout = cause.stdout;
+            }
+            else {
+                throw err;
+            }
+        }
+        return parseEnvelope(stdout);
+    };
+}
+/**
+ * Fail fast when no Orca runtime answers on this machine. `orca status` never
+ * fails itself, so `runtime.reachable` is the signal. Orca is never started
+ * implicitly: on a headless oven host `orca open` would launch a desktop app.
+ */
+export async function assertOrcaReachable(orca) {
+    const status = await orca(['status']);
+    const runtime = isRecord(status) ? status.runtime : undefined;
+    if (isRecord(runtime) && runtime.reachable === true) {
+        return;
+    }
+    const state = isRecord(runtime) && typeof runtime.state === 'string'
+        ? runtime.state
+        : 'unknown';
+    throw new Error(`Orca runtime not reachable (state: ${state}). Start Orca on this machine (desktop app or "orca serve") and retry.`);
+}

package/dist/src/preset.d.ts

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

package/dist/src/preset.js

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

package/dist/src/workspace.d.ts

@@ -0,0 +1,88 @@
+import type { BbWorkspace, EnsuredWorkspace, WorkspacePlugin } from '@bakers-build/conductor/contract';
+import type { ConductorLogger, RootGitExec } from '@bakers-build/core';
+import { type OrcaExec } from './orca-cli.js';
+export type GitExec = (args: string[]) => Promise<string>;
+export type Sleep = (ms: number) => Promise<void>;
+/**
+ * The overview terminal a FRESH worktree opens. `{identifier}`, `{branch}`,
+ * `{title}` and `{worktreePath}` expand in both; `open: {}` opens nothing.
+ */
+export interface OrcaOpenLayout {
+    command?: string;
+    title?: string;
+}
+export declare const DEFAULT_OPEN_LAYOUT: OrcaOpenLayout;
+/** Above Orca's 30 s worktree scan cache, so one rescan always fits. */
+export declare const DEFAULT_ADOPT_TIMEOUT_MS = 35000;
+export declare const defaultSleep: Sleep;
+export declare const noopLogger: ConductorLogger;
+/**
+ * Wait until Orca resolves `path` as a worktree. Orca adopts worktrees made
+ * with plain git by rescanning `git worktree list`, which it caches for up to
+ * 30 s, so a fresh worktree is `selector_not_found` for a while.
+ */
+export declare function waitForAdoption(orca: OrcaExec, path: string, timeoutMs: number, sleep: Sleep): Promise<void>;
+/** `git worktree list --porcelain` records; the main checkout comes first. */
+export declare function porcelainEntries(output: string): {
+    path: string;
+    branch: string | null;
+}[];
+export interface OrcaWorkspaceOptions {
+    /** Main clone (a git repo) that Orca registers and worktrees branch from. */
+    root: string;
+    /** Relative dir (under root) for new worktrees. Default `.bakers-worktrees`. */
+    worktreeDir?: string;
+    /** Base ref for new branches. Default: the upstream of the root's HEAD. */
+    baseBranch?: string;
+    /** Overview terminal of a fresh worktree. Unset → {@link DEFAULT_OPEN_LAYOUT}. */
+    open?: OrcaOpenLayout;
+    adoptTimeoutMs?: number;
+    execOrca?: OrcaExec;
+    execGit?: GitExec;
+    logger?: ConductorLogger;
+    sleep?: Sleep;
+}
+/**
+ * Per-ticket worktree hosted in Orca. The worktree is created with plain git on
+ * the exact ticket branch — `orca worktree create` can neither take an existing
+ * branch nor keep a name it considers taken — and Orca adopts it.
+ */
+export declare class OrcaWorkspace implements BbWorkspace {
+    private readonly options;
+    private readonly root;
+    private readonly execOrca;
+    private readonly execGit;
+    private readonly open;
+    private readonly logger;
+    private readonly sleep;
+    /** Fresh worktrees awaiting {@link applyOpenLayout}; one-shot. */
+    private readonly pendingOpen;
+    constructor(options: OrcaWorkspaceOptions);
+    ensure(_identifier: string, branch?: string, baseRefOverride?: string): Promise<EnsuredWorkspace>;
+    /** Register the root with Orca once and make its git worktrees visible. */
+    private registerRepo;
+    private isRegisteredWorktree;
+    private refExists;
+    /** Check out the ticket branch as it is — never reset (`-B`) or renamed. */
+    private addWorktree;
+    /**
+     * Open the overview terminal of a worktree the latest {@link ensure} created.
+     * A reused worktree has none pending, so reattaching never duplicates it.
+     * Best-effort: a failure is logged, never thrown, so it cannot wedge dispatch.
+     */
+    applyOpenLayout(path: string, ctx: {
+        identifier: string;
+        branch: string;
+        title: string;
+    }): Promise<void>;
+}
+export declare function orcaWorkspace(opts?: {
+    /** Explicit repo-root override; otherwise derived from the git common dir. */
+    root?: string;
+    worktreeDir?: string;
+    baseBranch?: string;
+    open?: OrcaOpenLayout;
+    adoptTimeoutMs?: number;
+    /** Overrideable git exec for root derivation (tests). */
+    execGit?: RootGitExec;
+}): WorkspacePlugin;

package/dist/src/workspace.js

@@ -0,0 +1,241 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { renderTemplate, resolveBaseRef, truncateOpenTabTitle, validateBranch, } from '@bakers-build/addon-herdr/shared';
+import { loadInstructions } from '@bakers-build/addon-workspace-git';
+import { deriveCheckoutRoot, exec } from '@bakers-build/core';
+import { assertOrcaReachable, createOrcaExec, isRecord, OrcaError, } from './orca-cli.js';
+export const DEFAULT_OPEN_LAYOUT = {
+    command: 'bakers ui --ticket {identifier}',
+    title: '{identifier} · {title}',
+};
+/** Above Orca's 30 s worktree scan cache, so one rescan always fits. */
+export const DEFAULT_ADOPT_TIMEOUT_MS = 35_000;
+const ADOPT_POLL_MS = 1000;
+export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+/**
+ * Wait until Orca resolves `path` as a worktree. Orca adopts worktrees made
+ * with plain git by rescanning `git worktree list`, which it caches for up to
+ * 30 s, so a fresh worktree is `selector_not_found` for a while.
+ */
+export async function waitForAdoption(orca, path, timeoutMs, sleep) {
+    const attempts = Math.max(1, Math.ceil(timeoutMs / ADOPT_POLL_MS));
+    for (let i = 0; i < attempts; i++) {
+        try {
+            await orca(['worktree', 'show', '--worktree', `path:${path}`]);
+            return;
+        }
+        catch (err) {
+            if (!(err instanceof OrcaError) || err.code !== 'selector_not_found') {
+                throw err;
+            }
+        }
+        if (i < attempts - 1)
+            await sleep(ADOPT_POLL_MS);
+    }
+    throw new Error(`Orca did not pick up worktree ${path} within ${Math.round(timeoutMs / 1000)}s`);
+}
+/** `git worktree list --porcelain` records; the main checkout comes first. */
+export function porcelainEntries(output) {
+    return output
+        .split('\n\n')
+        .map((record) => {
+        const lines = record.split('\n');
+        const path = lines.find((l) => l.startsWith('worktree '));
+        const branch = lines.find((l) => l.startsWith('branch '));
+        return {
+            path: path ? path.slice('worktree '.length).trim() : '',
+            branch: branch
+                ? branch
+                    .slice('branch '.length)
+                    .trim()
+                    .replace(/^refs\/heads\//, '')
+                : null,
+        };
+    })
+        .filter((e) => e.path);
+}
+/**
+ * Per-ticket worktree hosted in Orca. The worktree is created with plain git on
+ * the exact ticket branch — `orca worktree create` can neither take an existing
+ * branch nor keep a name it considers taken — and Orca adopts it.
+ */
+export class OrcaWorkspace {
+    options;
+    root;
+    execOrca;
+    execGit;
+    open;
+    logger;
+    sleep;
+    /** Fresh worktrees awaiting {@link applyOpenLayout}; one-shot. */
+    pendingOpen = new Set();
+    constructor(options) {
+        this.options = options;
+        this.root = resolve(options.root);
+        this.execOrca = options.execOrca ?? createOrcaExec();
+        this.execGit = options.execGit ?? ((args) => exec('git', args));
+        // `??`, not `||`: an explicit `open: {}` must survive as the opt-out.
+        this.open = options.open ?? DEFAULT_OPEN_LAYOUT;
+        this.logger = options.logger ?? noopLogger;
+        this.sleep = options.sleep ?? defaultSleep;
+    }
+    async ensure(_identifier, branch, baseRefOverride) {
+        if (branch === undefined) {
+            throw new Error('orca workspace requires a branch name');
+        }
+        validateBranch(branch);
+        await assertOrcaReachable(this.execOrca);
+        await this.registerRepo();
+        const path = resolve(this.root, this.options.worktreeDir ?? '.bakers-worktrees', branch);
+        const created = !(await this.isRegisteredWorktree(path));
+        if (created) {
+            await this.addWorktree(branch, path, baseRefOverride);
+        }
+        await waitForAdoption(this.execOrca, path, this.options.adoptTimeoutMs ?? DEFAULT_ADOPT_TIMEOUT_MS, this.sleep);
+        if (created) {
+            this.pendingOpen.add(path);
+        }
+        return { path, instructions: loadInstructions(path), created };
+    }
+    /** Register the root with Orca once and make its git worktrees visible. */
+    async registerRepo() {
+        const listed = await this.execOrca(['repo', 'list']);
+        const repos = isRecord(listed) && Array.isArray(listed.repos) ? listed.repos : [];
+        const known = repos.some((r) => isRecord(r) &&
+            typeof r.path === 'string' &&
+            resolve(r.path) === this.root);
+        if (!known) {
+            await this.execOrca(['repo', 'add', '--path', this.root]);
+        }
+        // Idempotent; without it Orca's sidebar hides worktrees it did not create.
+        await this.execOrca([
+            'repo',
+            'set',
+            '--repo',
+            `path:${this.root}`,
+            '--external-worktree-visibility',
+            'show',
+        ]);
+    }
+    async isRegisteredWorktree(path) {
+        const output = await this.execGit([
+            '-C',
+            this.root,
+            'worktree',
+            'list',
+            '--porcelain',
+        ]);
+        return (porcelainEntries(output).some((e) => e.path === path) && existsSync(path));
+    }
+    async refExists(ref) {
+        try {
+            await this.execGit([
+                '-C',
+                this.root,
+                'rev-parse',
+                '--verify',
+                '--quiet',
+                `${ref}^{commit}`,
+            ]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Check out the ticket branch as it is — never reset (`-B`) or renamed. */
+    async addWorktree(branch, path, baseRefOverride) {
+        const add = ['-C', this.root, 'worktree', 'add'];
+        if (await this.refExists(`refs/heads/${branch}`)) {
+            await this.execGit([...add, path, branch]);
+            return;
+        }
+        try {
+            await this.execGit(['-C', this.root, 'fetch', 'origin', branch]);
+        }
+        catch {
+            // Non-fatal: the branch is simply not on origin (yet).
+        }
+        if (await this.refExists(`refs/remotes/origin/${branch}`)) {
+            await this.execGit([
+                ...add,
+                '--track',
+                '-b',
+                branch,
+                path,
+                `origin/${branch}`,
+            ]);
+            return;
+        }
+        const base = await resolveBaseRef(this.root, this.execGit, {
+            ...(this.options.baseBranch
+                ? { baseBranch: this.options.baseBranch }
+                : {}),
+            ...(baseRefOverride !== undefined ? { override: baseRefOverride } : {}),
+        });
+        await this.execGit([...add, '-b', branch, path, ...(base ? [base] : [])]);
+    }
+    /**
+     * Open the overview terminal of a worktree the latest {@link ensure} created.
+     * A reused worktree has none pending, so reattaching never duplicates it.
+     * Best-effort: a failure is logged, never thrown, so it cannot wedge dispatch.
+     */
+    async applyOpenLayout(path, ctx) {
+        if (!this.pendingOpen.delete(path) || this.open.command === undefined) {
+            return;
+        }
+        const vars = {
+            identifier: ctx.identifier,
+            branch: ctx.branch,
+            title: ctx.title,
+            worktreePath: path,
+        };
+        try {
+            await this.execOrca([
+                'terminal',
+                'create',
+                '--worktree',
+                `path:${path}`,
+                '--title',
+                renderTemplate(this.open.title ?? '{identifier} · {title}', {
+                    ...vars,
+                    title: truncateOpenTabTitle(ctx.title),
+                }),
+                '--command',
+                renderTemplate(this.open.command, vars),
+            ]);
+        }
+        catch (err) {
+            this.logger.warn({ branch: ctx.branch, worktree: path, err: String(err) }, 'orca overview terminal failed (best-effort, ignored)');
+        }
+    }
+}
+export function orcaWorkspace(opts = {}) {
+    return {
+        kind: 'workspace',
+        id: 'orca',
+        requiredModules: [],
+        async createWorkspace(config, deps) {
+            const root = await deriveCheckoutRoot(config.config_path, {
+                ...(opts.root !== undefined ? { override: opts.root } : {}),
+                ...(opts.execGit ? { execGit: opts.execGit } : {}),
+            });
+            return new OrcaWorkspace({
+                root,
+                ...(opts.worktreeDir ? { worktreeDir: opts.worktreeDir } : {}),
+                ...(opts.baseBranch ? { baseBranch: opts.baseBranch } : {}),
+                ...(opts.open ? { open: opts.open } : {}),
+                ...(opts.adoptTimeoutMs !== undefined
+                    ? { adoptTimeoutMs: opts.adoptTimeoutMs }
+                    : {}),
+                ...(deps?.logger ? { logger: deps.logger } : {}),
+            });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@bakers-build/addon-orca",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2-next.194",
+  "description": "bakers.build Orca integration: executor + per-ticket worktree workspace hosted in Orca.",
+  "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://git.key-tec.de/bakers-build/bakers-build.git",
+    "directory": "bakers-cli/addons/orca"
+  },
+  "dependencies": {
+    "@bakers-build/addon-herdr": "^0.1.2-next.194",
+    "@bakers-build/addon-workspace-git": "^0.1.2-next.194"
+  },
+  "peerDependencies": {
+    "@bakers-build/conductor": "^0.1.2-next.194",
+    "@bakers-build/core": "^0.1.2-next.194"
+  }
+}