@bakers-build/addon-ports 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/addon-ports
 
-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 ports command plugin: discover a ticket worktree's running services (DDEV, Designbook, ad-hoc listeners) and bring shareable tunnels up and down. The command half of BB-475; usable without the cockpit half.
+
+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/claim-share.d.ts

@@ -0,0 +1,33 @@
+import type { ClaimedDiscovery, ClaimedService } from './claims.js';
+/** Eligible = a healthy (or prepared-Drupal-passthrough) claim with a rule. */
+export declare function eligible(service: ClaimedService): boolean;
+/** Every eligible service of `discovery` is shared on every "bring up
+ *  everything" pass — BB-681 review C4: an already-`applied` record is
+ *  never short-circuited here either, because the SPEC requires every
+ *  up/down/reap to reconcile the complete desired set (a dead Quick process
+ *  or a lost frp registration must recover on a repeated `up`, not only when
+ *  the recorded fields disagree with the freshly observed rule).
+ *  `bringUp`/`reconcileTunnels` own the actual idempotence (a live, matching
+ *  route is a cheap no-op there); this is the pure selection half of "bring
+ *  up everything" (spec v5's `bakers ports up` with no key, and the `tunnel`
+ *  inbox message), kept separate from the I/O loop so a test drives it
+ *  without a real `bringUp`. BB-681 review over-engineering pass: no
+ *  per-record state check is needed any more — every call site already has
+ *  no further reason to pass `records` here, so it was dropped. */
+export declare function servicesToShare(discovery: ClaimedDiscovery): ClaimedService[];
+/** One `bringUp` outcome, paired with the service it was for. */
+export interface ShareOutcome<R> {
+    readonly service: ClaimedService;
+    readonly result: R;
+}
+/**
+ * BB-676 pass-6 review cleanup — the "bring up everything" I/O loop, shared
+ * between `bakers ports up` (no key) and the `tunnel` inbox message so the two
+ * "share everything" entry points cannot drift apart: one call per selected
+ * service, in order, keeping going past a single failure, every outcome kept
+ * for the caller to report its own way (stdout lines vs. a Markdown list).
+ */
+export declare function shareAll<R extends {
+    ok: boolean;
+    message: string;
+}>(services: readonly ClaimedService[], bringUp: (service: ClaimedService) => Promise<R>): Promise<ShareOutcome<R>[]>;

package/dist/src/claim-share.js

@@ -0,0 +1,38 @@
+// BB-676 spec v5 — shared "bring up everything eligible" predicate AND I/O
+// loop (`shareAll`, pass-6 review cleanup), used by both the `tunnel` inbox
+// message and `bakers ports up` with no service key, so the two "share
+// everything" entry points cannot drift apart.
+/** Eligible = a healthy (or prepared-Drupal-passthrough) claim with a rule. */
+export function eligible(service) {
+    return service.rules.length > 0;
+}
+/** Every eligible service of `discovery` is shared on every "bring up
+ *  everything" pass — BB-681 review C4: an already-`applied` record is
+ *  never short-circuited here either, because the SPEC requires every
+ *  up/down/reap to reconcile the complete desired set (a dead Quick process
+ *  or a lost frp registration must recover on a repeated `up`, not only when
+ *  the recorded fields disagree with the freshly observed rule).
+ *  `bringUp`/`reconcileTunnels` own the actual idempotence (a live, matching
+ *  route is a cheap no-op there); this is the pure selection half of "bring
+ *  up everything" (spec v5's `bakers ports up` with no key, and the `tunnel`
+ *  inbox message), kept separate from the I/O loop so a test drives it
+ *  without a real `bringUp`. BB-681 review over-engineering pass: no
+ *  per-record state check is needed any more — every call site already has
+ *  no further reason to pass `records` here, so it was dropped. */
+export function servicesToShare(discovery) {
+    return discovery.services.filter(eligible);
+}
+/**
+ * BB-676 pass-6 review cleanup — the "bring up everything" I/O loop, shared
+ * between `bakers ports up` (no key) and the `tunnel` inbox message so the two
+ * "share everything" entry points cannot drift apart: one call per selected
+ * service, in order, keeping going past a single failure, every outcome kept
+ * for the caller to report its own way (stdout lines vs. a Markdown list).
+ */
+export async function shareAll(services, bringUp) {
+    const outcomes = [];
+    for (const service of services) {
+        outcomes.push({ service, result: await bringUp(service) });
+    }
+    return outcomes;
+}

