@bakers-build/ui 0.0.0-stage → 0.1.0-next.42

package/dist/src/route.js

@@ -0,0 +1,271 @@
+// BB-223: the pure CLI seam of `bakers ui` deep links.
+//
+// This module owns the *grammar* — argv in, an unresolved `UiInitialRoute` out —
+// and the `--here` ladder. It performs no I/O of its own: git, the filesystem
+// and the conductor registry all enter through injected seams, so the whole
+// grammar is testable offline and a conflict/parse failure costs no network
+// round-trip (spec Decisions 1, 3, 4, 6, 13).
+//
+// Resolving a route against the control plane is deliberately NOT here: the
+// entry has no JSON:API client (spec Finding 1). That happens in the renderer,
+// in `@bakers-build/addon-bakers-ui`'s `resolveRoute`, still before the TUI takes the
+// terminal (spec Decision 5).
+/** The known `--view` modes, in the order error messages list them. */
+export const UI_VIEW_MODES = [
+    'full',
+    'teaser',
+    'board_card',
+];
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `<project-key>-<number>`, case-insensitive (Decision 4). One dash only, so a
+ *  UUID can never match it. */
+const IDENTIFIER_RE = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+/**
+ * The ticket identifier carried by a branch name, first match wins. Every
+ * convention places the identifier before the title slug and `capBranchName()`
+ * never truncates it (Finding 3), so the first match is the right one.
+ */
+const BRANCH_IDENTIFIER_RE = /(?:^|[/_-])([A-Za-z][A-Za-z0-9]*-\d+)(?=$|[/_-])/;
+/** An origin issue reference: `#19`, `bakers#19`, or an http(s) URL. Only shape
+ *  is checked here; the server resolves the alias and the URL. */
+const ORIGIN_RE = /^(?:[A-Za-z0-9._-]*#\d+|https?:\/\/\S+)$/;
+const ACCEPTED_FORMS = "accepted forms: BB-221 (a ticket identifier), '#19' or 'bakers#19' or an " +
+    "issue URL (an origin issue), 'ticket:<id|uuid>', 'project:<name|uuid>', " +
+    "'run:<uuid>'";
+/** True for an `8-4-4-4-12` hex UUID (case-insensitive). */
+export function isUuid(value) {
+    return UUID_RE.test(value);
+}
+/** True for a `KEY-123` ticket identifier (case-insensitive). */
+export function isTicketIdentifier(value) {
+    return IDENTIFIER_RE.test(value);
+}
+/**
+ * The ticket identifier a branch name carries, uppercased, or `null`.
+ * Pure and offline — the `--here` ticket rung never needs the network.
+ */
+export function parseTicketIdentifierFromBranch(branch) {
+    const match = BRANCH_IDENTIFIER_RE.exec(branch);
+    return match?.[1] ? match[1].toUpperCase() : null;
+}
+/** Validate a raw `--view` value against the known modes. */
+function parseViewMode(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (UI_VIEW_MODES.includes(raw)) {
+        return raw;
+    }
+    throw new Error(`bakers ui: unknown --view mode '${raw}'. Known modes: ${UI_VIEW_MODES.join(', ')}.`);
+}
+/** A ticket target from a raw value: a UUID by id, else an identifier by name. */
+function ticketTarget(value) {
+    if (isUuid(value))
+        return { kind: 'ticket', by: 'uuid', value };
+    if (isTicketIdentifier(value)) {
+        return { kind: 'ticket', by: 'identifier', value: value.toUpperCase() };
+    }
+    throw new Error(`bakers ui: '${value}' is not a ticket identifier or UUID — ${ACCEPTED_FORMS}.`);
+}
+/** A project target: a UUID by id, else the label verbatim (labels are
+ *  case-sensitive Drupal entity labels — Decision 4). */
+function projectTarget(value) {
+    return isUuid(value)
+        ? { kind: 'project', by: 'uuid', value }
+        : { kind: 'project', by: 'name', value };
+}
+/** A run target — UUIDs only; there is no human-readable run handle. */
+function runTarget(value) {
+    if (!isUuid(value)) {
+        throw new Error(`bakers ui: a run target must be a UUID, got '${value}'.`);
+    }
+    return { kind: 'run', by: 'uuid', value };
+}
+/** Parse the positional form: an optional `kind:` prefix, else a bare identifier. */
+function parsePositional(raw) {
+    // Before the `kind:` split: an issue URL carries a colon of its own.
+    if (ORIGIN_RE.test(raw))
+        return { kind: 'ticket', by: 'origin', value: raw };
+    const colon = raw.indexOf(':');
+    if (colon >= 0) {
+        const prefix = raw.slice(0, colon);
+        const value = raw.slice(colon + 1);
+        if (prefix !== 'ticket' && prefix !== 'project' && prefix !== 'run') {
+            throw new Error(`bakers ui: unknown target kind '${prefix}'. ` +
+                "Known kinds: 'ticket:', 'project:', 'run:'.");
+        }
+        if (value === '') {
+            throw new Error(`bakers ui: '${raw}' has an empty value — ${ACCEPTED_FORMS}.`);
+        }
+        if (prefix === 'ticket')
+            return ticketTarget(value);
+        if (prefix === 'project')
+            return projectTarget(value);
+        return runTarget(value);
+    }
+    // Bare: strictly a ticket identifier. A UUID is ambiguous by construction —
+    // it does not say which kind — and never guessed (Decision 1).
+    if (isUuid(raw)) {
+        throw new Error(`bakers ui: '${raw}' is ambiguous — a bare UUID does not say which kind. ` +
+            "Use 'ticket:<uuid>', 'project:<uuid>' or 'run:<uuid>'.");
+    }
+    return ticketTarget(raw);
+}
+/**
+ * The grammar: at most ONE target source (the positional, `--ticket`,
+ * `--project`, `--run`, `--here`) plus the orthogonal `--view` modifier.
+ *
+ * Returns `undefined` for no target at all (the dashboard, AC-4), `{kind:'here'}`
+ * when the ladder still has to be walked, else the finished route. Throws — with
+ * a message naming exactly what went wrong — on a conflict or an unparseable
+ * form; the caller turns that into a stderr line and exit 1 before any network
+ * work happens.
+ */
+export function parseTarget(inputs) {
+    const supplied = [];
+    if (inputs.target !== undefined && inputs.target !== '') {
+        supplied.push(`the positional target '${inputs.target}'`);
+    }
+    if (inputs.ticket !== undefined)
+        supplied.push('--ticket');
+    if (inputs.project !== undefined)
+        supplied.push('--project');
+    if (inputs.run !== undefined)
+        supplied.push('--run');
+    if (inputs.here === true)
+        supplied.push('--here');
+    if (supplied.length > 1) {
+        throw new Error(`bakers ui: conflicting targets — ${supplied.join(', ')} were all supplied. ` +
+            'Give at most one of: a positional target, --ticket, --project, --run, --here.');
+    }
+    const view = parseViewMode(inputs.view);
+    if (supplied.length === 0)
+        return undefined;
+    if (inputs.here === true) {
+        return { kind: 'here', view: view ?? 'full' };
+    }
+    const target = inputs.target !== undefined && inputs.target !== ''
+        ? parsePositional(inputs.target)
+        : inputs.ticket !== undefined
+            ? ticketTarget(inputs.ticket)
+            : inputs.project !== undefined
+                ? projectTarget(inputs.project)
+                : runTarget(inputs.run);
+    // `--view` describes how a TICKET renders. A project screen has no view mode,
+    // and `run:` already means "the ticket's Runs tab", so pairing it with a
+    // compact block is contradictory rather than resolvable (Decision 13).
+    if (view !== undefined && target.kind === 'project') {
+        throw new Error('bakers ui: --view applies to ticket targets only, but the target is a project. ' +
+            'Drop --view, or name a ticket.');
+    }
+    if (view !== undefined && target.kind === 'run') {
+        throw new Error("bakers ui: --view cannot be combined with a 'run:' target — 'run:' already " +
+            "means the owning ticket's Runs tab. Use 'ticket:<id> --view <mode>' instead.");
+    }
+    return {
+        kind: 'route',
+        route: target.kind === 'project' ? target : { ...target, view: view ?? 'full' },
+    };
+}
+/**
+ * A git remote URL reduced to a comparable `host/path` identity: scheme,
+ * userinfo, port and a trailing `.git` (and trailing slashes) dropped, the whole
+ * thing lowercased. Returns `undefined` for anything that carries no host+path.
+ *
+ * This is REQUIRED, not cosmetic (spec Decision 3): git and the control plane
+ * disagree on form. Measured in this repo — `git remote get-url origin` yields
+ * `git@git.key-tec.de:bakers-build/bakers-build.git` while `bb_project.repository.url` holds
+ * `ssh://git@git.key-tec.de/bakers-build/bakers-build.git`. Both must reduce to
+ * `git.key-tec.de/bakers-build/bakers-build` or the `--here` project rung never matches.
+ *
+ * | raw                                     | normalised          |
+ * |-----------------------------------------|---------------------|
+ * | `git@host:bakers-build/bakers-build.git`              | `host/bakers-build/bakers-build`  |
+ * | `ssh://git@host/bakers-build/bakers-build.git`        | `host/bakers-build/bakers-build`  |
+ * | `ssh://git@host:2222/bakers-build/bakers-build.git`   | `host/bakers-build/bakers-build`  |
+ * | `https://host/bakers-build/bakers-build.git`          | `host/bakers-build/bakers-build`  |
+ */
+export function normalizeRepoUrl(raw) {
+    const trimmed = (raw ?? '').trim();
+    if (trimmed === '')
+        return undefined;
+    let host;
+    let path;
+    // `scheme://[user@]host[:port]/path` — checked FIRST, so an `ssh://…:2222/…`
+    // port is never mistaken for the scp form's `host:path` colon.
+    const withScheme = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/(.+)$/.exec(trimmed);
+    if (withScheme?.[1] !== undefined) {
+        const rest = withScheme[1];
+        const slash = rest.indexOf('/');
+        if (slash < 0)
+            return undefined;
+        host = rest.slice(0, slash);
+        path = rest.slice(slash + 1);
+    }
+    else {
+        // The scp-like form `[user@]host:path` — what `git remote get-url` emits
+        // for an ssh clone. A bare local path has no colon and falls out here.
+        const scp = /^(?:[^/@]+@)?([^/:]+):(.+)$/.exec(trimmed);
+        if (scp?.[1] === undefined || scp[2] === undefined)
+            return undefined;
+        host = scp[1];
+        path = scp[2];
+    }
+    host = host
+        .replace(/^[^@]*@/, '')
+        .replace(/:\d+$/, '')
+        .toLowerCase();
+    path = path
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/i, '')
+        .replace(/\/+$/, '')
+        .toLowerCase();
+    if (host === '' || path === '')
+        return undefined;
+    return `${host}/${path}`;
+}
+/**
+ * `--here`: derive the target from the cwd (spec Decision 3).
+ *
+ * ```
+ * branch carries a ticket identifier?  → that TICKET   (feat/bb-223-… → BB-223)
+ * else: the cwd's git remote           → the PROJECT(s) whose repository claims it
+ * else                                 → a named error
+ * ```
+ *
+ * The BRANCH decides the first rung, not git mechanics: a worktree on a
+ * non-ticket branch and the main clone on a ticket branch both come out right.
+ *
+ * The project rung stops HERE at a normalised repo identity — matching it
+ * against `bb_project.repository` needs a JSON:API client, which the entry does
+ * not have (Finding 1), so `by: 'repo'` travels to the renderer's `resolveRoute`
+ * and the ambiguity ruling (one match / a picker / an error) is made there
+ * (Decisions 5 + 14).
+ */
+export async function resolveHere(ctx) {
+    const branch = await ctx.readBranch(ctx.cwd).then((b) => b.trim(), () => '');
+    const identifier = branch === '' ? null : parseTicketIdentifierFromBranch(branch);
+    if (identifier !== null) {
+        return {
+            kind: 'ticket',
+            by: 'identifier',
+            value: identifier,
+            view: ctx.view ?? 'full',
+            fromBranch: branch,
+        };
+    }
+    const remote = await ctx.readRemoteUrl(ctx.cwd).then((r) => r.trim(), () => '');
+    const repo = normalizeRepoUrl(remote);
+    if (repo === undefined) {
+        const got = remote === '' ? '' : `, got '${remote}'`;
+        throw new Error(`bakers ui --here: could not derive a project from '${ctx.cwd}' — ` +
+            `no usable git remote (looked at 'origin'${got}).\n` +
+            "  Run 'bakers ui' and press Tab for the project list, or 'bakers ui project:<name>' to open one directly.");
+    }
+    return {
+        kind: 'project',
+        by: 'repo',
+        value: repo,
+        ...(branch !== '' ? { fromBranch: branch } : {}),
+    };
+}

