portweave 0.1.0

package/dist/allocator/allocate.js

@@ -0,0 +1,106 @@
+import { PortweaveError, PW_ERROR_CODES } from "../errors.js";
+import { err, ok } from "../result.js";
+import { withRegistry } from "../registry/storage.js";
+import { findFreeBlock, resolvePoolRange } from "./pool.js";
+import { probeBlock, probePort } from "./probe.js";
+export const MAX_PROBE_RETRIES = 100;
+/**
+ * Re-order services so that services sharing a `group` label are contiguous
+ * and groups appear in first-occurrence order. Ungrouped services keep their
+ * original sequential position relative to the groups.
+ *
+ * Pure — no I/O.
+ */
+export function orderServicesForAllocation(config) {
+    const groupFirstSeen = new Map();
+    for (const [i, s] of config.services.entries()) {
+        if (s.group !== undefined && !groupFirstSeen.has(s.group)) {
+            groupFirstSeen.set(s.group, i);
+        }
+    }
+    return [...config.services].sort((a, b) => {
+        const ai = a.group !== undefined
+            ? (groupFirstSeen.get(a.group) ?? config.services.indexOf(a))
+            : config.services.indexOf(a);
+        const bi = b.group !== undefined
+            ? (groupFirstSeen.get(b.group) ?? config.services.indexOf(b))
+            : config.services.indexOf(b);
+        if (ai !== bi) {
+            return ai - bi;
+        }
+        return config.services.indexOf(a) - config.services.indexOf(b);
+    });
+}
+function keysEqual(a, b) {
+    return (a.worktreeRoot === b.worktreeRoot &&
+        a.namespace === b.namespace &&
+        a.gitCommonDir === b.gitCommonDir);
+}
+function buildPortsMap(orderedServices, candidate) {
+    const ports = {};
+    for (const [i, service] of orderedServices.entries()) {
+        ports[service.name] = candidate + i;
+    }
+    return ports;
+}
+async function tryReuseExisting(handle, key) {
+    const existing = handle.entries.find((e) => keysEqual(e.key, key));
+    if (existing === undefined) {
+        return null;
+    }
+    for (const port of Object.values(existing.ports)) {
+        const probeResult = await probePort(port);
+        if (probeResult === 'taken') {
+            handle.remove(key);
+            return null;
+        }
+    }
+    handle.touch(key);
+    const touched = handle.entries.find((e) => keysEqual(e.key, key));
+    return { allocation: touched ?? existing, reused: true };
+}
+async function allocateFreshBlock(handle, key, orderedServices, range) {
+    const occupied = Array.from(new Set(handle.entries.flatMap((e) => Object.values(e.ports)))).sort((a, b) => a - b);
+    const externallyOccupied = [];
+    for (let retries = 0; retries < MAX_PROBE_RETRIES; retries++) {
+        const allOccupied = [...occupied, ...externallyOccupied].sort((a, b) => a - b);
+        const candidate = findFreeBlock(allOccupied, orderedServices.length, range);
+        if (candidate === null) {
+            return err(new PortweaveError(PW_ERROR_CODES.ALLOCATION_EXHAUSTED, 'Port pool exhausted: no contiguous block available in registry'));
+        }
+        const probeResult = await probeBlock(candidate, orderedServices.length);
+        if (probeResult.allFree) {
+            const ports = buildPortsMap(orderedServices, candidate);
+            const entry = {
+                key,
+                lastUsedAt: new Date().toISOString(),
+                namespace: key.namespace,
+                ports,
+            };
+            handle.upsert(entry);
+            return ok({ allocation: entry, reused: false });
+        }
+        // A port in the candidate block is externally taken — skip past it
+        externallyOccupied.push(probeResult.firstTakenPort);
+    }
+    return err(new PortweaveError(PW_ERROR_CODES.ALLOCATION_EXHAUSTED, 'Port pool exhausted: too many externally-bound ports prevented allocation'));
+}
+export async function allocate(key, config, env = process.env) {
+    const range = resolvePoolRange(env);
+    const orderedServices = orderServicesForAllocation(config);
+    // Wrap the inner Result in a container so withRegistry<T> doesn't
+    // double-wrap our error path. The outer Result carries lock/IO errors;
+    // the inner carries allocator-level errors.
+    const outer = await withRegistry(async (handle) => {
+        const reused = await tryReuseExisting(handle, key);
+        if (reused !== null) {
+            return ok(reused);
+        }
+        return allocateFreshBlock(handle, key, orderedServices, range);
+    }, env);
+    if (!outer.ok) {
+        return outer;
+    }
+    return outer.value;
+}
+//# sourceMappingURL=allocate.js.map

