@bakers-build/addon-ports 0.6.1-next.5 → 0.6.1-next.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  # @bakers-build/addon-ports
2
2
 
3
- 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.
3
+ bakers.build ports command plugin: discover a ticket worktree's running services (claimer packages' containers, Storybook, ad-hoc listeners) and bring shareable tunnels up and down. The command half of BB-475; usable without the cockpit half.
4
4
 
5
5
  Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://github.com/bakers-build/bakers-build (bakers-cli/).
@@ -1,7 +1,22 @@
1
- import type { ClaimContext, ClaimedDiscovery, HttpProbe, RawDiscovery } from '@bakers-build/addon-ddev';
2
1
  import { type HostDiscoveryDeps } from './discovery.js';
3
2
  import { type ServiceRules } from './service-config.js';
4
- export type { ClaimContext, ClaimedDiscovery, ClaimedService, ClaimStatus, HttpProbe, TunnelRule, } from '@bakers-build/addon-ddev';
3
+ import type { ClaimContext, ClaimedDiscovery, ClaimedService, HttpProbe, RawDiscovery, RawPort } from './types.js';
4
+ export type { ClaimContext, ClaimedDiscovery, ClaimedService, ClaimStatus, HttpProbe, TunnelRule, } from './types.js';
5
+ /** What a claimer's `discover` may call: a bounded command exec and a plain
6
+ * file read (`null` for a missing file). */
7
+ export type ClaimerDeps = Pick<HostDiscoveryDeps, 'run'> & ConfigFileDeps;
8
+ /** One claimer's own observations for a pass, plus the private `context` its
9
+ * `claim` reads back (merged into the `ClaimContext` it is handed). */
10
+ export interface ClaimerDiscovery<C extends object = object> extends RawDiscovery {
11
+ readonly context?: C;
12
+ }
13
+ /** The contract a claimer package exports as `claimer` (named in the ports
14
+ * entry's `with.claimers`). `claim` takes the raw indices it owns out of
15
+ * `remaining` and returns their services. */
16
+ export interface Claimer<C extends object = object> {
17
+ discover(worktree: string, deps: ClaimerDeps): Promise<ClaimerDiscovery<C>>;
18
+ claim(raw: readonly RawPort[], remaining: Set<number>, ctx: ClaimContext & Partial<C>): ClaimedService[];
19
+ }
5
20
  /**
6
21
  * `https://<lowercase-ticket>-<key>.<zone>` — pure, no I/O (spec: naming stays
7
22
  * a pure exported function). Throws on an invalid ticket, key, zone or a
@@ -16,24 +31,24 @@ export declare function publicHostname(ticket: string, key: string, zone: string
16
31
  export declare function inspectorPorts(cmdline: string): number[];
17
32
  /** Run claimers in precedence order over one raw discovery pass, specific
18
33
  * before broad: configured process entries (with the default `storybook`),
19
- * DDEV (generic `web`/`web-<host>` naming), then the opt-in all-Node rule.
20
- * DDEV's keys never change: a process claim on a key DDEV produced becomes
21
- * `<key>-<port>`. */
22
- export declare function claimServices(raw: RawDiscovery, ctx: ClaimContext, rules: ServiceRules): Promise<ClaimedDiscovery>;
23
- /** `.ddev/config.yaml`'s own raw-text reader — kept distinct from
24
- * `HostDiscoveryDeps` since it is plain file I/O, not a command exec. */
34
+ * the configured `claimers` in order, then the opt-in all-Node rule.
35
+ * A claimer's keys never change: a process claim on a key a claimer
36
+ * produced becomes `<key>-<port>`. */
37
+ export declare function claimServices(raw: RawDiscovery, ctx: ClaimContext, rules: ServiceRules, claimers?: readonly Claimer[]): Promise<ClaimedDiscovery>;
38
+ /** A plain file reader for claimers — kept distinct from
39
+ * `HostDiscoveryDeps` since it is file I/O, not a command exec. */
25
40
  export interface ConfigFileDeps {
26
41
  /** `null` for ENOENT; throwing is reserved for a real I/O failure. */
27
42
  readFile(path: string): Promise<string | null>;
28
43
  }
29
44
  /** Compose raw lookup and claims — the `list`/`up` entry point.
30
- * Host-listener discovery (process-rule candidates) stays local; DDEV's own
31
- * container discovery AND effective-host discovery (`ddev utility
32
- * configyaml`) are delegated to `@bakers-build/addon-ddev`, never read/called
33
- * directly here. */
45
+ * Host-listener discovery (process-rule candidates) stays local; every
46
+ * configured claimer discovers its own ports alongside it, and its
47
+ * `context` joins the `ClaimContext` all claimers are handed. */
34
48
  export declare function discoverClaimedServices(worktree: string, deps: HostDiscoveryDeps & ConfigFileDeps, opts: {
35
49
  readonly ticket: string;
36
50
  readonly zone: string;
37
51
  readonly probe: HttpProbe;
38
52
  readonly rules: ServiceRules;
53
+ readonly claimers?: readonly Claimer[];
39
54
  }): Promise<ClaimedDiscovery>;
