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

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/ui
 
-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 project-first cockpit: the `bakers ui` command plugin (renderer resolved dynamically).
+
+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/bun-runtime.d.ts

@@ -0,0 +1,84 @@
+/**
+ * BB-326 — `@opentui/core` reaches its Zig core through FFI, which Node does
+ * not expose before 26.1 (and then only behind `--experimental-ffi`). So the
+ * cockpit runs under the `bun` that `@bakers-build/addon-bakers-ui` installs.
+ *
+ * `process.versions.bun` is the loop guard: it is defined under Bun and nowhere
+ * else, so a re-exec can never recurse and no sentinel variable is introduced.
+ * `--print-config` deliberately stays on Node — it is what a human runs when the
+ * cockpit will not start, and a diagnostic that needs the thing it diagnoses is
+ * worth nothing.
+ *
+ * `injectedRenderer` is the same argument one step further: the runtime is
+ * needed by the DYNAMICALLY-resolved `@bakers-build/addon-bakers-ui`, so a caller that
+ * supplies its own `runUi` never reaches OpenTUI and must not be re-execed.
+ */
+export declare function shouldReExecUnderBun(input: {
+    bunVersion?: string | undefined;
+    noBun?: string | undefined;
+    printConfig: boolean;
+    injectedRenderer?: boolean | undefined;
+}): boolean;
+/**
+ * Resolve the `bun` executable from the renderer addon's own base — the same
+ * dynamic seam `loadBbUiModule` resolves the renderer through, so the one
+ * dynamic edge in this package stays one edge.
+ *
+ * The manifest is read with a plain `readFileSync` rather than through the
+ * resolver: `createRequire(...).resolve()` gives an absolute path, and reading a
+ * known path needs no module system. `bun`'s manifest is resolved by name
+ * (`bun/package.json`) because the launcher's location is the thing we are
+ * looking up; its `bin` entry is a relative path from the manifest's directory.
+ */
+export declare function resolveBunBinary(bases: string[]): string | undefined;
+export type LibcFamily = 'glibc' | 'musl' | 'unknown';
+/**
+ * BB-326 (A1) — which C library is this host running?
+ *
+ * Two evidence sources, cheapest first, both injected so the answer never
+ * depends on the machine the test runs on:
+ *
+ *  - `/proc/self/maps` (~0.1 ms) names the interpreter the kernel ACTUALLY
+ *    mapped into this process. That is the strongest signal available: a glibc
+ *    box with a musl-compat package installed has `/lib/ld-musl-x86_64.so.1` on
+ *    disk but never maps it, so the `existsSync` shortcut would misread it.
+ *  - the node report's `header.glibcVersionRuntime` (~4.6 ms) — present on
+ *    glibc, absent on musl. It needs no filesystem, which is why it is the
+ *    fallback for a container that hides `/proc`. Verified on all four
+ *    combinations: node+glibc `"2.43"`, bun+glibc `"2.43"`, node+musl absent,
+ *    bun+musl absent (node:22-alpine).
+ *
+ * Non-Linux returns `unknown` and NOT `musl`: the report header omits
+ * `glibcVersionRuntime` on macOS and Windows too, so reading its absence as
+ * musl would mislabel every mac. musl is a Linux question.
+ *
+ * Inconclusive is `unknown`, and `unknown` changes nothing — glibc is upstream's
+ * default and the overwhelmingly common case, so a failed probe must degrade to
+ * today's behaviour rather than to a guess.
+ */
+export declare function detectLibcFamily(probe: {
+    platform: string;
+    readProcSelfMaps: () => string | undefined;
+    readReportLibc: () => LibcFamily;
+}): LibcFamily;
+/** The real probe. Every leg is wrapped: an inconclusive read must not throw. */
+export declare function nodeLibcFamily(): LibcFamily;
+/**
+ * BB-326 (A1) — make the cockpit start on musl with no manual step.
+ *
+ * `@opentui/core@0.5.1` selects its native platform package from
+ * `process.env.OPENTUI_LIBC` and DEFAULTS TO GLIBC — it runs no probe of its
+ * own. Both prebuilts are always on disk (npm and pnpm filter optional deps by
+ * `os`/`cpu`, never by libc), so on Alpine the wrong one loads and the first
+ * frame dies with `Error loading shared library ld-linux-x86-64.so.2 (needed by
+ * libopentui.so)`. Requiring the user to export the variable IS a manual step,
+ * so A1 is only met once we set it.
+ *
+ * An explicit value always wins: an operator who exports `OPENTUI_LIBC=glibc`
+ * on a musl box is doing something deliberate, and a probe must not overrule
+ * them. Because a set value short-circuits BEFORE `detect` is called, the Bun
+ * child — which inherits this env — never pays for the probe a second time.
+ */
+export declare function applyOpentuiLibc(env: NodeJS.ProcessEnv, detect?: () => LibcFamily): void;
+/** Replace this process with the same command under Bun. Never returns. */
+export declare function reExecUnderBun(bin: string, argv: string[]): never;

