@bakers-build/addon-docker-compose 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-docker-compose
 
-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.
+Generic Docker Compose discovery: containers, bound ports, in-container sockets and supervisor status for a worktree — no DDEV knowledge.
+
+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/discovery.d.ts

@@ -0,0 +1,130 @@
+/** The injected seam — only `run`, since this package never reads `/proc`
+ *  itself (that is `addon-ports`' own host-listener discovery). `stderr` is
+ *  optional and only consulted to split an exit-126 `supervisorctl` failure
+ *  (BB-681 Task 1): "command not found" (missing executable — no diagnostic,
+ *  same as exit 127) versus "permission denied" (a real failure, still
+ *  diagnostic) — the general exec behavior is otherwise unchanged. */
+export interface DockerComposeDeps {
+    run(cmd: string, args: string[], cwd?: string): Promise<{
+        stdout: string;
+        ok: boolean;
+        exitCode?: number;
+        stderr?: string;
+    }>;
+}
+export interface ComposeDiagnostic {
+    readonly source: 'docker' | 'web-sockets' | 'supervisor';
+    readonly message: string;
+    /** D: which container this diagnostic is about, when it is about one in
+     *  particular (a per-container probe failure) — absent for a whole-pass
+     *  failure (`docker ps`/`docker inspect` itself failing) that genuinely
+     *  blinds every container at once. A reap must only withhold a record
+     *  whose OWN container produced unresolved evidence, not every record in
+     *  the worktree just because one unrelated container had a probe gap. */
+    readonly containerId?: string;
+}
+/** A confirmed-listening socket inside a container, with its supervisor
+ *  daemon attached when the pid correlation below found one. */
+export interface ComposeSocket {
+    readonly containerPort: number;
+    /** The bind address `ss`/`/proc/net/tcp` reported — `127.0.0.11` is
+     *  Docker's own embedded DNS resolver stub inside every container's
+     *  network namespace, never an operator-addressable service; a consumer
+     *  (`listeningSibling`, `@bakers-build/addon-ddev`) excludes it when picking a
+     *  diagnostic "what IS listening" candidate for a dead claim. */
+    readonly address?: string;
+    readonly pid?: number;
+    readonly daemon?: string;
+    readonly daemonStatus?: 'RUNNING' | 'STOPPED' | 'EXITED' | 'UNKNOWN';
+}
+/** A supervisor-managed daemon with no live socket to attach to (typically
+ *  STOPPED/EXITED) — distinct from "exposed but nothing is listening". */
+export interface ComposeUnattachedDaemon {
+    readonly daemon: string;
+    readonly status: 'RUNNING' | 'STOPPED' | 'EXITED' | 'UNKNOWN';
+}
+export interface ComposeContainer {
+    readonly id: string;
+    readonly running: boolean;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly env: Readonly<Record<string, string>>;
+    /** `NetworkSettings.Ports`' tcp entries, container port → bound host port. */
+    readonly boundPorts: ReadonlyMap<number, number>;
+    /** `NetworkSettings.Networks`, network name → non-empty `IPAddress`. */
+    readonly networks: ReadonlyMap<string, string>;
+    /** `false` when the in-container socket probe itself failed (e.g. no `ss`
+     *  in a minimal image) — `sockets` is then NOT proof of "nothing is
+     *  listening", only that nothing could be confirmed listening; a consumer
+     *  must not read an empty `sockets` as "dead" when this is `false`. */
+    readonly socketsProbed: boolean;
+    readonly sockets: readonly ComposeSocket[];
+    readonly unattachedDaemons: readonly ComposeUnattachedDaemon[];
+}
+export interface ComposeDiscovery {
+    readonly containers: readonly ComposeContainer[];
+    readonly diagnostics: readonly ComposeDiagnostic[];
+}
+/** `docker ps -a --format '{{.ID}}'` — one id per line. */
+export declare function parseDockerPsIds(text: string): string[];
+interface ContainerInspect {
+    readonly id: string;
+    readonly running: boolean;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly env: Readonly<Record<string, string>>;
+    readonly boundPorts: ReadonlyMap<number, number>;
+    readonly networks: ReadonlyMap<string, string>;
+}
+/**
+ * `docker inspect <ids…>` — a JSON array, one entry per container. Malformed
+ * input (or an entry missing `Id`) is dropped rather than thrown, so one bad
+ * record does not blank the whole batch.
+ */
+export declare function parseDockerInspect(text: string): ContainerInspect[];
+/** One listening socket `ss -ltnp` reported. `pid`/`command` are absent for a
+ *  row with no process column (no permission to see the owner, or a root-
+ *  owned listener an unprivileged `docker exec` cannot resolve) — still real
+ *  listening evidence, just with an unknown owner. */
+export interface SocketListener {
+    readonly address: string;
+    readonly port: number;
+    readonly command?: string;
+    readonly pid?: number;
+}
+/**
+ * Parse `ss -ltnp` output into listeners.
+ *
+ * The line's shape is `LISTEN q q <addr>:<port> <peer> users:(("cmd",pid=N,fd=…))`.
+ * The address may be `127.0.0.1`, `0.0.0.0`, `*`, or an IPv6 form in brackets, so
+ * the port is read as the last `:`-separated field of the local-address column
+ * and everything before it is the bind address. A row with no process column
+ * (no permission, or a kernel socket) is KEPT — it is still listening
+ * evidence, just with no pid to correlate a supervisor daemon against.
+ */
+export declare function parseSocketListeners(text: string): SocketListener[];
+export declare function parseProcNetTcp(text: string): SocketListener[];
+/** `ps -eo pid,ppid --no-headers` → child pid to parent pid, for walking a
+ *  socket's process up to the supervisor-managed ancestor that owns it: a
+ *  supervisor daemon's reported pid is its own forked process, not
+ *  necessarily the child that actually binds the socket. */
+export declare function parsePidParents(text: string): Map<number, number>;
+interface SupervisorEntry {
+    readonly daemon: string;
+    readonly status: 'RUNNING' | 'STOPPED' | 'EXITED' | 'UNKNOWN';
+    readonly pid?: number;
+}
+/** `supervisorctl status` — `group:name STATUS [pid N, uptime …]`. */
+export declare function parseSupervisorStatus(text: string): SupervisorEntry[];
+/**
+ * Discover this worktree's Docker Compose containers: `docker ps -a` (label
+ * filters supplied by the caller — `com.docker.compose.project.working_dir`
+ * is always included, since that is the label Compose itself sets; a
+ * DDEV-flavored caller passes `extraLabelFilters: ['com.ddev.approot']` to
+ * union DDEV's own worktree label, without this package knowing what that
+ * label means), `docker inspect`, and one bounded per-running-container
+ * `docker exec` (socket `ss -ltnp` + `supervisorctl status`, run concurrently
+ * across containers, pid-correlated).
+ */
+export declare function discoverCompose(worktree: string, deps: DockerComposeDeps, opts?: {
+    readonly extraLabelFilters?: readonly string[];
+}): Promise<ComposeDiscovery>;
+export {};