package/dist/allocator/allocate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocate.js","sourceRoot":"","sources":["../../src/allocator/allocate.ts"],"names":[],"mappings":"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"}

package/dist/allocator/cross-project.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cross-project.d.ts.map

package/dist/allocator/cross-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-project.d.ts","sourceRoot":"","sources":["../../src/allocator/cross-project.ts"],"names":[],"mappings":""}

package/dist/allocator/cross-project.js

@@ -0,0 +1,9 @@
+export {};
+// Cross-project collision test surface — this module exists to satisfy
+// structure:check which requires a source file at this location for
+// __tests__/cross-project.test.ts. The test exercises the runtime
+// allocate() function across multiple AllocationKeys sharing a single
+// registry, verifying that distinct repos and worktrees receive
+// non-overlapping port sets. No runtime exports are provided here;
+// the test imports directly from allocate.ts and registry/types.ts.
+//# sourceMappingURL=cross-project.js.map

package/dist/allocator/cross-project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-project.js","sourceRoot":"","sources":["../../src/allocator/cross-project.ts"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,oEAAoE;AACpE,kEAAkE;AAClE,sEAAsE;AACtE,gEAAgE;AAChE,mEAAmE;AACnE,oEAAoE"}

package/dist/allocator/order.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=order.d.ts.map

package/dist/allocator/order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.d.ts","sourceRoot":"","sources":["../../src/allocator/order.ts"],"names":[],"mappings":""}

package/dist/allocator/order.js

@@ -0,0 +1,8 @@
+export {};
+// Service-ordering test surface — this module exists to satisfy structure:check
+// which requires a source file at this location for __tests__/order.test.ts.
+// The test exercises orderServicesForAllocation() from allocate.ts in
+// isolation, verifying that scattered grouped services are made contiguous and
+// that group first-occurrence order is preserved. No additional runtime exports
+// are provided here; the test imports directly from allocate.ts.
+//# sourceMappingURL=order.js.map

package/dist/allocator/order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.js","sourceRoot":"","sources":["../../src/allocator/order.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,6EAA6E;AAC7E,sEAAsE;AACtE,+EAA+E;AAC/E,gFAAgF;AAChF,iEAAiE"}

package/dist/allocator/pool.d.ts

@@ -0,0 +1,35 @@
+export declare const POOL_START_DEFAULT: 30000;
+export declare const POOL_END_DEFAULT: 60000;
+export interface PoolRange {
+    readonly end: number;
+    readonly start: number;
+}
+/**
+ * Parse PORTWEAVE_POOL_RANGE from the environment.
+ *
+ * Format: "<start>-<end>" where both are integers, start >= 1024, and
+ * start < end. Malformed, non-integer, privileged, or inverted values fall
+ * back to the default and emit a one-line warning to stderr so a typo
+ * doesn't silently produce surprising allocations.
+ *
+ * The fallback semantics match PORTWEAVE_LOCK_TIMEOUT_MS (decision-log #19);
+ * the difference is the warning line — silent fallback was discovered to be
+ * surprising in the v0 review pass.
+ */
+export declare function resolvePoolRange(env?: NodeJS.ProcessEnv, stderr?: {
+    write: (msg: string) => boolean;
+}): PoolRange;
+/**
+ * Find the first ascending port at which `slotCount` contiguous ports avoid
+ * every entry in `occupiedSorted` and fit within `range`.
+ *
+ * Pure — no I/O. The probe loop in allocate.ts calls it repeatedly, each
+ * call passing an enlarged "occupied" set as probes fail.
+ *
+ * @param occupiedSorted - Sorted array of currently-occupied ports.
+ * @param slotCount - Number of contiguous ports needed.
+ * @param range - Pool range (exclusive upper bound).
+ * @returns The start port of the first free block, or null if no block fits.
+ */
+export declare function findFreeBlock(occupiedSorted: readonly number[], slotCount: number, range: PoolRange): null | number;
+//# sourceMappingURL=pool.d.ts.map