package/dist/src/bun-runtime.js

@@ -0,0 +1,149 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+/**
+ * BB-326 — `@opentui/core` reaches its Zig core through FFI, which Node does
+ * not expose before 26.1 (and then only behind `--experimental-ffi`). So the
+ * cockpit runs under the `bun` that `@bakers-build/addon-bakers-ui` installs.
+ *
+ * `process.versions.bun` is the loop guard: it is defined under Bun and nowhere
+ * else, so a re-exec can never recurse and no sentinel variable is introduced.
+ * `--print-config` deliberately stays on Node — it is what a human runs when the
+ * cockpit will not start, and a diagnostic that needs the thing it diagnoses is
+ * worth nothing.
+ *
+ * `injectedRenderer` is the same argument one step further: the runtime is
+ * needed by the DYNAMICALLY-resolved `@bakers-build/addon-bakers-ui`, so a caller that
+ * supplies its own `runUi` never reaches OpenTUI and must not be re-execed.
+ */
+export function shouldReExecUnderBun(input) {
+    if (input.printConfig)
+        return false;
+    if (input.injectedRenderer)
+        return false;
+    if (input.bunVersion !== undefined)
+        return false;
+    if (input.noBun !== undefined && input.noBun !== '')
+        return false;
+    return true;
+}
+/**
+ * Resolve the `bun` executable from the renderer addon's own base — the same
+ * dynamic seam `loadBbUiModule` resolves the renderer through, so the one
+ * dynamic edge in this package stays one edge.
+ *
+ * The manifest is read with a plain `readFileSync` rather than through the
+ * resolver: `createRequire(...).resolve()` gives an absolute path, and reading a
+ * known path needs no module system. `bun`'s manifest is resolved by name
+ * (`bun/package.json`) because the launcher's location is the thing we are
+ * looking up; its `bin` entry is a relative path from the manifest's directory.
+ */
+export function resolveBunBinary(bases) {
+    for (const base of bases) {
+        try {
+            const addon = createRequire(base).resolve('@bakers-build/addon-bakers-ui');
+            const manifest = createRequire(addon).resolve('bun/package.json');
+            const { bin } = JSON.parse(readFileSync(manifest, 'utf8'));
+            const relative = typeof bin === 'string' ? bin : bin?.bun;
+            if (relative)
+                return join(dirname(manifest), relative);
+        }
+        catch {
+            // try the next base
+        }
+    }
+    return undefined;
+}
+/**
+ * The dynamic linker musl installs. Matched as a path segment ending in `.so`
+ * rather than a bare `includes('ld-musl')`, so an unrelated mapped file whose
+ * NAME happens to carry the string cannot be mistaken for the interpreter.
+ */
+const MUSL_INTERPRETER = /\/ld-musl-[^/\s]*\.so/;
+/**
+ * BB-326 (A1) — which C library is this host running?
+ *
+ * Two evidence sources, cheapest first, both injected so the answer never
+ * depends on the machine the test runs on:
+ *
+ *  - `/proc/self/maps` (~0.1 ms) names the interpreter the kernel ACTUALLY
+ *    mapped into this process. That is the strongest signal available: a glibc
+ *    box with a musl-compat package installed has `/lib/ld-musl-x86_64.so.1` on
+ *    disk but never maps it, so the `existsSync` shortcut would misread it.
+ *  - the node report's `header.glibcVersionRuntime` (~4.6 ms) — present on
+ *    glibc, absent on musl. It needs no filesystem, which is why it is the
+ *    fallback for a container that hides `/proc`. Verified on all four
+ *    combinations: node+glibc `"2.43"`, bun+glibc `"2.43"`, node+musl absent,
+ *    bun+musl absent (node:22-alpine).
+ *
+ * Non-Linux returns `unknown` and NOT `musl`: the report header omits
+ * `glibcVersionRuntime` on macOS and Windows too, so reading its absence as
+ * musl would mislabel every mac. musl is a Linux question.
+ *
+ * Inconclusive is `unknown`, and `unknown` changes nothing — glibc is upstream's
+ * default and the overwhelmingly common case, so a failed probe must degrade to
+ * today's behaviour rather than to a guess.
+ */
+export function detectLibcFamily(probe) {
+    if (probe.platform !== 'linux')
+        return 'unknown';
+    const maps = probe.readProcSelfMaps();
+    if (maps !== undefined)
+        return MUSL_INTERPRETER.test(maps) ? 'musl' : 'glibc';
+    return probe.readReportLibc();
+}
+/** The real probe. Every leg is wrapped: an inconclusive read must not throw. */
+export function nodeLibcFamily() {
+    return detectLibcFamily({
+        platform: process.platform,
+        readProcSelfMaps: () => {
+            try {
+                return readFileSync('/proc/self/maps', 'utf8');
+            }
+            catch {
+                return undefined;
+            }
+        },
+        readReportLibc: () => {
+            try {
+                const report = process.report.getReport();
+                return report.header?.glibcVersionRuntime ? 'glibc' : 'musl';
+            }
+            catch {
+                return 'unknown';
+            }
+        },
+    });
+}
+/**
+ * BB-326 (A1) — make the cockpit start on musl with no manual step.
+ *
+ * `@opentui/core@0.5.1` selects its native platform package from
+ * `process.env.OPENTUI_LIBC` and DEFAULTS TO GLIBC — it runs no probe of its
+ * own. Both prebuilts are always on disk (npm and pnpm filter optional deps by
+ * `os`/`cpu`, never by libc), so on Alpine the wrong one loads and the first
+ * frame dies with `Error loading shared library ld-linux-x86-64.so.2 (needed by
+ * libopentui.so)`. Requiring the user to export the variable IS a manual step,
+ * so A1 is only met once we set it.
+ *
+ * An explicit value always wins: an operator who exports `OPENTUI_LIBC=glibc`
+ * on a musl box is doing something deliberate, and a probe must not overrule
+ * them. Because a set value short-circuits BEFORE `detect` is called, the Bun
+ * child — which inherits this env — never pays for the probe a second time.
+ */
+export function applyOpentuiLibc(env, detect = nodeLibcFamily) {
+    const current = env.OPENTUI_LIBC;
+    if (current !== undefined && current !== '')
+        return;
+    if (detect() === 'musl')
+        env.OPENTUI_LIBC = 'musl';
+}
+/** Replace this process with the same command under Bun. Never returns. */
+export function reExecUnderBun(bin, argv) {
+    const result = spawnSync(bin, argv.slice(1), {
+        stdio: 'inherit',
+        env: process.env,
+    });
+    process.exit(result.status ?? 1);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { type HereContext, isTicketIdentifier, isUuid, normalizeRepoUrl, type ParsedTarget, parseTarget, parseTicketIdentifierFromBranch, resolveHere, type TargetInputs, UI_VIEW_MODES, type UiInitialRoute, type UiViewMode, } from './route.js';
+export { cmdUi, default, type RunBbUiOptions, type UiDeps } from './ui.js';
+export { type HomeConnection, type ProjectRooting, resolveAgentCommand, resolveProjectRooting, } from './ui-home.js';

package/dist/src/index.js

@@ -0,0 +1,10 @@
+// BB-201 / BB-219: `@bakers-build/ui` — the `bakers ui` command plugin. Its
+// connection is resolved by core's `loadBbConfig` (explicit → project
+// walk-up → home → shipped fallback), so running it inside a project uses that
+// project's control plane; this package owns no precedence rule of its own.
+// The default export is the `BbCommandPlugin` the host mounts; `cmdUi` + the
+// bootstrap helpers are exported for tests.
+// BB-223: the deep-link grammar (the pure CLI seam).
+export { isTicketIdentifier, isUuid, normalizeRepoUrl, parseTarget, parseTicketIdentifierFromBranch, resolveHere, UI_VIEW_MODES, } from './route.js';
+export { cmdUi, default } from './ui.js';
+export { resolveAgentCommand, resolveProjectRooting, } from './ui-home.js';

package/dist/src/preset.d.ts

@@ -0,0 +1,2 @@
+import type { BbPreset } from '@bakers-build/core';
+export declare const commands: BbPreset['commands'];

package/dist/src/preset.js

@@ -0,0 +1,8 @@
+export const commands = (acc) => [
+    ...acc,
+    {
+        name: 'ui',
+        plugin: '@bakers-build/ui',
+        describe: 'interactive terminal UI: dashboard, projects, tickets',
+    },
+];

package/dist/src/route.d.ts

@@ -0,0 +1,119 @@
+/** How a ticket target is rendered. Mirrors the Drupal `bb_ticket` view modes. */
+export type UiViewMode = 'full' | 'teaser' | 'board_card';
+/** The known `--view` modes, in the order error messages list them. */
+export declare const UI_VIEW_MODES: readonly UiViewMode[];
+/**
+ * A deep-link target as the CLI understands it — *unresolved*: it says what to
+ * look up and how, never what screen results. Crosses both package boundaries
+ * (`RunBbUiOptions` → `BbUiLauncherOptions` → `TuiOptions`) and is mirrored
+ * structurally in the renderer, per the `HomeConnection` precedent (Finding 6).
+ */
+export interface UiInitialRoute {
+    kind: 'ticket' | 'project' | 'run';
+    /**
+     * How `value` must be looked up. `'repo'` is the `--here` project rung: the
+     * value is a NORMALISED remote URL (`host/path`), matched client-side against
+     * the `bb_project.repository.url` of every project (spec Decision 3).
+     */
+    /**
+     * `'origin'` (BB-544) is a ticket looked up by its origin issue — `#19`,
+     * `bakers#19` or the issue URL — which the server's `filter[search]` resolves.
+     */
+    by: 'uuid' | 'identifier' | 'name' | 'repo' | 'origin';
+    value: string;
+    /** Drupal view mode for a ticket target; default 'full'. */
+    view?: UiViewMode | undefined;
+    /** Set when the target came from `--here`; error messages only. */
+    fromBranch?: string | undefined;
+}
+/** The raw argv inputs `parseTarget` reads (commander's parsed options). */
+export interface TargetInputs {
+    target?: string | undefined;
+    ticket?: string | undefined;
+    project?: string | undefined;
+    run?: string | undefined;
+    here?: boolean | undefined;
+    view?: string | undefined;
+}
+/**
+ * What the grammar made of the argv: nothing (the dashboard), a `--here`
+ * request that still needs the ladder walked, or a finished route.
+ */
+export type ParsedTarget = {
+    kind: 'here';
+    view?: UiViewMode | undefined;
+} | {
+    kind: 'route';
+    route: UiInitialRoute;
+};
+/** True for an `8-4-4-4-12` hex UUID (case-insensitive). */
+export declare function isUuid(value: string): boolean;
+/** True for a `KEY-123` ticket identifier (case-insensitive). */
+export declare function isTicketIdentifier(value: string): boolean;
+/**
+ * The ticket identifier a branch name carries, uppercased, or `null`.
+ * Pure and offline — the `--here` ticket rung never needs the network.
+ */
+export declare function parseTicketIdentifierFromBranch(branch: string): string | null;
+/**
+ * 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 declare function parseTarget(inputs: TargetInputs): ParsedTarget | undefined;
+/**
+ * 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 declare function normalizeRepoUrl(raw: string | undefined): string | undefined;
+/** Everything `resolveHere` needs, all injected — two git reads, nothing else. */
+export interface HereContext {
+    cwd: string;
+    view?: UiViewMode | undefined;
+    /** The current branch of `cwd` (git resolves it per worktree). May reject. */
+    readBranch: (cwd: string) => Promise<string>;
+    /**
+     * The cwd's `origin` remote URL, raw. Git resolves it per worktree too, and a
+     * worktree shares its main clone's remote — which is exactly the right answer
+     * (spec Decision 3). May reject (not a repo, no `origin`).
+     */
+    readRemoteUrl: (cwd: string) => Promise<string>;
+}
+/**
+ * `--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 declare function resolveHere(ctx: HereContext): Promise<UiInitialRoute>;