@@ -2,21 +2,18 @@
2
2
  // tunnel-ready services. A claimer consumes raw IDENTITIES (array indices
3
3
  // into one `RawDiscovery` pass), never a global port number: two containers
4
4
  // or two site rules can share a port, so "port already seen" would silently
5
- // merge them. Claimers run in precedence order (configured processes, DDEV,
6
- // then the opt-in all-Node rule — specific before broad); each receives only
7
- // what the previous claimer left in `remaining`.
5
+ // merge them. Claimers run in precedence order (configured processes, the
6
+ // configured claimer packages, then the opt-in all-Node rule — specific
7
+ // before broad); each receives only what the previous claimer left in
8
+ // `remaining`.
8
9
  //
9
10
  // This package owns naming/reconciliation and the process claimers (host
10
11
  // processes matched by the ports addon's `services` settings, no Docker
11
12
  // call). Which processes are tunnelled is configuration, not code here; an
12
- // unmatched listener stays unclaimed — still no numeric-port fallback. DDEV's own discovery/claim logic — everything
13
- // that fires `docker` or interprets `HTTP(S)_EXPOSE`/`VIRTUAL_HOST`, and the
14
- // neutral `{key, service, hostHeader?, insecureTls?}` rules it emits (BB-681:
15
- // no CMS-specific addon or policy layer over its output any more) — lives in
16
- // `@bakers-build/addon-ddev` (operator decision 2026-10-15: ports must not fire
17
- // Docker calls itself). `claimServices` below runs the process rules, then
18
- // DDEV, then all-Node, over one merged raw-discovery pass.
19
- import { claimDdev, discoverDdevHosts, discoverDdevPorts, parseWebExtraExposedPorts, } from '@bakers-build/addon-ddev';
13
+ // unmatched listener stays unclaimed — still no numeric-port fallback.
14
+ // Container discovery and claiming belong to claimer packages named in
15
+ // `with.claimers` (a `Claimer` each, see below): ports fires no `docker`
16
+ // call itself and knows no runtime's conventions.
20
17
  import { discoverHostPorts } from './discovery.js';
21
18
  import { DEFAULT_STORYBOOK, LABEL_RE, } from './service-config.js';
22
19
  const TICKET_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*-\d+$/;
@@ -224,17 +221,17 @@ async function claimProcesses(raw, remaining, ctx, rules) {
224
221
  }