package/dist/allocator/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/allocator/pool.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,EAAG,KAAc,CAAA;AAChD,eAAO,MAAM,gBAAgB,EAAG,KAAc,CAAA;AAO9C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,MAAM,GAAE;IAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CAAmB,GAC3D,SAAS,CAsBX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,GACf,IAAI,GAAG,MAAM,CA4Bf"}

package/dist/allocator/pool.js

@@ -0,0 +1,74 @@
+export const POOL_START_DEFAULT = 30000;
+export const POOL_END_DEFAULT = 60000;
+// Ports below 1024 are privileged on POSIX (require root to bind). Allocating
+// into that range would silently produce ports the dev server can't bind to —
+// treat any start < 1024 as malformed so the user gets a warning and the
+// default range is used instead. Module-local: not part of the public surface.
+const POOL_PRIVILEGED_FLOOR = 1024;
+/**
+ * Parse PORTWEAVE_POOL_RANGE from the environment.
+ *
+ * Format: "<start>-<end>" where both are integers, start >= 1024, and
+ * start < end. Malformed, non-integer, privileged, or inverted values fall
+ * back to the default and emit a one-line warning to stderr so a typo
+ * doesn't silently produce surprising allocations.
+ *
+ * The fallback semantics match PORTWEAVE_LOCK_TIMEOUT_MS (decision-log #19);
+ * the difference is the warning line — silent fallback was discovered to be
+ * surprising in the v0 review pass.
+ */
+export function resolvePoolRange(env = process.env, stderr = process.stderr) {
+    const raw = env.PORTWEAVE_POOL_RANGE;
+    if (raw === undefined || raw.length === 0) {
+        return { end: POOL_END_DEFAULT, start: POOL_START_DEFAULT };
+    }
+    const parts = raw.split('-');
+    if (parts.length === 2) {
+        const start = Number(parts[0]);
+        const end = Number(parts[1]);
+        if (Number.isInteger(start) &&
+            Number.isInteger(end) &&
+            start >= POOL_PRIVILEGED_FLOOR &&
+            end > start) {
+            return { end, start };
+        }
+    }
+    stderr.write(`[portweave] PORTWEAVE_POOL_RANGE="${raw}" ignored — using default ${POOL_START_DEFAULT.toString()}-${POOL_END_DEFAULT.toString()} (format: <start>-<end>, integers, start >= ${POOL_PRIVILEGED_FLOOR.toString()}, end > start)\n`);
+    return { end: POOL_END_DEFAULT, start: POOL_START_DEFAULT };
+}
+/**
+ * Find the first ascending port at which `slotCount` contiguous ports avoid
+ * every entry in `occupiedSorted` and fit within `range`.
+ *
+ * Pure — no I/O. The probe loop in allocate.ts calls it repeatedly, each
+ * call passing an enlarged "occupied" set as probes fail.
+ *
+ * @param occupiedSorted - Sorted array of currently-occupied ports.
+ * @param slotCount - Number of contiguous ports needed.
+ * @param range - Pool range (exclusive upper bound).
+ * @returns The start port of the first free block, or null if no block fits.
+ */
+export function findFreeBlock(occupiedSorted, slotCount, range) {
+    let start = range.start;
+    let oi = 0;
+    // Advance oi to the first occupied port >= start
+    while (oi < occupiedSorted.length && occupiedSorted[oi] < start) {
+        oi++;
+    }
+    while (start + slotCount <= range.end) {
+        const blockEnd = start + slotCount - 1;
+        // Find first occupied port within [start, blockEnd]
+        while (oi < occupiedSorted.length && occupiedSorted[oi] < start) {
+            oi++;
+        }
+        if (oi >= occupiedSorted.length || occupiedSorted[oi] > blockEnd) {
+            // No occupied port in [start, blockEnd] — this block is free
+            return start;
+        }
+        // Jump past the conflict
+        start = occupiedSorted[oi] + 1;
+        oi++;
+    }
+    return null;
+}
+//# sourceMappingURL=pool.js.map