package/dist/src/ui-home.d.ts

@@ -0,0 +1,69 @@
+import { type MachineContext } from '@bakers-build/core';
+/**
+ * The resolved control-plane connection passed to the renderer launcher.
+ * A structural mirror of `@bakers-build/addon-bakers-ui`'s `HomeConnection` — kept
+ * local so this package needs NO compile-time dependency on the renderer (it
+ * resolves the renderer dynamically, ESLint-style, at runtime).
+ */
+export interface HomeConnection {
+    baseUrl: string;
+    jsonapiPrefix?: string | undefined;
+    authPlugins: unknown[];
+    configPath?: string | undefined;
+}
+/**
+ * Resolve the agent-launch command builder from the home config. Turns a TUI
+ * prompt into the shell command herdr runs. Defaults to `claude` (an empty
+ * prompt yields the bare launch command). A machine context may name a
+ * different `agent_command` binary.
+ */
+export declare function resolveAgentCommand(machine: Partial<MachineContext> & {
+    agent_command?: string;
+}): (prompt: string) => string;
+/** Where `bakers ui` roots the agents it launches, and which project they belong to. */
+export interface ProjectRooting {
+    cwd: string;
+    /**
+     * The `.bakers` dir of the project we are standing in, when there is one.
+     *
+     * The ui hands this over rather than a resolved project name: matching it
+     * against a conductor's `workspace_root` needs the control plane, and the
+     * client that reaches it first exists in the renderer (BB-232). Undefined
+     * outside any project.
+     */
+    bakersDir?: string | undefined;
+}
+/**
+ * Decide the agents' working directory (BB-219 AC-9).
+ *
+ * The trigger is the **cwd**, deliberately not the winning connection config:
+ * "which connection did we resolve" and "which project am I standing in" are
+ * different questions, and binding them would let an explicit `--config`
+ * silently relocate the agents' working directory.
+ *
+ * Standing **in** a project (core's walk-up finds a `.bakers/` project dir that
+ * is not the user's own `~/.bakers`), the cwd is that repo's **root**. Otherwise
+ * the agents root at the home dir and the cockpit opens with no default group —
+ * an honest empty cockpit rather than a guess.
+ *
+ * The project name and this machine's conductor id used to come from a local
+ * registry file, which BB-232 deleted. Both now resolve in the renderer's
+ * `run()` — `Entity/conductor/Data/own-conductor.ts`, reached through the
+ * launcher's `bakersDir` — from the conductor record whose `workspace_root`
+ * equals this dir: the same data, from the store that also knows whether the
+ * conductor is alive, and matched by the same exact normalised path comparison
+ * the registry lookup used.
+ *
+ * The marker is core's `findProjectBbDir` — "is there a `.bakers/` here" —
+ * NOT the connection walk-up `findBbConfig`. Since BB-230 the latter skips
+ * an engine-only `conductor.config.js`, which BB-218 makes the canonical repo
+ * shape, so keying on it would leave the most common project rooted at home.
+ *
+ * `~/.bakers` is excluded for the same reason core labels it `home`: the walk-up
+ * reaches it from every directory under `$HOME`, so counting it would make
+ * every such directory look like "a project rooted at `$HOME`".
+ *
+ * Pure with respect to precedence — the walk-up is core's; this helper owns no
+ * filesystem probe of its own.
+ */
+export declare function resolveProjectRooting(cwd: string, homeDir: string): ProjectRooting;