package/dist/src/discovery.js

@@ -0,0 +1,440 @@
+// BB-676 spec v2 — generic Docker Compose discovery, no DDEV knowledge.
+//
+// Split out of `@bakers-build/addon-ports` (operator decision 2026-10-15: "ddev
+// darf nicht im ports dabei sein, zumindest wenn es direkt ddev calls
+// abfeuert") so firing `docker` is not that package's job. This package knows
+// nothing about `HTTP(S)_EXPOSE`, `VIRTUAL_HOST` or any other DDEV
+// convention — it reports containers, their labels/env/bound ports, and the
+// confirmed in-container sockets + supervisor daemons, correlated by pid.
+// Interpreting what those mean (a DDEV router mapping, a Drupal site, …) is a
+// consumer's job — see `@bakers-build/addon-ddev`.
+/** Exit 126 is POSIX "found but not executable" OR (many shells/`docker
+ *  exec`) "command not found" — both reuse 126 instead of 127 in practice.
+ *  Only a stderr phrase that clearly says "permission denied" counts as the
+ *  real failure; anything else (including no stderr at all) is treated like
+ *  a missing binary, so an engine that returns 126 for an absent
+ *  `supervisorctl` never blocks a no-claim reap. */
+function isPermissionDenied126(stderr) {
+    if (!stderr)
+        return false;
+    return /permission denied/i.test(stderr);
+}
+/** `docker ps -a --format '{{.ID}}'` — one id per line. */
+export function parseDockerPsIds(text) {
+    return text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+/**
+ * `docker inspect <ids…>` — a JSON array, one entry per container. Malformed
+ * input (or an entry missing `Id`) is dropped rather than thrown, so one bad
+ * record does not blank the whole batch.
+ */
+export function parseDockerInspect(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const entry of parsed) {
+        const e = entry;
+        const id = e.Id;
+        if (typeof id !== 'string')
+            continue;
+        const state = e.State;
+        const config = e.Config;
+        const labels = config?.Labels ?? {};
+        const envList = Array.isArray(config?.Env) ? config.Env : [];
+        const env = {};
+        for (const line of envList) {
+            const eq = line.indexOf('=');
+            if (eq === -1)
+                continue;
+            env[line.slice(0, eq)] = line.slice(eq + 1);
+        }
+        const boundPorts = new Map();
+        const networkSettings = e.NetworkSettings;
+        const portsMap = networkSettings?.Ports;
+        for (const [key, bindings] of Object.entries(portsMap ?? {})) {
+            const [portStr, proto] = key.split('/');
+            if (proto !== 'tcp' || !bindings || bindings.length === 0)
+                continue;
+            const containerPort = Number(portStr);
+            const hostPort = Number(bindings[0]?.HostPort);
+            if (Number.isInteger(containerPort) && Number.isInteger(hostPort)) {
+                boundPorts.set(containerPort, hostPort);
+            }
+        }
+        const networks = new Map();
+        const networksMap = networkSettings?.Networks;
+        for (const [name, network] of Object.entries(networksMap ?? {})) {
+            const ip = network?.IPAddress;
+            if (typeof ip === 'string' && ip !== '')
+                networks.set(name, ip);
+        }
+        out.push({
+            id,
+            running: state?.Running === true,
+            labels,
+            env,
+            boundPorts,
+            networks,
+        });
+    }
+    return out;
+}
+/**
+ * Parse `ss -ltnp` output into listeners.
+ *
+ * The line's shape is `LISTEN q q <addr>:<port> <peer> users:(("cmd",pid=N,fd=…))`.
+ * The address may be `127.0.0.1`, `0.0.0.0`, `*`, or an IPv6 form in brackets, so
+ * the port is read as the last `:`-separated field of the local-address column
+ * and everything before it is the bind address. A row with no process column
+ * (no permission, or a kernel socket) is KEPT — it is still listening
+ * evidence, just with no pid to correlate a supervisor daemon against.
+ */
+export function parseSocketListeners(text) {
+    const listeners = [];
+    for (const line of text.split('\n')) {
+        if (!line.startsWith('LISTEN'))
+            continue;
+        const columns = line.trim().split(/\s+/);
+        const local = columns[3] ?? '';
+        const sep = local.lastIndexOf(':');
+        if (sep === -1)
+            continue;
+        const port = Number(local.slice(sep + 1));
+        if (!Number.isInteger(port))
+            continue;
+        const address = local.slice(0, sep).replace(/^\[|\]$/g, '');
+        const process = /\(\("([^"]+)",pid=(\d+)/.exec(line);
+        listeners.push({
+            address,
+            port,
+            ...(process
+                ? { command: process[1] ?? '', pid: Number(process[2]) }
+                : {}),
+        });
+    }
+    return listeners;
+}
+/** C: fallback when `ss` is missing/fails entirely inside the container
+ *  (exit 127, not "ran, found nothing") — images like phpMyAdmin/OpenSearch
+ *  ship neither `ss` nor `netstat`. Parse `/proc/net/tcp`(6) directly: each
+ *  data line's 2nd column is `local_address:port_hex`, the 4th column is
+ *  connection state, `0A` hex = LISTEN. This reads the kernel's own listener
+ *  table — strictly real listening evidence, unlike trusting a published
+ *  host port binding (Docker binds a host port whether or not anything
+ *  inside listens). */
+/** `/proc/net/tcp`'s IPv4 address column is 8 hex chars, little-endian byte
+ *  order — `0B00007F` is `127.0.0.11`, not `11.0.0.127`. A 32-char IPv6 form
+ *  is returned as-is (comparisons against it are not needed here). */
+function decodeProcNetAddress(hex) {
+    if (hex.length !== 8)
+        return hex;
+    const bytes = [0, 2, 4, 6].map((i) => Number.parseInt(hex.slice(i, i + 2), 16));
+    return bytes.reverse().join('.');
+}
+export function parseProcNetTcp(text) {
+    const listeners = [];
+    const lines = text.split('\n').slice(1); // header row
+    for (const line of lines) {
+        const cols = line.trim().split(/\s+/);
+        const localAddress = cols[1];
+        const state = cols[3];
+        if (!localAddress || state !== '0A')
+            continue;
+        const sep = localAddress.lastIndexOf(':');
+        if (sep === -1)
+            continue;
+        const port = Number.parseInt(localAddress.slice(sep + 1), 16);
+        if (!Number.isInteger(port))
+            continue;
+        listeners.push({
+            address: decodeProcNetAddress(localAddress.slice(0, sep)),
+            port,
+        });
+    }
+    return listeners;
+}
+/** `ps -eo pid,ppid --no-headers` → child pid to parent pid, for walking a
+ *  socket's process up to the supervisor-managed ancestor that owns it: a
+ *  supervisor daemon's reported pid is its own forked process, not
+ *  necessarily the child that actually binds the socket. */
+export function parsePidParents(text) {
+    const out = new Map();
+    for (const line of text.split('\n')) {
+        const match = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
+        if (!match)
+            continue;
+        out.set(Number(match[1]), Number(match[2]));
+    }
+    return out;
+}
+/** Is `ancestorPid` the supervisor pid, or an ancestor of it, up to a
+ *  bounded depth? Protects against a cyclic/malformed parent map. */
+function isAncestor(parents, pid, ancestorPid) {
+    let current = pid;
+    for (let hop = 0; hop < 16 && current !== undefined; hop += 1) {
+        if (current === ancestorPid)
+            return true;
+        current = parents.get(current);
+    }
+    return false;
+}
+/** `supervisorctl status` — `group:name STATUS [pid N, uptime …]`. */
+export function parseSupervisorStatus(text) {
+    const out = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        const match = /^(\S+)\s+(RUNNING|STOPPED|EXITED|STARTING|BACKOFF|FATAL)\b(.*)$/.exec(trimmed);
+        if (!match)
+            continue;
+        const status = match[2] === 'RUNNING' || match[2] === 'STOPPED' || match[2] === 'EXITED'
+            ? match[2]
+            : 'UNKNOWN';
+        const pid = /pid (\d+)/.exec(match[3] ?? '');
+        out.push({
+            daemon: match[1] ?? '',
+            status,
+            ...(pid ? { pid: Number(pid[1]) } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Discover this worktree's Docker Compose containers: `docker ps -a` (label
+ * filters supplied by the caller — `com.docker.compose.project.working_dir`
+ * is always included, since that is the label Compose itself sets; a
+ * DDEV-flavored caller passes `extraLabelFilters: ['com.ddev.approot']` to
+ * union DDEV's own worktree label, without this package knowing what that
+ * label means), `docker inspect`, and one bounded per-running-container
+ * `docker exec` (socket `ss -ltnp` + `supervisorctl status`, run concurrently
+ * across containers, pid-correlated).
+ */
+export async function discoverCompose(worktree, deps, opts) {
+    const diagnostics = [];
+    const labels = [
+        'com.docker.compose.project.working_dir',
+        ...(opts?.extraLabelFilters ?? []),
+    ];
+    const psResults = await Promise.all(labels.map((label) => deps.run('docker', [
+        'ps',
+        '-a',
+        '--filter',
+        `label=${label}=${worktree}`,
+        '--format',
+        '{{.ID}}',
+    ])));
+    if (psResults.every((r) => !r.ok)) {
+        diagnostics.push({
+            source: 'docker',
+            message: '`docker ps` failed — container discovery is unknown, not empty',
+        });
+        return { containers: [], diagnostics };
+    }
+    const ids = [
+        ...new Set(psResults.flatMap((r) => (r.ok ? parseDockerPsIds(r.stdout) : []))),
+    ];
+    if (ids.length === 0)
+        return { containers: [], diagnostics };
+    const inspect = await deps.run('docker', ['inspect', ...ids]);
+    if (!inspect.ok) {
+        diagnostics.push({ source: 'docker', message: '`docker inspect` failed' });
+        return { containers: [], diagnostics };
+    }
+    const inspected = parseDockerInspect(inspect.stdout);
+    const perContainer = await Promise.all(inspected.map(async (c) => {
+        const containerDiagnostics = [];
+        if (!c.running) {
+            return {
+                container: {
+                    ...c,
+                    socketsProbed: true,
+                    sockets: [],
+                    unattachedDaemons: [],
+                },
+                diagnostics: containerDiagnostics,
+            };
+        }
+        const [socketsRes, pidTreeRes, supervisorRes] = await Promise.all([
+            deps.run('docker', ['exec', c.id, 'ss', '-ltnp']),
+            deps.run('docker', [
+                'exec',
+                c.id,
+                'ps',
+                '-eo',
+                'pid,ppid',
+                '--no-headers',
+            ]),
+            deps.run('docker', ['exec', c.id, 'supervisorctl', 'status']),
+        ]);
+        // B: `supervisorctl status` exits 3 (LSB NOT_RUNNING) whenever ANY
+        // managed program is STOPPED/EXITED/FATAL — not just when the whole
+        // call failed. Its stdout still lists every program's status in that
+        // case, so parse it the same as exit 0; only a genuine failure
+        // (binary missing, timeout, unreachable container) withholds evidence.
+        const supervisorHasDaemons = supervisorRes.ok || supervisorRes.exitCode === 3;
+        const parents = pidTreeRes.ok
+            ? parsePidParents(pidTreeRes.stdout)
+            : new Map();
+        const sockets = [];
+        // R6: a daemon's reported pid can own more than one listening socket
+        // (and `ss`'s own row order is not guaranteed) — a single-port map
+        // made which port actually got the daemon attached depend on which
+        // line `ss` printed first. Keep every port a pid owns.
+        const pidToPort = new Map();
+        let socketsProbed = socketsRes.ok;
+        if (socketsRes.ok) {
+            for (const listener of parseSocketListeners(socketsRes.stdout)) {
+                // Docker's embedded DNS resolver (127.0.0.11) listens inside
+                // every container's netns on an ephemeral port — never a service
+                // an operator or a dead-port diagnostic should ever name.
+                if (listener.address === '127.0.0.11')
+                    continue;
+                // A real in-container `ss -ltnpH` run as an unprivileged uid often
+                // cannot see the PID of a root-owned listener (nginx on 80/443) —
+                // the socket line itself still proves it is listening.
+                sockets.push({
+                    containerPort: listener.port,
+                    address: listener.address,
+                });
+                if (listener.pid !== undefined) {
+                    const ports = pidToPort.get(listener.pid) ?? [];
+                    ports.push(listener.port);
+                    pidToPort.set(listener.pid, ports);
+                }
+            }
+        }
+        else {
+            // C: `ss` may simply not be installed at all (exit 127) — images
+            // like phpMyAdmin/OpenSearch ship neither `ss` nor `netstat` AND
+            // have no published host binding (Traefik-only routing), so they
+            // would otherwise stay `unknown` forever. Read the kernel's own
+            // listener table directly instead of trusting any host binding
+            // (Docker binds a host port whether or not anything listens).
+            const [tcp, tcp6] = await Promise.all([
+                deps.run('docker', ['exec', c.id, 'cat', '/proc/net/tcp']),
+                deps.run('docker', ['exec', c.id, 'cat', '/proc/net/tcp6']),
+            ]);
+            if (tcp.ok || tcp6.ok) {
+                socketsProbed = true;
+                const seen = new Set();
+                for (const out of [tcp, tcp6]) {
+                    if (!out.ok)
+                        continue;
+                    for (const listener of parseProcNetTcp(out.stdout)) {
+                        if (listener.address === '127.0.0.11')
+                            continue;
+                        if (seen.has(listener.port))
+                            continue;
+                        seen.add(listener.port);
+                        sockets.push({
+                            containerPort: listener.port,
+                            address: listener.address,
+                        });
+                    }
+                }
+                // `/proc/net/tcp` carries no pid column, so no daemon can be
+                // attached to any of these sockets. Only worth flagging when
+                // this container actually has supervisor-managed daemons to
+                // lose (N1): phpMyAdmin/OpenSearch/`db` have none (exit 127),
+                // and a diagnostic there would wrongly protect their stale
+                // reap records forever.
+                if (supervisorHasDaemons) {
+                    containerDiagnostics.push({
+                        source: 'web-sockets',
+                        message: `in-container socket probe for ${c.id} used the /proc/net/tcp fallback — no daemon names available`,
+                        containerId: c.id,
+                    });
+                }
+            }
+            else {
+                // Both probes failed outright — genuinely unknown, never dead,
+                // so a missing probe binary cannot revoke a live route.
+                containerDiagnostics.push({
+                    source: 'web-sockets',
+                    message: `in-container socket probe failed for ${c.id}`,
+                    containerId: c.id,
+                });
+            }
+        }
+        const unattachedDaemons = [];
+        if (supervisorHasDaemons) {
+            for (const entry of parseSupervisorStatus(supervisorRes.stdout)) {
+                // Prefer an exact socket-pid match; a supervisor-managed daemon's
+                // own reported pid is sometimes a forked child's parent rather
+                // than the pid holding the socket, so fall back to walking the
+                // process tree from each socket pid up to this supervisor pid.
+                // R6: a pid can own more than one port — attach the daemon to
+                // every one of them, not just whichever happened to match first.
+                let ports = entry.pid ? pidToPort.get(entry.pid) : undefined;
+                if (ports === undefined && entry.pid !== undefined) {
+                    for (const [socketPid, candidatePorts] of pidToPort) {
+                        if (isAncestor(parents, socketPid, entry.pid)) {
+                            ports = candidatePorts;
+                            break;
+                        }
+                    }
+                }
+                if (ports !== undefined && ports.length > 0) {
+                    for (const port of ports) {
+                        const idx = sockets.findIndex((s) => s.containerPort === port);
+                        if (idx >= 0) {
+                            sockets[idx] = {
+                                ...sockets[idx],
+                                daemon: entry.daemon,
+                                daemonStatus: entry.status,
+                            };
+                        }
+                    }
+                    continue;
+                }
+                // No live socket to attach to (typically STOPPED/EXITED).
+                unattachedDaemons.push({
+                    daemon: entry.daemon,
+                    status: entry.status,
+                });
+            }
+        }
+        else if (supervisorRes.exitCode !== 127 &&
+            !(supervisorRes.exitCode === 126 &&
+                !isPermissionDenied126(supervisorRes.stderr))) {
+            // D/4: exit 127 means `supervisorctl` is not installed in this
+            // image at all (phpMyAdmin, OpenSearch, OpenSearch Dashboards,
+            // `db`, …) — an absent tool is not a probe failure, just "this
+            // container has no supervisor" (true of most non-DDEV-web
+            // containers), and must never withhold an unrelated reap record.
+            // Exit 126 without a "permission denied" stderr signal is treated
+            // the same way — some engines report a missing binary as 126
+            // rather than 127, and this must not block a no-claim reap either.
+            // Only a genuine execution failure (the binary exists but errored,
+            // a real permission-denied 126, timed out, or the container could
+            // not be reached at all) is diagnostic evidence.
+            containerDiagnostics.push({
+                source: 'supervisor',
+                message: `supervisorctl status failed for ${c.id}`,
+                containerId: c.id,
+            });
+        }
+        return {
+            container: {
+                ...c,
+                socketsProbed,
+                sockets,
+                unattachedDaemons,
+            },
+            diagnostics: containerDiagnostics,
+        };
+    }));
+    const containers = perContainer.map((r) => r.container);
+    for (const r of perContainer)
+        diagnostics.push(...r.diagnostics);
+    return { containers, diagnostics };
+}

package/dist/src/index.d.ts

@@ -0,0 +1 @@
+export { type ComposeContainer, type ComposeDiagnostic, type ComposeDiscovery, type ComposeSocket, type ComposeUnattachedDaemon, type DockerComposeDeps, discoverCompose, parseDockerInspect, parseDockerPsIds, parsePidParents, parseSocketListeners, parseSupervisorStatus, type SocketListener, } from './discovery.js';

package/dist/src/index.js

@@ -0,0 +1 @@
+export { discoverCompose, parseDockerInspect, parseDockerPsIds, parsePidParents, parseSocketListeners, parseSupervisorStatus, } from './discovery.js';

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@bakers-build/addon-docker-compose",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-next.42",
+  "description": "Generic Docker Compose discovery: containers, bound ports, in-container sockets and supervisor status for a worktree — no DDEV knowledge.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/bakers-build/bakers-build.git",
+    "directory": "bakers-cli/addons/docker-compose"
+  },
+  "peerDependencies": {
+    "@bakers-build/core": "^0.1.0-next.42"
+  }
+}