package/dist/allocator/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/allocator/pool.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAc,CAAA;AAChD,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAc,CAAA;AAC9C,8EAA8E;AAC9E,8EAA8E;AAC9E,yEAAyE;AACzE,+EAA+E;AAC/E,MAAM,qBAAqB,GAAG,IAAI,CAAA;AAOlC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAyB,OAAO,CAAC,GAAG,EACpC,SAA8C,OAAO,CAAC,MAAM;IAE5D,MAAM,GAAG,GAAG,GAAG,CAAC,oBAAoB,CAAA;IACpC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,OAAO,EAAE,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAA;IAC7D,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC5B,IACE,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;YACvB,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC;YACrB,KAAK,IAAI,qBAAqB;YAC9B,GAAG,GAAG,KAAK,EACX,CAAC;YACD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAA;QACvB,CAAC;IACH,CAAC;IACD,MAAM,CAAC,KAAK,CACV,qCAAqC,GAAG,6BAA6B,kBAAkB,CAAC,QAAQ,EAAE,IAAI,gBAAgB,CAAC,QAAQ,EAAE,+CAA+C,qBAAqB,CAAC,QAAQ,EAAE,kBAAkB,CACnO,CAAA;IACD,OAAO,EAAE,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAA;AAC7D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAC3B,cAAiC,EACjC,SAAiB,EACjB,KAAgB;IAEhB,IAAI,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;IACvB,IAAI,EAAE,GAAG,CAAC,CAAA;IAEV,iDAAiD;IACjD,OAAO,EAAE,GAAG,cAAc,CAAC,MAAM,IAAI,cAAc,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC;QAChE,EAAE,EAAE,CAAA;IACN,CAAC;IAED,OAAO,KAAK,GAAG,SAAS,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,CAAC,CAAA;QAEtC,oDAAoD;QACpD,OAAO,EAAE,GAAG,cAAc,CAAC,MAAM,IAAI,cAAc,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC;YAChE,EAAE,EAAE,CAAA;QACN,CAAC;QAED,IAAI,EAAE,IAAI,cAAc,CAAC,MAAM,IAAI,cAAc,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC;YACjE,6DAA6D;YAC7D,OAAO,KAAK,CAAA;QACd,CAAC;QAED,yBAAyB;QACzB,KAAK,GAAG,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;QAC9B,EAAE,EAAE,CAAA;IACN,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/allocator/probe.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Probe a single port on 127.0.0.1 to determine if it is free or taken.
+ *
+ * Binds to 127.0.0.1 explicitly — we only care about loopback availability.
+ * Binding to 0.0.0.0 would falsely flag ports as free when an
+ * interface-specific listener exists on a different address.
+ */
+export declare function probePort(port: number): Promise<'free' | 'taken'>;
+export type ProbeBlockResult = {
+    allFree: false;
+    firstTakenPort: number;
+} | {
+    allFree: true;
+};
+/**
+ * Probe every port in [start, start + count).
+ *
+ * Probes sequentially so we can short-circuit on the first taken port and
+ * return it for use as the skip-past value in the outer allocator loop.
+ */
+export declare function probeBlock(start: number, count: number): Promise<ProbeBlockResult>;
+//# sourceMappingURL=probe.d.ts.map

package/dist/allocator/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../src/allocator/probe.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,CAejE;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAAA;AAErB;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,gBAAgB,CAAC,CAQ3B"}

package/dist/allocator/probe.js