package/dist/src/ui-home.js

@@ -0,0 +1,67 @@
+// BB-201 (was BB-194), BB-219: bootstrap builders for `bakers ui`. Pure
+// functions that turn the machine context (identity), the conductor registry
+// and the cwd into everything `runBbUi` needs. The CONNECTION itself is not
+// built here — `ui.ts` asks core's `loadBbConfig` for it, so this package
+// holds no connection-precedence rule of its own (AC-6).
+import { dirname, resolve } from 'node:path';
+import { findProjectBbDir, homeBbDir, shellQuote, } from '@bakers-build/core';
+// BB-391: the two read/write auth-profile members are gone. A connection used
+// to declare two dropsh auth profiles that differed only by OAuth scope, and the
+// cockpit had to name one for reads and one for writes; BB-359 moved capability
+// onto OG ranks, so both resolved to the same role. The connection now declares
+// ONE default provider and nothing has to choose. AC2's grep over
+// `bakers-cli/*/src` is the guard, so the retired names are not spelled here.
+/**
+ * Resolve the agent-launch command builder from the home config. Turns a TUI
+ * prompt into the shell command herdr runs. Defaults to `claude` (an empty
+ * prompt yields the bare launch command). A machine context may name a
+ * different `agent_command` binary.
+ */
+export function resolveAgentCommand(machine) {
+    const bin = (machine.agent_command ?? '').trim() || 'claude';
+    return (prompt) => prompt.trim() === '' ? bin : `${bin} ${shellQuote(prompt)}`;
+}
+/**
+ * Decide the agents' working directory (BB-219 AC-9).
+ *
+ * The trigger is the **cwd**, deliberately not the winning connection config:
+ * "which connection did we resolve" and "which project am I standing in" are
+ * different questions, and binding them would let an explicit `--config`
+ * silently relocate the agents' working directory.
+ *
+ * Standing **in** a project (core's walk-up finds a `.bakers/` project dir that
+ * is not the user's own `~/.bakers`), the cwd is that repo's **root**. Otherwise
+ * the agents root at the home dir and the cockpit opens with no default group —
+ * an honest empty cockpit rather than a guess.
+ *
+ * The project name and this machine's conductor id used to come from a local
+ * registry file, which BB-232 deleted. Both now resolve in the renderer's
+ * `run()` — `Entity/conductor/Data/own-conductor.ts`, reached through the
+ * launcher's `bakersDir` — from the conductor record whose `workspace_root`
+ * equals this dir: the same data, from the store that also knows whether the
+ * conductor is alive, and matched by the same exact normalised path comparison
+ * the registry lookup used.
+ *
+ * The marker is core's `findProjectBbDir` — "is there a `.bakers/` here" —
+ * NOT the connection walk-up `findBbConfig`. Since BB-230 the latter skips
+ * an engine-only `conductor.config.js`, which BB-218 makes the canonical repo
+ * shape, so keying on it would leave the most common project rooted at home.
+ *
+ * `~/.bakers` is excluded for the same reason core labels it `home`: the walk-up
+ * reaches it from every directory under `$HOME`, so counting it would make
+ * every such directory look like "a project rooted at `$HOME`".
+ *
+ * Pure with respect to precedence — the walk-up is core's; this helper owns no
+ * filesystem probe of its own.
+ */
+export function resolveProjectRooting(cwd, homeDir) {
+    const bakersDir = findProjectBbDir(cwd);
+    // Core owns where `.bakers` lives; the ui never spells the path itself. No
+    // argument here: `homeDir` is the fallback cwd (the OS home), not the
+    // `.bakers` root, and an explicit argument would beat BB_HOME by design.
+    const homeDotBb = resolve(homeBbDir());
+    if (bakersDir !== undefined && resolve(bakersDir) !== homeDotBb) {
+        return { cwd: dirname(bakersDir), bakersDir };
+    }
+    return { cwd: homeDir };
+}