package/dist/src/claims.d.ts

@@ -0,0 +1,39 @@
+import type { ClaimContext, ClaimedDiscovery, HttpProbe, RawDiscovery } from '@bakers-build/addon-ddev';
+import { type HostDiscoveryDeps } from './discovery.js';
+import { type ServiceRules } from './service-config.js';
+export type { ClaimContext, ClaimedDiscovery, ClaimedService, ClaimStatus, HttpProbe, TunnelRule, } from '@bakers-build/addon-ddev';
+/**
+ * `https://<lowercase-ticket>-<key>.<zone>` — pure, no I/O (spec: naming stays
+ * a pure exported function). Throws on an invalid ticket, key, zone or a
+ * combined label over 63 bytes; never truncates.
+ */
+export declare function publicHostname(ticket: string, key: string, zone: string): string;
+/**
+ * Inspector ports a command line names: `--inspect`, `--inspect-brk`,
+ * `--inspect-wait` or `--inspect-port`, as `=port`, `=host:port` or a separate
+ * argument; a bare `--inspect*` means the default 9229. Pure, for tests.
+ */
+export declare function inspectorPorts(cmdline: string): number[];
+/** Run claimers in precedence order over one raw discovery pass, specific
+ *  before broad: configured process entries (with the default `storybook`),
+ *  DDEV (generic `web`/`web-<host>` naming), then the opt-in all-Node rule.
+ *  DDEV's keys never change: a process claim on a key DDEV produced becomes
+ *  `<key>-<port>`. */
+export declare function claimServices(raw: RawDiscovery, ctx: ClaimContext, rules: ServiceRules): Promise<ClaimedDiscovery>;
+/** `.ddev/config.yaml`'s own raw-text reader — kept distinct from
+ *  `HostDiscoveryDeps` since it is plain file I/O, not a command exec. */
+export interface ConfigFileDeps {
+    /** `null` for ENOENT; throwing is reserved for a real I/O failure. */
+    readFile(path: string): Promise<string | null>;
+}
+/** Compose raw lookup and claims — the `list`/`up` entry point.
+ *  Host-listener discovery (process-rule candidates) stays local; DDEV's own
+ *  container discovery AND effective-host discovery (`ddev utility
+ *  configyaml`) are delegated to `@bakers-build/addon-ddev`, never read/called
+ *  directly here. */
+export declare function discoverClaimedServices(worktree: string, deps: HostDiscoveryDeps & ConfigFileDeps, opts: {
+    readonly ticket: string;
+    readonly zone: string;
+    readonly probe: HttpProbe;
+    readonly rules: ServiceRules;
+}): Promise<ClaimedDiscovery>;

package/dist/src/claims.js