@@ -0,0 +1,40 @@
+import { createServer } from 'node:net';
+/**
+ * Probe a single port on 127.0.0.1 to determine if it is free or taken.
+ *
+ * Binds to 127.0.0.1 explicitly — we only care about loopback availability.
+ * Binding to 0.0.0.0 would falsely flag ports as free when an
+ * interface-specific listener exists on a different address.
+ */
+export function probePort(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('listening', () => {
+            server.close(() => {
+                resolve('free');
+            });
+        });
+        // Any error (EADDRINUSE or permissions/sandbox issues) means we cannot
+        // bind — treat as taken so the allocator skips this port defensively.
+        server.once('error', () => {
+            resolve('taken');
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+/**
+ * Probe every port in [start, start + count).
+ *
+ * Probes sequentially so we can short-circuit on the first taken port and
+ * return it for use as the skip-past value in the outer allocator loop.
+ */
+export async function probeBlock(start, count) {
+    for (let port = start; port < start + count; port++) {
+        const result = await probePort(port);
+        if (result === 'taken') {
+            return { allFree: false, firstTakenPort: port };
+        }
+    }
+    return { allFree: true };
+}
+//# sourceMappingURL=probe.js.map

package/dist/allocator/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../src/allocator/probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;QAC7B,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;YAC5B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;gBAChB,OAAO,CAAC,MAAM,CAAC,CAAA;YACjB,CAAC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;QACF,uEAAuE;QACvE,sEAAsE;QACtE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YACxB,OAAO,CAAC,OAAO,CAAC,CAAA;QAClB,CAAC,CAAC,CAAA;QACF,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;IAClC,CAAC,CAAC,CAAA;AACJ,CAAC;AAMD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAa,EACb,KAAa;IAEb,KAAK,IAAI,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAA;QACpC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,CAAA;QACjD,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAC1B,CAAC"}

package/dist/cli/banner.d.ts

@@ -0,0 +1,25 @@
+import type { Allocation } from '../allocator/allocate.ts';
+import type { Config } from '../config/index.ts';
+export interface BannerInput {
+    allocation: Allocation;
+    config: Config;
+    launchingCommand?: string;
+    reused: boolean;
+    verboseLines?: readonly string[];
+    wroteEnvFile?: boolean;
+}
+/**
+ * Returns a multi-line banner string. The caller writes it once to stderr
+ * with a trailing newline appended.
+ *
+ * Pure — no I/O, no global state. All tests are snapshot-friendly fixtures.
+ */
+export declare function formatAllocationBanner(input: BannerInput): string;
+/**
+ * Returns a formatted error line for use in all error paths.
+ *
+ * `[portweave] error: <message> (<code>)` or
+ * `[portweave] error: <message>`
+ */
+export declare function formatErrorLine(message: string, code?: string): string;
+//# sourceMappingURL=banner.d.ts.map

package/dist/cli/banner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"banner.d.ts","sourceRoot":"","sources":["../../src/cli/banner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAEhD,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,MAAM,EAAE,OAAO,CAAA;IACf,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAQD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAuDjE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAItE"}

package/dist/cli/banner.js

@@ -0,0 +1,61 @@
+import { basename } from 'node:path';
+const PREFIX = '[portweave]';
+function worktreeName(worktreeRoot) {
+    return basename(worktreeRoot);
+}
+/**
+ * Returns a multi-line banner string. The caller writes it once to stderr
+ * with a trailing newline appended.
+ *
+ * Pure — no I/O, no global state. All tests are snapshot-friendly fixtures.
+ */
+export function formatAllocationBanner(input) {
+    const { allocation, config, launchingCommand, reused, verboseLines, wroteEnvFile, } = input;
+    const { key, namespace, ports } = allocation;
+    const lines = [];
+    // Worktree header
+    lines.push(`${PREFIX} worktree: ${worktreeName(key.worktreeRoot)} (namespace: ${namespace})`);
+    // Verb line
+    const verb = reused ? 'reusing existing allocation:' : 'allocated:';
+    lines.push(`${PREFIX} ${verb}`);
+    // Service rows: left-pad name to longest service name + 2 spaces
+    const serviceNames = config.services.map((s) => s.name);
+    const maxNameLen = Math.max(...serviceNames.map((n) => n.length));
+    const padWidth = maxNameLen + 2;
+    for (const service of config.services) {
+        if (!(service.name in ports)) {
+            continue;
+        }
+        const port = ports[service.name];
+        const paddedName = service.name.padEnd(padWidth);
+        lines.push(`  ${paddedName}→ ${String(port)}     (${service.envVar})`);
+    }
+    // Wrote line — only when run-command actually wrote the env file; show
+    // omits this since it's a read-only introspection command.
+    if (wroteEnvFile === true) {
+        lines.push(`${PREFIX} wrote .portweave/current.env`);
+    }
+    // Optional verbose lines (already prefixed with [portweave])
+    if (verboseLines !== undefined) {
+        for (const vl of verboseLines) {
+            lines.push(vl);
+        }
+    }
+    // Launching line (omitted by show-command)
+    if (launchingCommand !== undefined) {
+        lines.push(`${PREFIX} launching: ${launchingCommand}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Returns a formatted error line for use in all error paths.
+ *
+ * `[portweave] error: <message> (<code>)` or
+ * `[portweave] error: <message>`
+ */
+export function formatErrorLine(message, code) {
+    return code !== undefined
+        ? `${PREFIX} error: ${message} (${code})`
+        : `${PREFIX} error: ${message}`;
+}
+//# sourceMappingURL=banner.js.map

package/dist/cli/banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"banner.js","sourceRoot":"","sources":["../../src/cli/banner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAapC,MAAM,MAAM,GAAG,aAAa,CAAA;AAE5B,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,QAAQ,CAAC,YAAY,CAAC,CAAA;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAkB;IACvD,MAAM,EACJ,UAAU,EACV,MAAM,EACN,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,YAAY,GACb,GAAG,KAAK,CAAA;IACT,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,UAAU,CAAA;IAE5C,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,kBAAkB;IAClB,KAAK,CAAC,IAAI,CACR,GAAG,MAAM,cAAc,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,gBAAgB,SAAS,GAAG,CAClF,CAAA;IAED,YAAY;IACZ,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,YAAY,CAAA;IACnE,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC,CAAA;IAE/B,iEAAiE;IACjE,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IACvD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;IACjE,MAAM,QAAQ,GAAG,UAAU,GAAG,CAAC,CAAA;IAE/B,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;YAC7B,SAAQ;QACV,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAChC,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAChD,KAAK,CAAC,IAAI,CAAC,KAAK,UAAU,KAAK,MAAM,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,MAAM,GAAG,CAAC,CAAA;IACxE,CAAC;IAED,uEAAuE;IACvE,2DAA2D;IAC3D,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,+BAA+B,CAAC,CAAA;IACtD,CAAC;IAED,6DAA6D;IAC7D,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,KAAK,MAAM,EAAE,IAAI,YAAY,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAChB,CAAC;IACH,CAAC;IAED,2CAA2C;IAC3C,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,eAAe,gBAAgB,EAAE,CAAC,CAAA;IACxD,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,IAAa;IAC5D,OAAO,IAAI,KAAK,SAAS;QACvB,CAAC,CAAC,GAAG,MAAM,WAAW,OAAO,KAAK,IAAI,GAAG;QACzC,CAAC,CAAC,GAAG,MAAM,WAAW,OAAO,EAAE,CAAA;AACnC,CAAC"}

package/dist/cli/run.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from 'commander';
+export interface RunIo {
+    cwd: () => string;
+    env: NodeJS.ProcessEnv;
+    stderr: NodeJS.WritableStream;
+    stdout: NodeJS.WritableStream;
+}
+export interface RunOptions {
+    configPath?: string;
+    count?: number;
+    verbose: boolean;
+}
+export declare function runCommand(childArgs: readonly string[], options: RunOptions, io?: RunIo): Promise<number>;
+export declare function registerRunCommand(program: Command): void;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAaxC,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;IACtB,MAAM,EAAE,MAAM,CAAC,cAAc,CAAA;IAC7B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAA;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;CACjB;AAsJD,wBAAsB,UAAU,CAC9B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,OAAO,EAAE,UAAU,EACnB,EAAE,GAAE,KAAoB,GACvB,OAAO,CAAC,MAAM,CAAC,CAgDjB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoBzD"}

package/dist/cli/run.js

@@ -0,0 +1,156 @@
+import { allocate } from "../allocator/allocate.js";
+import { synthesizeAnonymousConfig } from "../config/anonymous.js";
+import { loadConfig } from "../config/loader.js";
+import { resolveEnv } from "../env/index.js";
+import { PortweaveError, PW_ERROR_CODES } from "../errors.js";
+import { resolveRegistryPath } from "../registry/paths.js";
+import { err } from "../result.js";
+import { resolveAllocationKey } from "../worktree/key.js";
+import { formatAllocationBanner, formatErrorLine } from "./banner.js";
+import { resolveExitCode, spawnChild } from "./spawn.js";
+const defaultRunIo = {
+    cwd: () => process.cwd(),
+    env: process.env,
+    stderr: process.stderr,
+    stdout: process.stdout,
+};
+function writeError(opts) {
+    opts.io.stderr.write(formatErrorLine(opts.message, opts.code) + '\n');
+    if (opts.verbose === true && opts.stack !== undefined) {
+        opts.io.stderr.write(opts.stack + '\n');
+    }
+}
+function writePortweaveError(error, io, verbose) {
+    writeError({
+        code: error.code,
+        io,
+        message: error.message,
+        stack: error.stack,
+        verbose,
+    });
+}
+function validateFlags(childArgs, options) {
+    if (options.configPath !== undefined && options.count !== undefined) {
+        return err(new PortweaveError(PW_ERROR_CODES.CLI_INVALID_FLAGS, '--config and --count are mutually exclusive'));
+    }
+    if (childArgs.length === 0) {
+        return err(new PortweaveError(PW_ERROR_CODES.CLI_INVALID_FLAGS, 'no command provided after --'));
+    }
+    if (options.count !== undefined &&
+        (!Number.isInteger(options.count) || options.count <= 0)) {
+        return err(new PortweaveError(PW_ERROR_CODES.CLI_INVALID_FLAGS, `--count must be a positive integer, received ${String(options.count)}`));
+    }
+    return { ok: true, value: undefined };
+}
+async function resolveConfig(cwd, options, io) {
+    if (options.count !== undefined) {
+        const result = synthesizeAnonymousConfig(options.count);
+        if (!result.ok) {
+            writePortweaveError(result.error, io, options.verbose);
+            return null;
+        }
+        return result.value;
+    }
+    const result = await loadConfig(cwd, { configPath: options.configPath });
+    if (!result.ok) {
+        writePortweaveError(result.error, io, options.verbose);
+        return null;
+    }
+    return result.value;
+}
+function buildVerboseLines(config, key, env) {
+    const registryPaths = resolveRegistryPath(env);
+    const configLabel = config.sourcePath ??
+        (config.source === 'anonymous' ? '<anonymous-mode>' : '<unknown>');
+    return [
+        `[portweave] config: ${configLabel}`,
+        `[portweave] registry: ${registryPaths.registryFile}`,
+        `[portweave] key: ${JSON.stringify({ gitCommonDir: key.gitCommonDir, namespace: key.namespace, worktreeRoot: key.worktreeRoot })}`,
+    ];
+}
+async function spawnWithBanner(ctx) {
+    const { allocResult, childArgs, config, io, key, options, resolvedEnv } = ctx;
+    const { allocation, reused } = allocResult;
+    const verboseLines = options.verbose
+        ? buildVerboseLines(config, key, io.env)
+        : undefined;
+    io.stderr.write(formatAllocationBanner({
+        allocation,
+        config,
+        launchingCommand: childArgs.join(' '),
+        reused,
+        verboseLines,
+        wroteEnvFile: true,
+    }) + '\n');
+    // Parent env spread last → io.env wins on conflict (DESIGN.md §7.2 row 9: process > .env > computed). Spec step-7 example is inverted.
+    const mergedEnv = { ...resolvedEnv.env, ...io.env };
+    const spawnResult = await spawnChild(childArgs, { env: mergedEnv, io });
+    if (!spawnResult.ok) {
+        writeError({
+            code: spawnResult.error.code,
+            io,
+            message: spawnResult.error.message,
+            verbose: options.verbose,
+        });
+        return 127;
+    }
+    return resolveExitCode(spawnResult.value);
+}
+export async function runCommand(childArgs, options, io = defaultRunIo) {
+    const flagResult = validateFlags(childArgs, options);
+    if (!flagResult.ok) {
+        writeError({
+            code: flagResult.error.code,
+            io,
+            message: flagResult.error.message,
+        });
+        return 1;
+    }
+    const keyResult = resolveAllocationKey(io.cwd());
+    if (!keyResult.ok) {
+        writePortweaveError(keyResult.error, io, options.verbose);
+        return 1;
+    }
+    const key = keyResult.value;
+    const config = await resolveConfig(io.cwd(), options, io);
+    if (config === null) {
+        return 1;
+    }
+    const allocResult = await allocate(key, config, io.env);
+    if (!allocResult.ok) {
+        writePortweaveError(allocResult.error, io, options.verbose);
+        return 1;
+    }
+    const envResult = await resolveEnv(allocResult.value.allocation, config, key.worktreeRoot);
+    if (!envResult.ok) {
+        writePortweaveError(envResult.error, io, options.verbose);
+        return 1;
+    }
+    return spawnWithBanner({
+        allocResult: allocResult.value,
+        childArgs,
+        config,
+        io,
+        key,
+        options,
+        resolvedEnv: envResult.value,
+    });
+}
+export function registerRunCommand(program) {
+    program
+        .command('run')
+        .description('Allocate ports and run a command with env vars injected')
+        .argument('[childArgs...]', 'command and args to run after --')
+        .allowUnknownOption(true)
+        .action(async (childArgs) => {
+        const opts = program.opts();
+        const count = opts.count !== undefined ? Number(opts.count) : undefined;
+        const exitCode = await runCommand(childArgs, {
+            configPath: opts.config,
+            count,
+            verbose: opts.verbose === true,
+        });
+        process.exitCode = exitCode;
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"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"}