package/dist/src/ui.d.ts

@@ -0,0 +1,155 @@
+import { type AgentLaunchHost } from '@bakers-build/addon-herdr';
+import { type BbCommandHost, type BbCommandPlugin, type BbConnectionConfig, type MachineContext, type WorkspaceRecoveryOptions } from '@bakers-build/core';
+import { type UiInitialRoute } from './route.js';
+import { type HomeConnection } from './ui-home.js';
+/** Prompt-level agent service the renderer consumes (mirror of bakers-ui's `TuiAgentService`). */
+interface TuiAgentService {
+    launch(o: {
+        group: string;
+        cwd: string;
+        prompt: string;
+        env: Record<string, string | undefined>;
+        isNew?: boolean | undefined;
+        label?: string | undefined;
+    }): Promise<{
+        id: string;
+        group: string;
+        label: string;
+    }>;
+    list(group: string): Promise<{
+        id: string;
+        group: string;
+        label: string;
+    }[]>;
+    focus(id: string): Promise<void>;
+    hide(group: string): Promise<void>;
+    kill(id: string): Promise<void>;
+}
+/** A dropsh program (only the `parseAsync` the launcher drives). */
+interface DropshProgram {
+    parseAsync(argv: string[], opts: {
+        from: 'user';
+    }): Promise<unknown>;
+}
+/** Options for bakers-ui's `runBbUi` (mirror of its `BbUiLauncherOptions`). */
+export interface RunBbUiOptions {
+    connection: HomeConnection;
+    cwd: string;
+    project?: string | undefined;
+    agents?: TuiAgentService | undefined;
+    currentUser?: string | undefined;
+    /**
+     * The `.bakers` dir of the project the ui was started in, when there is one.
+     *
+     * Replaces the `ownConductorMachineId` the local registry used to supply
+     * (BB-232): the renderer matches this against each conductor's
+     * `workspace_root` to find which record is this machine's own — it holds the
+     * JSON:API client, and this entry does not.
+     */
+    bakersDir?: string | undefined;
+    /** BB-472 — the connection's ambient workspace uuid; the renderer resolves
+     *  its name and shows it in the chrome. Absent ⇒ no workspace suffix. */
+    workspaceId?: string | undefined;
+    /** BB-472 — the loaded connection config's absolute path, so the
+     *  workspace-picker screen can find `workspace_id`'s owning file. */
+    configPath?: string | undefined;
+    /** BB-472 — re-executes this process; the picker calls it after writing a
+     *  new workspace selection. */
+    restartProcess?: (() => void) | undefined;
+    /** Persist a product-workspace name through the conductor-owned contract. */
+    selectWorkspace?: ((name: string) => Promise<void>) | undefined;
+    createPrompt?: string | undefined;
+    buildProgram: (opts: {
+        plugins: unknown[];
+    }) => DropshProgram;
+    renderer?: ((opts: unknown) => unknown) | undefined;
+    /** BB-223: the deep-link target, still UNRESOLVED (the entry has no JSON:API
+     *  client — Finding 1). Absent ⇒ the renderer boots its dashboard (AC-4). */
+    initialRoute?: UiInitialRoute | undefined;
+    /** BB-233: the write-scoped JSON:API client. Absent ⇒ the renderer writes
+     *  through the read client and the server decides (spec Decision 1). */
+    writeClient?: unknown;
+    /** BB-373: UI extension entry MODULES core discovered from `addons[]`.
+     *  Specifiers only — this package imports none of them (spec F2). */
+    uiEntries?: readonly string[] | undefined;
+}
+/** What a write-client builder needs — everything a connection already carries. */
+export interface BuildWriteClientOptions {
+    baseUrl: string;
+    jsonapiPrefix: string;
+    stateDir?: string;
+    plugins: BbConnectionConfig['plugins'];
+}
+/** Test/composition seams for `bakers ui`. */
+export interface UiDeps {
+    /** Local operator identity; default: read the host context from disk. */
+    machine?: Partial<MachineContext>;
+    workspaceRecovery?: WorkspaceRecoveryOptions;
+    /** herdr-backed agent host; default: `herdrAgentHost(exec herdr)`. */
+    agentHost?: AgentLaunchHost;
+    /** The renderer launcher; default: the dynamically-resolved `runBbUi`. */
+    runUi?: (opts: RunBbUiOptions) => Promise<void>;
+    /** Host contract (resolveBases) for renderer resolution; default: cwd + this install. */
+    host?: BbCommandHost;
+    /** Explicit connection config (`--config`); beats project + home (AC-4). */
+    explicitConfig?: string;
+    /** Named connection selected by `--connection`. */
+    connection?: string;
+    /**
+     * `--workspace <name|uuid>` (BB-472): a ONE-SHOT override of the
+     * configured workspace for THIS process only — never written to the
+     * connection config. Resolved against the identity's reachable workspaces
+     * (`discoverBbWorkspaces`) before the ready connection loads, so an
+     * unknown or ambiguous name fails before the renderer starts.
+     */
+    workspace?: string;
+    /** Where the resolution + the rooting start; default: `process.cwd()`. */
+    cwd?: string;
+    /** Connection loader; default: core's `loadBbConfig` (the ONE rule). */
+    loadConnection?: (host: BbCommandHost, opts: {
+        cwd?: string;
+        explicit?: string | undefined;
+        connection?: string | undefined;
+        workspaceSelector?: string | undefined;
+    }) => Promise<BbConnectionConfig>;
+    /** Print the resolved connection and exit without launching the TUI (AC-7). */
+    printConfig?: boolean;
+    /** Sink for `--print-config`; default: `process.stdout.write`. */
+    stdout?: (s: string) => void;
+    /** Daily update lookup; injectable for startup ordering tests. */
+    updateCheck?: () => Promise<string | null>;
+    /** Positional `[target]` (`BB-221`, `#19`, `ticket:…`, `project:…`, `run:…`). */
+    target?: string | undefined;
+    /** `--ticket <id>`. */
+    ticket?: string | undefined;
+    /** `--project <id>`. */
+    project?: string | undefined;
+    /** `--run <uuid>`. */
+    run?: string | undefined;
+    /** `--here` — derive the target from the cwd (Decision 3). */
+    here?: boolean | undefined;
+    /** `--view <mode>` — how a ticket target renders (Decision 13). */
+    view?: string | undefined;
+    /** Current git branch of a dir; default `git branch --show-current`. */
+    readBranch?: (cwd: string) => Promise<string>;
+    /** The dir's `origin` remote URL; default `git remote get-url origin`. */
+    readRemoteUrl?: (cwd: string) => Promise<string>;
+    /** Where user-facing grammar errors go; default `process.stderr`. */
+    stderr?: (line: string) => void;
+    /** Builds the write client with the same configured identity as reads.
+     *  Injected so the write seam is testable without a live token endpoint. */
+    buildWriteClient?: (o: BuildWriteClientOptions) => Promise<unknown>;
+}
+/**
+ * `bakers ui` — launch the interactive terminal UI. Resolves the connection
+ * through core's shared ready loader (explicit → project → global), roots the agents in the project it was started in, reads the
+ * machine context for identity + the agent binary, adapts a herdr-backed agent
+ * host to the renderer's prompt-level service, and delegates to
+ * `@bakers-build/addon-bakers-ui`'s `runBbUi`. `--print-config` reports the
+ * resolution and exits without launching. `$BB_UI_PLUGIN` overrides the
+ * renderer module (dev).
+ */
+export declare function cmdUi(deps?: UiDeps): Promise<void>;
+/** The `ui` command plugin the host mounts (`bakers ui`). */
+declare const uiCommandPlugin: BbCommandPlugin;
+export default uiCommandPlugin;