225
222
  /** Run claimers in precedence order over one raw discovery pass, specific
226
223
  * before broad: configured process entries (with the default `storybook`),
227
- * DDEV (generic `web`/`web-<host>` naming), then the opt-in all-Node rule.
228
- * DDEV's keys never change: a process claim on a key DDEV produced becomes
229
- * `<key>-<port>`. */
230
- export async function claimServices(raw, ctx, rules) {
224
+ * the configured `claimers` in order, then the opt-in all-Node rule.
225
+ * A claimer's keys never change: a process claim on a key a claimer
226
+ * produced becomes `<key>-<port>`. */
227
+ export async function claimServices(raw, ctx, rules, claimers = []) {
231
228
  const remaining = new Set(raw.ports.map((_, i) => i));
232
229
  const processes = await claimProcesses(raw.ports, remaining, ctx, rules);
233
- const ddev = claimDdev(raw.ports, remaining, ctx);
230
+ const claimed = claimers.flatMap((c) => c.claim(raw.ports, remaining, ctx));
234
231
  const nodes = await processes.allNode();
235
- const ddevKeys = new Set(ddev.map((s) => s.key));
232
+ const claimedKeys = new Set(claimed.map((s) => s.key));
236
233
  const renamed = [...processes.services, ...nodes].map((s) => {
237
- if (!ddevKeys.has(s.key))
234
+ if (!claimedKeys.has(s.key))
238
235
  return s;
239
236
  const key = `${s.key}-${s.rawPorts[0].hostPort}`;
240
237
  return { ...s, key, rules: s.rules.map((r) => ({ ...r, key })) };
@@ -243,44 +240,31 @@ export async function claimServices(raw, ctx, rules) {
243
240
  .sort((a, b) => a - b)
244
241
  .map((i) => raw.ports[i]);
245
242
  return {
246
- services: [...renamed, ...ddev],
243
+ services: [...renamed, ...claimed],
247
244
  diagnostics: raw.diagnostics,
248
245
  unclaimed,
249
246
  };
250
247
  }
251
248
  /** Compose raw lookup and claims — the `list`/`up` entry point.
252
- * Host-listener discovery (process-rule candidates) stays local; DDEV's own
253
- * container discovery AND effective-host discovery (`ddev utility
254
- * configyaml`) are delegated to `@bakers-build/addon-ddev`, never read/called
255
- * directly here. */
249
+ * Host-listener discovery (process-rule candidates) stays local; every
250
+ * configured claimer discovers its own ports alongside it, and its
251
+ * `context` joins the `ClaimContext` all claimers are handed. */
256
252
  export async function discoverClaimedServices(worktree, deps, opts) {
257
- const [host, ddev, hostsResult, ddevConfigYaml] = await Promise.all([
253
+ const claimers = opts.claimers ?? [];
254
+ const [host, ...found] = await Promise.all([
258
255
  discoverHostPorts(worktree, deps),
259
- discoverDdevPorts(worktree, deps),
260
- discoverDdevHosts(worktree, deps),
261
- deps.readFile(`${worktree.replace(/\/+$/, '')}/.ddev/config.yaml`),
256
+ ...claimers.map((c) => c.discover(worktree, deps)),
262
257
  ]);
263
- // BB-681 review I1: a failed `ddev utility configyaml` read must leave a
264
- // diagnostic, not silently drop every `web-<host>` alias claim — without
265
- // one, `shouldKeepTunnelRecord` sees no evidence at all for a vanished
266
- // alias record and `reap` deletes a route that may still be perfectly
267
- // live, only unobserved this pass.
268
258
  const raw = {
269
- ports: [...host.ports, ...ddev.ports],
270
- diagnostics: [
271
- ...host.diagnostics,
272
- ...ddev.diagnostics,
273
- ...(hostsResult.ok
274
- ? []
275
- : [{ source: 'ddev-hosts', message: hostsResult.reason }]),
276
- ],
259
+ ports: [host, ...found].flatMap((d) => d.ports),
260
+ diagnostics: [host, ...found].flatMap((d) => d.diagnostics),
277
261
  };
262
+ const context = Object.assign({}, ...found.map((d) => d.context));
278
263
  return claimServices(raw, {
264
+ ...context,
279
265
  worktree,
280
266
  ticket: opts.ticket,
281
267
  zone: opts.zone,
282
268
  probe: opts.probe,
283
- webExtraExposedPortNames: parseWebExtraExposedPorts(ddevConfigYaml),
284
- ...(hostsResult.ok ? { hosts: hostsResult.hosts } : {}),
285
- }, opts.rules);
269
+ }, opts.rules, claimers);
286
270
  }
@@ -1,3 +1,4 @@
1
+ import type { Claimer } from './claims.js';
1
2
  import { type PortsTransport } from './transport.js';
2
3
  /** The ports addon entry's `with`, transport-agnostic: `transport.use`
3
4
  * names the package to load; `transport.with` is whatever settings that
@@ -26,6 +27,13 @@ export declare function portsSettings(worktree: string): Promise<unknown>;
26
27
  * scope lists the addon. Throws for a malformed `with` in either scope.
27
28
  */
28
29
  export declare function readPortsSettings(worktree: string): Promise<unknown>;
30
+ /**
31
+ * Load the claimer packages the ports entry's `with.claimers` names, in
32
+ * order, from the same bases as the transport. Each module exports its
33
+ * `Claimer` as the named export `claimer`; an unresolvable package or a
34
+ * module without one throws a safe diagnostic.
35
+ */
36
+ export declare function loadClaimers(settings: unknown, home: string): Promise<Claimer[]>;
29
37
  /**
30
38
  * Resolve, load and construct the configured ports transport from the ports
31
39
  * addon entry's `with` (`settings`).
@@ -96,6 +96,36 @@ export async function readPortsSettings(worktree) {
96
96
  return undefined;
97
97
  return found.entry.with ?? found.entry.options;
98
98
  }
99
+ /** `home`, the running `bakers` host install, then `process.cwd()` — see
100
+ * `loadPortsTransport`. */
101
+ function loadBases(home) {
102
+ return [
103
+ pathToFileURL(`${home}/`).href,
104
+ ...hostInstallBases(),
105
+ pathToFileURL(`${process.cwd()}/`).href,
106
+ ];
107
+ }
108
+ /**
109
+ * Load the claimer packages the ports entry's `with.claimers` names, in
110
+ * order, from the same bases as the transport. Each module exports its
111
+ * `Claimer` as the named export `claimer`; an unresolvable package or a
112
+ * module without one throws a safe diagnostic.
113
+ */
114
+ export async function loadClaimers(settings, home) {
115
+ const names = settings?.claimers;
116
+ if (!Array.isArray(names))
117
+ return [];
118
+ return Promise.all(names.map(async (spec) => {
119
+ const resolved = resolveModuleEslintStyle(spec, loadBases(home));
120
+ if (resolved === undefined)
121
+ throw new Error(`bakers ports cannot resolve claimer package '${spec}'`);
122
+ const { claimer } = (await import(pathToFileURL(resolved).href));
123
+ if (typeof claimer?.discover !== 'function' ||
124
+ typeof claimer.claim !== 'function')
125
+ throw new Error(`ports claimer '${spec}' has no \`claimer\` export with discover and claim`);
126
+ return claimer;
127
+ }));
128
+ }
99
129
  /**
100
130
  * Resolve, load and construct the configured ports transport from the ports
101
131
  * addon entry's `with` (`settings`).
@@ -123,11 +153,7 @@ export async function loadPortsTransport(settings, home) {
123
153
  // `createRequire` as a FILE, which starts `node_modules` lookup one level
124
154
  // too high. Same `pathToFileURL(dir + '/')` shape `load-bakers-config.ts`
125
155
  // already uses for its own bases.
126
- const resolved = resolveModuleEslintStyle(spec, [
127
- pathToFileURL(`${home}/`).href,
128
- ...hostInstallBases(),
129
- pathToFileURL(`${process.cwd()}/`).href,
130
- ]);
156
+ const resolved = resolveModuleEslintStyle(spec, loadBases(home));
131
157
  if (resolved === undefined) {
132
158
  throw new Error(`bakers ports cannot resolve transport package '${spec}'`);
133
159
  }
@@ -1,10 +1,9 @@
1
- export type { RawDiagnostic, RawDiscovery, RawPort, Tri, } from '@bakers-build/addon-ddev';
2
- export { type ClaimContext, type ClaimedDiscovery, type ClaimedService, type ClaimStatus, claimServices, discoverClaimedServices, type HttpProbe, publicHostname, type TunnelRule, } from './claims.js';
3
- export { assertNoMachinePorts, loadPortsTransport, PORTS_NEEDS_ENTRY, PORTS_RETIRED, type PortsMachineConfig, portsSettings, readPortsSettings, withProblems, } from './config.js';
1
+ export { type ClaimContext, type ClaimedDiscovery, type ClaimedService, type Claimer, type ClaimerDeps, type ClaimerDiscovery, type ClaimStatus, type ConfigFileDeps, claimServices, discoverClaimedServices, type HttpProbe, publicHostname, type TunnelRule, } from './claims.js';
2
+ export { assertNoMachinePorts, loadClaimers, loadPortsTransport, PORTS_NEEDS_ENTRY, PORTS_RETIRED, type PortsMachineConfig, portsSettings, readPortsSettings, withProblems, } from './config.js';
4
3
  export { discoverHostPorts, type HostDiscoveryDeps, parseSocketListeners, type SocketListener, } from './discovery.js';
5
4
  export { type LockDeps, LockTimeoutError, nodeLockDeps, tunnelLockPath, withTunnelLock, } from './lock.js';
6
5
  export { readTunnelState, type StateDeps } from './state.js';
7
6
  export { assertPortsTransport, InvalidTransportModuleError, type PortsTransport, type PortsTransportFactory, } from './transport.js';
8
7
  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';
9
8
  export { assertIdentity, emptyState, type MachineTunnelState, nodeTunnelStateDeps, type ReadResult, readMachineTunnelState, readValidatedMachineState, type TunnelDesiredRecord, type TunnelIdentity, TunnelIdentityMismatchError, type TunnelStateDeps, tunnelStatePath, upsertRecord, writeMachineTunnelState, } from './tunnel-state.js';
10
- export type { TunnelRecord, TunnelState } from './types.js';
9
+ export type { RawDiagnostic, RawDiscovery, RawPort, Tri, TunnelRecord, TunnelState, } from './types.js';
package/dist/src/core.js CHANGED
@@ -6,7 +6,7 @@
6
6
  // same code the commands run; the cockpit renders their result and drives their
7
7
  // actions.
8
8
  export { claimServices, discoverClaimedServices, publicHostname, } from './claims.js';
9
- export { assertNoMachinePorts, loadPortsTransport, PORTS_NEEDS_ENTRY, PORTS_RETIRED, portsSettings, readPortsSettings, withProblems, } from './config.js';
9
+ export { assertNoMachinePorts, loadClaimers, loadPortsTransport, PORTS_NEEDS_ENTRY, PORTS_RETIRED, portsSettings, readPortsSettings, withProblems, } from './config.js';
10
10
  export { discoverHostPorts, parseSocketListeners, } from './discovery.js';
11
11
  export { LockTimeoutError, nodeLockDeps, tunnelLockPath, withTunnelLock, } from './lock.js';
12
12
  export { readTunnelState } from './state.js';
@@ -43,7 +43,7 @@ export const nodeDiscoveryDeps = {
43
43
  return { stdout, ok: true };
44
44
  }
45
45
  catch (err) {
46
- // A non-zero exit still carries stdout for a command like `ddev describe`
46
+ // A non-zero exit still carries stdout for a command like `docker inspect`
47
47
  // outside a project; hand it back so the parser can decide. `code` is
48
48
  // the numeric exit code when the process actually ran (e.g. 127 =
49
49
  // command not found inside the container); a spawn-level failure
@@ -1,4 +1,5 @@
1
- import { parseSocketListeners, type RawDiscovery, type SocketListener } from '@bakers-build/addon-ddev';
1
+ import { parseSocketListeners, type SocketListener } from '@bakers-build/addon-docker-compose';
2
+ import type { RawDiscovery } from './types.js';
2
3
  export { parseSocketListeners, type SocketListener };
3
4
  /** The injected seams for host-listener discovery. */
4
5
  export interface HostDiscoveryDeps {
@@ -1,18 +1,13 @@
1
- // BB-676 spec v2 — host-listener discovery only. Docker/DDEV discovery
2
- // moved to `@bakers-build/addon-docker-compose`/`@bakers-build/addon-ddev` (operator
3
- // decision 2026-10-15: `bakers ports` must not fire `docker` itself). This file
4
- // now does exactly one thing: `ss -ltnpH` plus `/proc/<pid>` — no external
5
- // binary beyond `ss`, no root.
1
+ // BB-676 spec v2 — host-listener discovery only. Container discovery belongs
2
+ // to the configured claimer packages (`bakers ports` must not fire `docker`
3
+ // itself). This file does exactly one thing: `ss -ltnpH` plus `/proc/<pid>` —
4
+ // no external binary beyond `ss`, no root.
6
5
  //
7
6
  // The parsers are pure and exported so a test drives them with captured
8
7
  // output; the orchestrator takes an injected `run`/`processInfo` so no real
9
8
  // socket is ever read in a test.
10
- import { parseSocketListeners, } from '@bakers-build/addon-ddev';
11
- // BB-676 pass-6 review cleanup — `parseSocketListeners`/`SocketListener`
12
- // used to be reimplemented here byte-for-byte; `@bakers-build/addon-docker-compose`
13
- // is the one home now (the lower-level package), re-exported through
14
- // `@bakers-build/addon-ddev` because this addon may not edge to
15
- // `@bakers-build/addon-docker-compose` directly (`scripts/assert-acyclic.mjs`).
9
+ import { parseSocketListeners, } from '@bakers-build/addon-docker-compose';
10
+ // `@bakers-build/addon-docker-compose` is the one home of the `ss` parser.
16
11
  export { parseSocketListeners };
17
12
  /** Is `path` inside `worktree` (or the worktree itself)? */
18
13
  function underWorktree(path, worktree) {
@@ -38,7 +33,7 @@ export async function discoverHostPorts(worktree, deps) {
38
33
  // netstat parity is out of scope). Rather than let a raw `ENOENT` surface
39
34
  // as "ss -ltnpH failed" with no further context, name the real cause when
40
35
  // we know it, so this reads as an honest platform limitation rather than a
41
- // mysterious probe failure. Docker/DDEV-routed services are unaffected —
36
+ // mysterious probe failure. Container-routed services are unaffected —
42
37
  // the Linux VM behind Docker Desktop still answers these probes fine
43
38
  // in-container; only THIS host-process scan is skipped.
44
39
  const host = await deps.run('ss', ['-ltnpH']);
@@ -78,7 +78,7 @@ export declare function liveTunnel(record: TunnelDesiredRecord, discovery: Claim
78
78
  rule?: TunnelRule;
79
79
  };
80
80
  /** Keys of present records whose freshly claimed rule no longer matches
81
- * them (e.g. a new container IP after `ddev restart`). A key with no claim
81
+ * them (e.g. a new container IP after a container restart). A key with no claim
82
82
  * at all is `reap`'s business, not stale. */
83
83
  export declare function staleKeys(records: readonly TunnelDesiredRecord[], discovery: ClaimedDiscovery): Set<string>;
84
84
  /** BB-681 review M6: Quick's URL is a real `trycloudflare.com` allocation,
package/dist/src/index.js CHANGED
@@ -17,7 +17,7 @@ import { execFileSync } from 'node:child_process';
17
17
  import { readdirSync, readFileSync } from 'node:fs';
18
18
  import { isAbsolute, join, relative, resolve } from 'node:path';
19
19
  import { homeBbDir } from '@bakers-build/core';
20
- import { discoverClaimedServices, loadPortsTransport, portsSettings, readPortsSettings, } from './core.js';
20
+ import { discoverClaimedServices, loadClaimers, loadPortsTransport, portsSettings, readPortsSettings, } from './core.js';
21
21
  import { isOwnedByCurrentUser, listCloudflaredProcesses, nodeDeps, nodeHttpProbe, processStartTime, readLegacyTunnelPids, } from './deps-node.js';
22
22
  import { serviceRules } from './service-config.js';
23
23
  import { recordMatchesRule } from './tunnel-ops.js';
@@ -163,16 +163,15 @@ export function shouldKeepTunnelRecord(discovery, key) {
163
163
  // when it is a whole-probe failure (`ss -ltnpH` itself failing) — the
164
164
  // host-side equivalent of a `containerId`-less Docker diagnostic — since
165
165
  // that blinds every host-backed no-claim record at once, same as a
166
- // host-backed claimed record is kept on it above. A `ddev-hosts` diagnostic
167
- // (BB-681 review I1) is scoped to `web`/`web-<host>` alias keys only —
168
- // `ddev utility configyaml` failing says nothing about a non-DDEV claim
169
- // (e.g. `storybook`) in the SAME worktree, so it must not block THAT
170
- // record's reap (BB-681 review N1).
166
+ // host-backed claimed record is kept on it above. A diagnostic carrying a
167
+ // `keyPrefix` (a claimer's, BB-681 review I1) blocks only keys under that
168
+ // prefix — it says nothing about another claim (e.g. `storybook`) in the
169
+ // SAME worktree, so it must not block THAT record's reap (BB-681 review N1).
171
170
  return discovery.diagnostics.some((d) => {
172
171
  if (d.source === 'host')
173
172
  return d.wholePass === true;
174
- if (d.source === 'ddev-hosts')
175
- return key === 'web' || key.startsWith('web-');
173
+ if (d.keyPrefix !== undefined)
174
+ return key === d.keyPrefix || key.startsWith(`${d.keyPrefix}-`);
176
175
  return true;
177
176
  });
178
177
  }
@@ -209,11 +208,13 @@ async function resolveTransport(worktree) {
209
208
  /** Claim `worktree`'s services under its own ports settings; throws for a
210
209
  * malformed settings entry (see `readPortsSettings`). */
211
210
  async function discover(worktree, ticket, zone) {
211
+ const settings = await readPortsSettings(worktree);
212
212
  return discoverClaimedServices(worktree, nodeDeps, {
213
213
  ticket,
214
214
  zone,
215
215
  probe: nodeHttpProbe,
216
- rules: serviceRules(await readPortsSettings(worktree)),
216
+ rules: serviceRules(settings),
217
+ claimers: await loadClaimers(settings, homeBbDir()),
217
218
  });
218
219
  }
219
220
  /** `discover`, or print its error and set a failing exit code. */
@@ -258,7 +259,7 @@ export function liveTunnel(record, discovery) {
258
259
  return rule ? { live: true, rule } : { live: true };
259
260
  }
260
261
  /** Keys of present records whose freshly claimed rule no longer matches
261
- * them (e.g. a new container IP after `ddev restart`). A key with no claim
262
+ * them (e.g. a new container IP after a container restart). A key with no claim
262
263
  * at all is `reap`'s business, not stale. */
263
264
  export function staleKeys(records, discovery) {
264
265
  const stale = new Set();
@@ -2,14 +2,15 @@
2
2
  // `services` names a key and a command-line substring per service; the port is
3
3
  // always read from the running process. `all_node` (opt-in) claims every
4
4
  // remaining Node listener. Storybook is a shipped default entry, so every
5
- // process-based service follows one rule.
5
+ // process-based service follows one rule. `claimers` names claimer packages
6
+ // (loaded by `config.ts`'s `loadClaimers`), run in order after the services.
6
7
  /** A DNS-safe service key (one hostname label). */
7
8
  export const LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
8
9
  export const DEFAULT_STORYBOOK = {
9
10
  key: 'storybook',
10
11
  match: 'storybook',
11
12
  };
12
- const WITH_KEYS = new Set(['transport', 'services', 'all_node']);
13
+ const WITH_KEYS = new Set(['transport', 'services', 'all_node', 'claimers']);
13
14
  const ENTRY_KEYS = new Set(['key', 'match']);
14
15
  const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
15
16
  /** Every problem in a ports entry's `with`; `[]` when it is valid or absent. */
@@ -23,9 +24,13 @@ export function checkWith(value) {
23
24
  if (!WITH_KEYS.has(k))
24
25
  out.push({
25
26
  key: k,
26
- message: 'is not a ports setting (transport, services, all_node)',
27
+ message: 'is not a ports setting (transport, services, all_node, claimers)',
27
28
  });
28
- const { transport, services, all_node } = value;
29
+ const { transport, services, all_node, claimers } = value;
30
+ if (claimers !== undefined &&
31
+ (!Array.isArray(claimers) ||
32
+ !claimers.every((c) => typeof c === 'string' && c !== '')))
33
+ out.push({ key: 'claimers', message: 'must be an array of package names' });
29
34
  if (transport !== undefined) {
30
35
  if (!isObject(transport))
31
36
  out.push({ key: 'transport', message: 'must be an object' });
package/dist/src/tools.js CHANGED
@@ -7,11 +7,11 @@ import { existsSync, realpathSync } from 'node:fs';
7
7
  import { homeBbDir } from '@bakers-build/core';
8
8
  import { servicesToShare, shareAll } from './claim-share.js';
9
9
  import { discoverClaimedServices } from './claims.js';
10
- import { assertNoMachinePorts, bringUpTunnel, loadPortsTransport, readMachineTunnelRecords, reapTunnels, takeDownTunnel, withProblems, } from './core.js';
10
+ import { assertNoMachinePorts, bringUpTunnel, loadClaimers, loadPortsTransport, readMachineTunnelRecords, reapTunnels, takeDownTunnel, withProblems, } from './core.js';
11
11
  import { nodeDeps, nodeHttpProbe, nodeTunnelOpsDeps } from './deps-node.js';
12
12
  import { currentBranch, liveTunnel, resolveTicketIdentifier, selectService, staleKeys, } from './index.js';
13
13
  import { serviceRules } from './service-config.js';
14
- /** DDEV labels containers with the real path; discovery matches it exactly. */
14
+ /** Container labels carry the real path; discovery matches it exactly. */
15
15
  function canonicalPath(path) {
16
16
  try {
17
17
  return realpathSync(path);
@@ -53,7 +53,7 @@ export function portsTools(deps) {
53
53
  const worktree = canonicalPath(req.worktreePath);
54
54
  const ticket = ticketOf(req, worktree);
55
55
  const lines = [];
56
- // A container IP reused by another DDEV project after `ddev restart`
56
+ // A container IP reused by another project after a container restart
57
57
  // would serve that project under a stale route, so every `up` first
58
58
  // re-checks every recorded route machine-wide, exactly like `reap`.
59
59
  const recheck = await reapAll(transport, req.signal);
@@ -163,11 +163,12 @@ export function toolsFor(options) {
163
163
  };
164
164
  }
165
165
  },
166
- discover: (worktree, ticket, zone) => discoverClaimedServices(worktree, nodeDeps, {
166
+ discover: async (worktree, ticket, zone) => discoverClaimedServices(worktree, nodeDeps, {
167
167
  ticket,
168
168
  zone,
169
169
  probe: nodeHttpProbe,
170
170
  rules: serviceRules(options),
171
+ claimers: await loadClaimers(options, homeBbDir()),
171
172
  }),
172
173
  readRecords: (worktree) => readMachineTunnelRecords(worktree, homeBbDir(), nodeTunnelOpsDeps),
173
174
  bringUp: (rule, ctx) => bringUpTunnel(rule, ctx, nodeTunnelOpsDeps),
@@ -16,3 +16,124 @@ export interface TunnelRecord {
16
16
  export interface TunnelState {
17
17
  readonly tunnels: readonly TunnelRecord[];
18
18
  }
19
+ /** One OBSERVATION, not yet a claimed service. A port alone is not an
20
+ * identity (two containers, two site rules can share one). `RawPort`
21
+ * carries every piece of evidence a claimer needs, and a missing probe is
22
+ * `unknown` — never collapsed into `false` — so a permission-denied Docker
23
+ * query cannot read as "this is dead" and revoke a route that is actually
24
+ * still live. */
25
+ export type Tri = boolean | 'unknown';
26
+ export interface RawPort {
27
+ readonly worktree: string;
28
+ readonly containerId?: string;
29
+ readonly containerPort?: number;
30
+ readonly protocol?: 'tcp' | 'udp';
31
+ readonly hostAddress?: string;
32
+ readonly hostPort?: number;
33
+ /** The in-container bind address a listening socket reported, when known —
34
+ * used to tell Docker's embedded DNS resolver (`127.0.0.11`) apart from a
35
+ * real service when picking a dead claim's "what IS listening" sibling. */
36
+ readonly address?: string;
37
+ readonly pid?: number;
38
+ readonly cmdline?: string;
39
+ readonly cwd?: string;
40
+ readonly cwdDeleted?: boolean;
41
+ /** The container's IP on its project network, when it has one. */
42
+ readonly containerIp?: string;
43
+ /** The router-side port of an `HTTP_EXPOSE`/`HTTPS_EXPOSE` mapping. */
44
+ readonly routerPort?: number;
45
+ /** Which `*_EXPOSE` var produced this row's router mapping — the only
46
+ * reliable signal for the target scheme (B): a port that only appears in
47
+ * `HTTP_EXPOSE` must be dialled over plain HTTP, never HTTPS. */
48
+ readonly exposeScheme?: 'http' | 'https';
49
+ readonly virtualHost?: string;
50
+ /** A service-type label, when a project sets one — the more specific
51
+ * naming source than `composeService` when it exists. */
52
+ readonly serviceType?: string;
53
+ /** The `com.docker.compose.service` label (`web`, `mailpit`, `phpmyadmin`,
54
+ * `opensearch`, …) — naming evidence for the claimer. */
55
+ readonly composeService?: string;
56
+ /** `supervisorctl`'s `group:name`, e.g. `webextradaemons:xhgui`. */
57
+ readonly daemon?: string;
58
+ readonly daemonStatus?: 'RUNNING' | 'STOPPED' | 'EXITED' | 'UNKNOWN';
59
+ readonly containerState?: 'running' | 'stopped' | 'unknown';
60
+ /** A real socket was observed bound to this port. */
61
+ readonly listening: Tri;
62
+ /** A router rule claims this port, regardless of whether it listens. */
63
+ readonly exposed: Tri;
64
+ /** The host-bound port `docker inspect`'s `NetworkSettings.Ports` maps this
65
+ * `containerPort` to (BB-500 passthrough target), when published. */
66
+ readonly hostBoundPort?: number;
67
+ }
68
+ export interface RawDiagnostic {
69
+ /** `'claimer'`: reported by a configured claimer package, uninterpreted. */
70
+ readonly source: 'host' | 'docker' | 'web-sockets' | 'supervisor' | 'claimer';
71
+ readonly message: string;
72
+ /** Scopes a no-claim record's reap block to keys `keyPrefix` and
73
+ * `keyPrefix-*`; without it a non-host diagnostic blocks every key. */
74
+ readonly keyPrefix?: string;
75
+ /** D: the container this diagnostic is about, when it is about one in
76
+ * particular — see `ComposeDiagnostic.containerId` (`@bakers-build/addon-docker-compose`)
77
+ * for why this narrows reap's blast radius instead of widening it. */
78
+ readonly containerId?: string;
79
+ /** C: true when this `source: 'host'` diagnostic means the WHOLE host
80
+ * probe (`ss -ltnpH`) failed, blinding every host-backed service at once
81
+ * — the host-side equivalent of a `containerId`-less Docker diagnostic.
82
+ * A per-listener host diagnostic (e.g. "no visible owner") is about one
83
+ * socket, not the whole probe, and must not carry this flag. */
84
+ readonly wholePass?: boolean;
85
+ }
86
+ export interface RawDiscovery {
87
+ readonly ports: readonly RawPort[];
88
+ readonly diagnostics: readonly RawDiagnostic[];
89
+ }
90
+ export interface TunnelRule {
91
+ readonly key: string;
92
+ readonly service: string;
93
+ readonly hostHeader?: string;
94
+ readonly insecureTls?: boolean;
95
+ /** Plain-HTTP origin of the service container itself
96
+ * (`http://<container IP>:<containerPort>`), reachable with the public
97
+ * Host kept; only transports that can dial container IPs (frp) use it. */
98
+ readonly direct?: string;
99
+ }
100
+ export type ClaimStatus = 'healthy' | 'dead' | 'stopped' | 'not-exposed' | 'unknown';
101
+ export interface ClaimedService {
102
+ readonly key: string;
103
+ /** The claimer that owns this service — `'process'` (a configured ports
104
+ * rule), `'node'` (the all-Node rule) or a claimer package's own name. */
105
+ readonly claim: string;
106
+ readonly status: ClaimStatus;
107
+ /** A local address worth opening on this machine. */
108
+ readonly local: string;
109
+ /** Set when the service is shareable but with a known gap (e.g. no login). */
110
+ readonly limitation?: string;
111
+ /** The raw evidence this claim rests on, for `list` and diagnostics. */
112
+ readonly rawPorts: readonly RawPort[];
113
+ /** Empty unless `status === 'healthy'`. */
114
+ readonly rules: readonly TunnelRule[];
115
+ }
116
+ export interface ClaimedDiscovery {
117
+ readonly services: readonly ClaimedService[];
118
+ /** Surfaced raw-discovery diagnostics — a caller (reap) must be able to
119
+ * tell "nothing is here" from "the probe itself could not see", so a
120
+ * denied Docker query cannot read as every service having vanished. */
121
+ readonly diagnostics: readonly RawDiagnostic[];
122
+ /** Every raw identity no claimer picked up — `list` shows these dimmed,
123
+ * literally "no addon" (spec): visible, but never shareable. */
124
+ readonly unclaimed: readonly RawPort[];
125
+ }
126
+ /** A single bounded, non-redirecting HTTP probe — injected, never a real fetch here. */
127
+ export type HttpProbe = (url: string, opts: {
128
+ readonly timeoutMs: number;
129
+ }) => Promise<{
130
+ readonly ok: boolean;
131
+ readonly status: number;
132
+ readonly body: string;
133
+ } | null>;
134
+ export interface ClaimContext {
135
+ readonly worktree: string;
136
+ readonly ticket: string;
137
+ readonly zone: string;
138
+ readonly probe: HttpProbe;
139
+ }
package/dist/src/types.js CHANGED
@@ -5,7 +5,7 @@
5
5
  // captured command output and substituted process spawning, and never starts
6
6
  // a tunnel or reads a real socket table.
7
7
  //
8
- // BB-676 spec v2: `RawPort`/`RawDiagnostic`/`RawDiscovery` and the claim
9
- // contract (`ClaimedService`/`TunnelRule`/`ClaimContext`/…) moved to
10
- // `@bakers-build/addon-ddev` — see `claims.ts`'s header comment for why.
8
+ // `RawPort`/`RawDiagnostic`/`RawDiscovery` and the claim contract
9
+ // (`ClaimedService`/`TunnelRule`/`ClaimContext`/…) are owned here; claimer
10
+ // packages import them from `@bakers-build/addon-ports/core`.
11
11
  export {};
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@bakers-build/addon-ports",
3
- "version": "0.6.1-next.5",
4
- "description": "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.",
3
+ "version": "0.6.1-next.7",
4
+ "description": "bakers.build ports command plugin: discover a ticket worktree's running services (claimer packages' containers, Storybook, ad-hoc listeners) and bring shareable tunnels up and down. The command half of BB-475; usable without the cockpit half.",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "exports": {
@@ -23,15 +23,15 @@
23
23
  "directory": "bakers-cli/addons/ports"
24
24
  },
25
25
  "dependencies": {
26
- "@bakers-build/addon-ddev": "^0.6.1-next.5",
26
+ "@bakers-build/addon-docker-compose": "^0.6.1-next.7",
27
27
  "commander": "^12.1.0"
28
28
  },
29
29
  "peerDependencies": {
30
- "@bakers-build/conductor": "^0.6.1-next.5",
31
- "@bakers-build/core": "^0.6.1-next.5"
30
+ "@bakers-build/conductor": "^0.6.1-next.7",
31
+ "@bakers-build/core": "^0.6.1-next.7"
32
32
  },
33
33
  "bakersBuild": {
34
- "commit": "314f28982940df736bea55293a81435d37864b31",
34
+ "commit": "b89398b187bf51f4f9ca5bfc1150469f73a879e6",
35
35
  "channel": "next"
36
36
  }
37
37
  }