@@ -0,0 +1,286 @@
+// BB-676 Task 2 (spec v2 split) — claim raw observations into named,
+// tunnel-ready services. A claimer consumes raw IDENTITIES (array indices
+// into one `RawDiscovery` pass), never a global port number: two containers
+// or two site rules can share a port, so "port already seen" would silently
+// merge them. Claimers run in precedence order (configured processes, DDEV,
+// then the opt-in all-Node rule — specific before broad); each receives only
+// what the previous claimer left in `remaining`.
+//
+// This package owns naming/reconciliation and the process claimers (host
+// processes matched by the ports addon's `services` settings, no Docker
+// call). Which processes are tunnelled is configuration, not code here; an
+// unmatched listener stays unclaimed — still no numeric-port fallback. DDEV's own discovery/claim logic — everything
+// that fires `docker` or interprets `HTTP(S)_EXPOSE`/`VIRTUAL_HOST`, and the
+// neutral `{key, service, hostHeader?, insecureTls?}` rules it emits (BB-681:
+// no CMS-specific addon or policy layer over its output any more) — lives in
+// `@bakers-build/addon-ddev` (operator decision 2026-10-15: ports must not fire
+// Docker calls itself). `claimServices` below runs the process rules, then
+// DDEV, then all-Node, over one merged raw-discovery pass.
+import { claimDdev, discoverDdevHosts, discoverDdevPorts, parseWebExtraExposedPorts, } from '@bakers-build/addon-ddev';
+import { discoverHostPorts } from './discovery.js';
+import { DEFAULT_STORYBOOK, LABEL_RE, } from './service-config.js';
+const TICKET_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*-\d+$/;
+/**
+ * `https://<lowercase-ticket>-<key>.<zone>` — pure, no I/O (spec: naming stays
+ * a pure exported function). Throws on an invalid ticket, key, zone or a
+ * combined label over 63 bytes; never truncates.
+ */
+export function publicHostname(ticket, key, zone) {
+    if (!zone || /[:/*]/.test(zone) || zone.includes('://')) {
+        throw new Error(`invalid zone (must be a bare hostname): ${zone}`);
+    }
+    const t = ticket.toLowerCase();
+    if (!TICKET_RE.test(t)) {
+        throw new Error(`invalid ticket identifier (expected project-key-number): ${ticket}`);
+    }
+    const k = key.toLowerCase();
+    if (!LABEL_RE.test(k)) {
+        throw new Error(`invalid service key (must be a DNS-safe label): ${key}`);
+    }
+    const label = `${t}-${k}`;
+    if (Buffer.byteLength(label, 'utf8') > 63) {
+        throw new Error(`combined label exceeds 63 bytes: ${label}`);
+    }
+    return `${label}.${zone}`;
+}
+/** The Node default inspector port. */
+const INSPECTOR_DEFAULT_PORT = 9229;
+const INSPECT_FLAG_RE = /^--inspect(-brk|-wait|-port)?(?:=(.*))?$/;
+const PORT_VALUE_RE = /^(?:.*:)?(\d+)$/;
+/**
+ * Inspector ports a command line names: `--inspect`, `--inspect-brk`,
+ * `--inspect-wait` or `--inspect-port`, as `=port`, `=host:port` or a separate
+ * argument; a bare `--inspect*` means the default 9229. Pure, for tests.
+ */
+export function inspectorPorts(cmdline) {
+    const tokens = cmdline.split(/\s+/);
+    const ports = [];
+    tokens.forEach((token, i) => {
+        const flag = INSPECT_FLAG_RE.exec(token);
+        if (!flag)
+            return;
+        const value = flag[2] ?? tokens[i + 1] ?? '';
+        const port = PORT_VALUE_RE.exec(value)?.[1];
+        if (port !== undefined)
+            ports.push(Number(port));
+        else if (flag[2] === undefined && flag[1] !== '-port')
+            ports.push(INSPECTOR_DEFAULT_PORT);
+    });
+    return ports;
+}
+/** Where a host listener answers HTTP: loopback for a loopback or wildcard
+ *  bind, else the bound address. */
+function probeOrigin(p) {
+    const a = p.hostAddress ?? '';
+    if (a.includes(':'))
+        return a === '::' || a === '::1'
+            ? `[::1]:${p.hostPort}`
+            : `[${a}]:${p.hostPort}`;
+    const loopback = a === '' ||
+        a === '*' ||
+        a === '0.0.0.0' ||
+        a === 'localhost' ||
+        a.startsWith('127.');
+    return `${loopback ? '127.0.0.1' : a}:${p.hostPort}`;
+}
+/** Probe `/json/version`: `'inspector'` for a Node inspector, `null` for no
+ *  HTTP answer at all, else `'http'`. */
+async function probeInspector(p, probe) {
+    let result;
+    try {
+        result = await probe(`http://${probeOrigin(p)}/json/version`, {
+            timeoutMs: 300,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!result)
+        return null;
+    try {
+        const browser = JSON.parse(result.body).Browser;
+        if (typeof browser === 'string' && browser.startsWith('node.js/'))
+            return 'inspector';
+    }
+    catch {
+        // Not JSON: an ordinary HTTP server.
+    }
+    return 'http';
+}
+/** A loopback `/index.json` answering as a Storybook v5 static build. */
+async function isStaticStorybook(p, probe) {
+    let result;
+    try {
+        result = await probe(`http://127.0.0.1:${p.hostPort}/index.json`, {
+            timeoutMs: 300,
+        });
+    }
+    catch {
+        return false;
+    }
+    if (!result || !result.ok)
+        return false;
+    try {
+        const b = JSON.parse(result.body);
+        return b.v === 5 && !!b.entries && typeof b.entries === 'object';
+    }
+    catch {
+        return false;
+    }
+}
+function processClaim(key, claim, p) {
+    return {
+        key,
+        claim,
+        status: 'healthy',
+        local: `http://127.0.0.1:${p.hostPort}`,
+        rawPorts: [p],
+        rules: [
+            {
+                key,
+                service: `http://127.0.0.1:${p.hostPort}`,
+                // Dev servers (Vite, VitePress, Storybook) reject a foreign Host.
+                hostHeader: `localhost:${p.hostPort}`,
+            },
+        ],
+    };
+}
+/**
+ * The process claimers over one pass: an inspector exclusion, then each
+ * configured entry in order (a match on the command line; the entry keyed
+ * `storybook` also claims a loopback static build by its `/index.json`).
+ * Further matches of one entry get `<key>-<port>`. Only worktree-owned host
+ * listeners are considered. Each listener a claimer would take is first
+ * checked for a Node inspector (port 9229, an `--inspect*` flag of its own
+ * process, or a `/json/version` probe) and stays unclaimed when it is one.
+ */
+async function claimProcesses(raw, remaining, ctx, rules) {
+    const hosts = [...remaining].filter((i) => raw[i].hostPort !== undefined && raw[i].containerId === undefined);
+    // Inspectors are never claimed but stay listed as unclaimed.
+    const blocked = new Set(hosts.filter((i) => {
+        const p = raw[i];
+        return (p.hostPort === INSPECTOR_DEFAULT_PORT ||
+            inspectorPorts(p.cmdline ?? '').includes(p.hostPort));
+    }));
+    const probed = new Map();
+    const answer = (i) => {
+        let r = probed.get(i);
+        if (!r) {
+            r = probeInspector(raw[i], ctx.probe);
+            probed.set(i, r);
+        }
+        return r;
+    };
+    const free = () => hosts.filter((i) => remaining.has(i) && !blocked.has(i));
+    // The listeners of `matched` the probe verdict lets through, by port.
+    const take = async (matched, keep) => {
+        const verdicts = await Promise.all(matched.map(answer));
+        const ok = matched.filter((_, n) => keep(verdicts[n]));
+        matched.forEach((i, n) => {
+            if (verdicts[n] === 'inspector')
+                blocked.add(i);
+        });
+        return ok.sort((a, b) => raw[a].hostPort - raw[b].hostPort);
+    };
+    const services = [];
+    for (const rule of rules.entries) {
+        const needle = rule.match.toLowerCase();
+        const candidates = free();
+        const matched = candidates.filter((i) => raw[i].cmdline?.toLowerCase().includes(needle));
+        if (rule.key === DEFAULT_STORYBOOK.key) {
+            const statics = await Promise.all(candidates
+                .filter((i) => !matched.includes(i) &&
+                (raw[i].hostAddress === '127.0.0.1' ||
+                    raw[i].hostAddress === 'localhost'))
+                .map(async (i) => (await isStaticStorybook(raw[i], ctx.probe)) ? i : undefined));
+            for (const i of statics)
+                if (i !== undefined)
+                    matched.push(i);
+        }
+        // Explicit entries claim without a probe answer, like Storybook always did.
+        const ok = await take(matched, (r) => r !== 'inspector');
+        ok.forEach((i, idx) => {
+            remaining.delete(i);
+            const p = raw[i];
+            services.push(processClaim(idx === 0 ? rule.key : `${rule.key}-${p.hostPort}`, 'process', p));
+        });
+    }
+    const allNode = async () => {
+        if (!rules.allNode)
+            return [];
+        const node = free().filter((i) => {
+            const exe = (raw[i].cmdline ?? '').split(/\s+/)[0].split('/').pop();
+            return exe === 'node' || exe === 'nodejs';
+        });
+        // Fail closed: no HTTP answer at all is not claimed by the broad rule.
+        const ok = await take(node, (r) => r === 'http');
+        return ok.map((i) => {
+            remaining.delete(i);
+            const p = raw[i];
+            return processClaim(`node-${p.hostPort}`, 'node', p);
+        });
+    };
+    return { services, allNode };
+}
+/** Run claimers in precedence order over one raw discovery pass, specific
+ *  before broad: configured process entries (with the default `storybook`),
+ *  DDEV (generic `web`/`web-<host>` naming), then the opt-in all-Node rule.
+ *  DDEV's keys never change: a process claim on a key DDEV produced becomes
+ *  `<key>-<port>`. */
+export async function claimServices(raw, ctx, rules) {
+    const remaining = new Set(raw.ports.map((_, i) => i));
+    const processes = await claimProcesses(raw.ports, remaining, ctx, rules);
+    const ddev = claimDdev(raw.ports, remaining, ctx);
+    const nodes = await processes.allNode();
+    const ddevKeys = new Set(ddev.map((s) => s.key));
+    const renamed = [...processes.services, ...nodes].map((s) => {
+        if (!ddevKeys.has(s.key))
+            return s;
+        const key = `${s.key}-${s.rawPorts[0].hostPort}`;
+        return { ...s, key, rules: s.rules.map((r) => ({ ...r, key })) };
+    });
+    const unclaimed = [...remaining]
+        .sort((a, b) => a - b)
+        .map((i) => raw.ports[i]);
+    return {
+        services: [...renamed, ...ddev],
+        diagnostics: raw.diagnostics,
+        unclaimed,
+    };
+}
+/** Compose raw lookup and claims — the `list`/`up` entry point.
+ *  Host-listener discovery (process-rule candidates) stays local; DDEV's own
+ *  container discovery AND effective-host discovery (`ddev utility
+ *  configyaml`) are delegated to `@bakers-build/addon-ddev`, never read/called
+ *  directly here. */
+export async function discoverClaimedServices(worktree, deps, opts) {
+    const [host, ddev, hostsResult, ddevConfigYaml] = await Promise.all([
+        discoverHostPorts(worktree, deps),
+        discoverDdevPorts(worktree, deps),
+        discoverDdevHosts(worktree, deps),
+        deps.readFile(`${worktree.replace(/\/+$/, '')}/.ddev/config.yaml`),
+    ]);
+    // BB-681 review I1: a failed `ddev utility configyaml` read must leave a
+    // diagnostic, not silently drop every `web-<host>` alias claim — without
+    // one, `shouldKeepTunnelRecord` sees no evidence at all for a vanished
+    // alias record and `reap` deletes a route that may still be perfectly
+    // live, only unobserved this pass.
+    const raw = {
+        ports: [...host.ports, ...ddev.ports],
+        diagnostics: [
+            ...host.diagnostics,
+            ...ddev.diagnostics,
+            ...(hostsResult.ok
+                ? []
+                : [{ source: 'ddev-hosts', message: hostsResult.reason }]),
+        ],
+    };
+    return claimServices(raw, {
+        worktree,
+        ticket: opts.ticket,
+        zone: opts.zone,
+        probe: opts.probe,
+        webExtraExposedPortNames: parseWebExtraExposedPorts(ddevConfigYaml),
+        ...(hostsResult.ok ? { hosts: hostsResult.hosts } : {}),
+    }, opts.rules);
+}

package/dist/src/config.d.ts

@@ -0,0 +1,40 @@
+import { type PortsTransport } from './transport.js';
+/** The ports addon entry's `with`, transport-agnostic: `transport.use`
+ *  names the package to load; `transport.with` is whatever settings that
+ *  package's own factory understands. This loader validates only this
+ *  generic shape — never a specific transport's own field names. */
+export interface PortsMachineConfig {
+    readonly transport: {
+        readonly use: string;
+        readonly with?: unknown;
+    };
+}
+/** No ports addon entry (or one without a transport) in either scope. */
+export declare const PORTS_NEEDS_ENTRY = "bakers ports needs '@bakers-build/addon-ports' in addons[] of ~/.bakers/machine.config.js or .bakers/conductor.config.js, with with.transport.use naming a transport package; see docs/addons/ports";
+/** The retired top-level machine `ports` key. */
+export declare const PORTS_RETIRED = "machine ports is retired: move it to addons: [{ use: '@bakers-build/addon-ports', with: { transport: \u2026 } }]";
+/** Throw the remediation when the machine config still carries `ports`. */
+export declare function assertNoMachinePorts(): Promise<void>;
+/** `addons[@bakers-build/addon-ports].with.<key> <message>` per finding. */
+export declare function withProblems(value: unknown): string[];
+/** `portsSettings` plus the retired machine `ports` check — the transport
+ *  path; discovery (`list`) reads settings without it. */
+export declare function portsSettings(worktree: string): Promise<unknown>;
+/**
+ * The effective `@bakers-build/addon-ports` entry's `with` for `worktree`, merged
+ * by the preset's `mergeWith` (the machine wins). Undefined when neither
+ * scope lists the addon. Throws for a malformed `with` in either scope.
+ */
+export declare function readPortsSettings(worktree: string): Promise<unknown>;
+/**
+ * Resolve, load and construct the configured ports transport from the ports
+ * addon entry's `with` (`settings`).
+ * Resolution bases, in order: `home` (a project-local transport package),
+ * the running `bakers` host's own install (realpath'd, so the three built-in
+ * provider packages resolve through a symlinked global install), then
+ * `process.cwd()`.
+ * Every failure — missing config, unresolvable package, no default export,
+ * a factory that rejects its settings, or a malformed `PortsTransport`
+ * result — throws a safe diagnostic, never a raw crash.
+ */
+export declare function loadPortsTransport(settings: unknown, home: string): Promise<PortsTransport>;

package/dist/src/config.js

@@ -0,0 +1,158 @@
+// BB-681 Task 2 — resolve the machine's configured ports transport package
+// by name, reusing the engine's own ESLint-style module resolver
+// (`resolveModuleEslintStyle`, hoisted from the conductor's plugin loader)
+// rather than inventing a second one.
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { machineUiConfigPath, projectConductorConfigPath, readConfigAddons, readEffectiveAddon, readMachineContext, resolveModuleEslintStyle, } from '@bakers-build/core';
+import { checkWith } from './service-config.js';
+import { assertPortsTransport, InvalidTransportModuleError, } from './transport.js';
+/**
+ * Resolution bases rooted at the running `bakers` HOST install, usable from
+ * both the CLI (which gets a `BbCommandHost`) and the inbox handler (which
+ * does not: `oven start`/`once` dispatches inbox messages from inside
+ * the SAME long-running `bakers` process, never a subprocess). The three
+ * built-in transport packages are declared only on `bakers-cli/host/package.json`
+ * (never on `@bakers-build/addon-ports`, which would cycle back through
+ * `addon-ports/transport` — see the spec's "no core dependency on provider
+ * implementations"), so they resolve from the host's own `node_modules`, not
+ * from wherever this file happens to be installed. `process.argv[1]` is the
+ * entry script for every invocation shape (`bakers ports …` and the conductor
+ * process alike); a test harness with no such argv falls back to this
+ * module's own URL. The global install is a symlink
+ * (`~/.nvm/.../bin/bakers` → `lib/node_modules/@bakers-build/bakers/bin/bakers`):
+ * `createRequire`'s `node_modules` walk follows the real path, not the
+ * symlink's directory, so the base must be realpath'd first (BB-681 review
+ * C1). The repo's own dev/test-workspace launcher (`bakers-cli/bin/bakers`) is a
+ * SEPARATE package from the host and imports `../host/dist/src/host.js`
+ * directly, so `entry`'s own realpath'd directory has no `node_modules` with
+ * the transport packages either — mirror that launcher's own relative import
+ * as a second candidate (BB-681 review N6).
+ */
+function hostInstallBases() {
+    const entry = process.argv[1];
+    if (!entry)
+        return [import.meta.url];
+    let real;
+    try {
+        real = realpathSync(entry);
+    }
+    catch {
+        real = entry;
+    }
+    const entryUrl = pathToFileURL(real);
+    return [entryUrl.href, new URL('../host/dist/src/host.js', entryUrl).href];
+}
+/** No ports addon entry (or one without a transport) in either scope. */
+export const PORTS_NEEDS_ENTRY = "bakers ports needs '@bakers-build/addon-ports' in addons[] of ~/.bakers/machine.config.js or .bakers/conductor.config.js, with with.transport.use naming a transport package; see docs/addons/ports";
+/** The retired top-level machine `ports` key. */
+export const PORTS_RETIRED = "machine ports is retired: move it to addons: [{ use: '@bakers-build/addon-ports', with: { transport: … } }]";
+/** Throw the remediation when the machine config still carries `ports`. */
+export async function assertNoMachinePorts() {
+    const machine = await readMachineContext();
+    if (machine.ports !== undefined)
+        throw new Error(PORTS_RETIRED);
+}
+const PORTS_SPEC = '@bakers-build/addon-ports';
+/** `addons[@bakers-build/addon-ports].with.<key> <message>` per finding. */
+export function withProblems(value) {
+    return checkWith(value).map((f) => `addons[${PORTS_SPEC}].with${f.key ? `.${f.key}` : ''} ${f.message}`);
+}
+/** Throw the first malformed ports `with` in the machine or project config,
+ *  naming the file and key — a bad setting is never silently ignored. */
+async function assertValidScopes(worktree) {
+    const project = projectConductorConfigPath(worktree);
+    for (const path of [machineUiConfigPath(), project]) {
+        if (path === undefined)
+            continue;
+        for (const entry of await readConfigAddons(path)) {
+            if (typeof entry === 'string' ||
+                (entry?.use ?? entry?.name) !== PORTS_SPEC)
+                continue;
+            const [problem] = withProblems(entry.with ?? entry.options);
+            if (problem)
+                throw new Error(`${path}: ${problem}`);
+        }
+    }
+}
+/** `portsSettings` plus the retired machine `ports` check — the transport
+ *  path; discovery (`list`) reads settings without it. */
+export async function portsSettings(worktree) {
+    await assertNoMachinePorts();
+    return readPortsSettings(worktree);
+}
+/**
+ * The effective `@bakers-build/addon-ports` entry's `with` for `worktree`, merged
+ * by the preset's `mergeWith` (the machine wins). Undefined when neither
+ * scope lists the addon. Throws for a malformed `with` in either scope.
+ */
+export async function readPortsSettings(worktree) {
+    await assertValidScopes(worktree);
+    const found = await readEffectiveAddon('@bakers-build/addon-ports', {
+        cwd: worktree,
+        bases: [...hostInstallBases(), import.meta.url],
+    });
+    if (found === undefined || typeof found.entry === 'string')
+        return undefined;
+    return found.entry.with ?? found.entry.options;
+}
+/**
+ * Resolve, load and construct the configured ports transport from the ports
+ * addon entry's `with` (`settings`).
+ * Resolution bases, in order: `home` (a project-local transport package),
+ * the running `bakers` host's own install (realpath'd, so the three built-in
+ * provider packages resolve through a symlinked global install), then
+ * `process.cwd()`.
+ * Every failure — missing config, unresolvable package, no default export,
+ * a factory that rejects its settings, or a malformed `PortsTransport`
+ * result — throws a safe diagnostic, never a raw crash.
+ */
+export async function loadPortsTransport(settings, home) {
+    const ports = settings;
+    if (!ports ||
+        typeof ports !== 'object' ||
+        typeof ports.transport !== 'object' ||
+        ports.transport === null ||
+        typeof ports.transport.use !== 'string' ||
+        ports.transport.use === '') {
+        throw new Error(PORTS_NEEDS_ENTRY);
+    }
+    const spec = ports.transport.use;
+    // `resolveModuleEslintStyle`'s bases are node module PARENTS — a bare
+    // directory path (no trailing slash) is otherwise treated by
+    // `createRequire` as a FILE, which starts `node_modules` lookup one level
+    // too high. Same `pathToFileURL(dir + '/')` shape `load-bakers-config.ts`
+    // already uses for its own bases.
+    const resolved = resolveModuleEslintStyle(spec, [
+        pathToFileURL(`${home}/`).href,
+        ...hostInstallBases(),
+        pathToFileURL(`${process.cwd()}/`).href,
+    ]);
+    if (resolved === undefined) {
+        throw new Error(`bakers ports cannot resolve transport package '${spec}'`);
+    }
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(resolved).href));
+    }
+    catch (err) {
+        throw new InvalidTransportModuleError(spec, `failed to load: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const factory = mod.default;
+    if (typeof factory !== 'function') {
+        throw new InvalidTransportModuleError(spec, 'module has no default export factory');
+    }
+    let transport;
+    try {
+        transport = await factory(ports.transport.with, {
+            home,
+        });
+    }
+    catch (err) {
+        if (err instanceof InvalidTransportModuleError)
+            throw err;
+        throw new Error(`ports transport '${spec}' rejected its settings: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    assertPortsTransport(transport, spec);
+    return transport;
+}

package/dist/src/core.d.ts

@@ -0,0 +1,10 @@
+export type { RawDiagnostic, RawDiscovery, RawPort, Tri, } from '@bakers-build/addon-ddev';
+export { type ClaimContext, type ClaimedDiscovery, type ClaimedService, type ClaimStatus, claimServices, discoverClaimedServices, type HttpProbe, publicHostname, type TunnelRule, } from './claims.js';
+export { assertNoMachinePorts, loadPortsTransport, PORTS_NEEDS_ENTRY, PORTS_RETIRED, type PortsMachineConfig, portsSettings, readPortsSettings, withProblems, } from './config.js';
+export { discoverHostPorts, type HostDiscoveryDeps, parseSocketListeners, type SocketListener, } from './discovery.js';
+export { type LockDeps, LockTimeoutError, nodeLockDeps, tunnelLockPath, withTunnelLock, } from './lock.js';
+export { readTunnelState, type StateDeps } from './state.js';
+export { assertPortsTransport, InvalidTransportModuleError, type PortsTransport, type PortsTransportFactory, } from './transport.js';
+export { bringUp as bringUpTunnel, type OperationContext, type OpResult as TunnelOpResult, type ReapResult as TunnelReapResult, readTunnelState as readMachineTunnelRecords, reap as reapTunnels, reconcileTunnels, type TunnelOpsDeps, takeDown as takeDownTunnel, } from './tunnel-ops.js';
+export { assertIdentity, emptyState, type MachineTunnelState, nodeTunnelStateDeps, type ReadResult, readMachineTunnelState, readValidatedMachineState, type TunnelDesiredRecord, type TunnelIdentity, TunnelIdentityMismatchError, type TunnelStateDeps, tunnelStatePath, upsertRecord, writeMachineTunnelState, } from './tunnel-state.js';
+export type { TunnelRecord, TunnelState } from './types.js';

package/dist/src/core.js

@@ -0,0 +1,15 @@
+// BB-475 — the ports package's pure surface, free of the command wiring.
+//
+// Exported as `@bakers-build/addon-ports/core` so the cockpit package (BB-475 stage
+// 6) consumes the discovery, transport and state functions and their types
+// WITHOUT pulling in commander or the CLI entry. Discovery and transport are the
+// same code the commands run; the cockpit renders their result and drives their
+// actions.
+export { claimServices, discoverClaimedServices, publicHostname, } from './claims.js';
+export { assertNoMachinePorts, loadPortsTransport, PORTS_NEEDS_ENTRY, PORTS_RETIRED, portsSettings, readPortsSettings, withProblems, } from './config.js';
+export { discoverHostPorts, parseSocketListeners, } from './discovery.js';
+export { LockTimeoutError, nodeLockDeps, tunnelLockPath, withTunnelLock, } from './lock.js';
+export { readTunnelState } from './state.js';
+export { assertPortsTransport, InvalidTransportModuleError, } from './transport.js';
+export { bringUp as bringUpTunnel, readTunnelState as readMachineTunnelRecords, reap as reapTunnels, reconcileTunnels, takeDown as takeDownTunnel, } from './tunnel-ops.js';
+export { assertIdentity, emptyState, nodeTunnelStateDeps, readMachineTunnelState, readValidatedMachineState, TunnelIdentityMismatchError, tunnelStatePath, upsertRecord, writeMachineTunnelState, } from './tunnel-state.js';