@kindgi/cli 0.0.0-bootstrap.0 → 0.1.1

package/dist/dev/pack-service.js

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * How `kindgi dev` keeps the pack's code and its index in step. The
+ * pack service loads an index once, when it boots, so a change is
+ * picked up in this order:
+ *
+ *   1. bundle the pack's code (esbuild; a watch rebuild hands its result in) —
+ *      for a Python pack, the sources are the build;
+ *   2. index the bundles (or sources) in a child process with the pack's
+ *      environment, into a staging file — the TypeScript indexer, or
+ *      `python -m kindgi.pack index`;
+ *   3. boot a pack service on it — once it listens (every module
+ *      imported), calls go to it and the previous one stops;
+ *   4. publish the staged index as the one the api-server reads.
+ *
+ * So the api-server never lists a tool whose code isn't running. Code
+ * that fails to bundle or to load leaves the previous pack service and
+ * index in place. A pack whose last primitives were deleted publishes an
+ * empty index, so what was deleted stops being listed.
+ *
+ * Refreshes run one at a time. A refresh asked for while one runs waits
+ * for it, and several such requests collapse into one, with the latest
+ * build — so two pack services never start at once.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { devIndexPath, devStagedIndexPath, devStagedPackIndexPath } from './paths.js';
+export function createPackRefresher(deps) {
+    let tail = Promise.resolve();
+    let waiting;
+    let lastGood;
+    async function refreshOnce(given) {
+        const build = given ?? lastGood ?? (await deps.builder.build());
+        if (build.kind === 'err') {
+            return {
+                kind: 'err',
+                code: 'bundle-failed',
+                message: `The pack's code did not build:\n      ${build.errors.join('\n      ')}`,
+            };
+        }
+        lastGood = build;
+        await deps.onBuild?.(build);
+        const staged = devStagedIndexPath(deps.packDir);
+        const indexed = await deps.dev.runIndexer(deps.packDir, staged, {
+            bundleMap: build.bundleMap,
+            env: deps.env,
+            code: deps.code,
+        });
+        if (indexed.kind !== 'ok') {
+            if (indexed.code === 'discovery-empty')
+                await publishEmpty();
+            return indexed;
+        }
+        const packIndex = devStagedPackIndexPath(deps.packDir);
+        await mkdir(dirname(packIndex), { recursive: true });
+        await writeFile(packIndex, JSON.stringify(packServiceIndex(indexed.index, build.bundleMap)), 'utf8');
+        const started = await deps.pack.start(packIndex);
+        if (started.kind === 'err') {
+            return {
+                kind: 'err',
+                code: 'pack-service-boot-failed',
+                message: `The pack's code did not load: ${started.error.problems.join('; ')}`,
+            };
+        }
+        await deps.dev.publishIndex(staged, devIndexPath(deps.packDir));
+        return indexed;
+    }
+    /**
+     * The pack has no primitives left (the last ones were deleted): publish
+     * the previous index's header with nothing in it, so the api-server
+     * stops listing them. Nothing to do before any index was published, or
+     * when the published one is already empty. The pack service keeps its
+     * old code until the next refresh with primitives; nothing calls it.
+     */
+    async function publishEmpty() {
+        const published = devIndexPath(deps.packDir);
+        let previous;
+        try {
+            previous = JSON.parse(await readFile(published, 'utf8'));
+        }
+        catch {
+            return;
+        }
+        const kinds = ['tools', 'guardrails', 'agents', 'flows'];
+        const listed = (kind) => {
+            const entries = previous[kind];
+            return Array.isArray(entries) && entries.length > 0;
+        };
+        if (!kinds.some(listed))
+            return;
+        const staged = devStagedIndexPath(deps.packDir);
+        await mkdir(dirname(staged), { recursive: true });
+        await writeFile(staged, JSON.stringify({
+            ...previous,
+            publishedAt: new Date().toISOString(),
+            tools: [],
+            guardrails: [],
+            agents: [],
+            flows: [],
+        }), 'utf8');
+        await deps.dev.publishIndex(staged, published);
+    }
+    async function guarded(build) {
+        try {
+            return await refreshOnce(build);
+        }
+        catch (cause) {
+            return {
+                kind: 'err',
+                code: 'refresh-failed',
+                message: cause instanceof Error ? cause.message : String(cause),
+            };
+        }
+    }
+    return {
+        refresh(build) {
+            if (waiting !== undefined) {
+                // Collapse into the waiting refresh; the latest build wins.
+                if (build !== undefined)
+                    waiting.build = build;
+                return waiting.result;
+            }
+            const request = { build, result: Promise.resolve(undefined) };
+            request.result = tail.then(() => {
+                if (waiting === request)
+                    waiting = undefined;
+                return guarded(request.build);
+            });
+            waiting = request;
+            tail = request.result;
+            return request.result;
+        },
+        async idle() {
+            await tail;
+        },
+    };
+}
+/**
+ * The index as the pack service reads it: each tool's module and each
+ * guardrail's check module point at their bundles (paths relative to
+ * the pack root, which is the pack service's module root).
+ */
+export function packServiceIndex(index, bundleMap) {
+    const doc = index;
+    const bundled = (path) => typeof path === 'string' ? (bundleMap[path] ?? path) : path;
+    return {
+        ...doc,
+        ...(doc.tools !== undefined && {
+            tools: doc.tools.map((t) => ({ ...t, modulePath: bundled(t.modulePath) })),
+        }),
+        ...(doc.guardrails !== undefined && {
+            guardrails: doc.guardrails.map((g) => ({
+                ...g,
+                checkModulePath: bundled(g.checkModulePath),
+            })),
+        }),
+    };
+}
+/**
+ * The dev console's view of the pack service: what pack code prints,
+ * failed calls, and crashes. Successful calls and restarts that work
+ * stay quiet.
+ */
+/** A pack service log line worth a line of `kindgi dev` output: a failed call, missing env. */
+function describePackLog(event) {
+    const e = event;
+    if (e.kind === 'missing-env' && Array.isArray(e.names)) {
+        const names = e.names.map(String);
+        const one = names.length === 1;
+        return `  ⚠ the pack's env.required ${one ? 'name' : 'names'} ${names.join(', ')} ${one ? 'has' : 'have'} no value: add ${one ? 'it' : 'them'} to the pack's env files (a deployment won't be ready without ${one ? 'it' : 'them'})`;
+    }
+    return e.kind === 'call' && e.outcome !== 'ok'
+        ? `  [pack] ✗ ${String(e.id)}: ${String(e.outcome)}`
+        : undefined;
+}
+export function describePackEvent(event) {
+    switch (event.kind) {
+        case 'exited':
+            return `  ⚠ pack service exited (${event.signal ?? event.code}) — restarting`;
+        case 'gave-up':
+            return `  ✗ pack service kept exiting (${event.attempts} restarts) — fix the code and save to retry`;
+        case 'log':
+            return describePackLog(event.event);
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=pack-service.js.map

package/dist/dev/pack-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-service.js","sourceRoot":"","sources":["../../src/dev/pack-service.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAoCtF,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACzD,IAAI,IAAI,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/C,IAAI,OAA4B,CAAC;IACjC,IAAI,QAA+B,CAAC;IAEpC,KAAK,UAAU,WAAW,CAAC,KAA4B;QACrD,MAAM,KAAK,GAAG,KAAK,IAAI,QAAQ,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAChE,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YACzB,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,eAAe;gBACrB,OAAO,EAAE,yCAAyC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE;aAClF,CAAC;QACJ,CAAC;QACD,QAAQ,GAAG,KAAK,CAAC;QACjB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE;YAC9D,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAC1B,IAAI,OAAO,CAAC,IAAI,KAAK,iBAAiB;gBAAE,MAAM,YAAY,EAAE,CAAC;YAC7D,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,MAAM,SAAS,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvD,MAAM,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,MAAM,SAAS,CACb,SAAS,EACT,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,EAChE,MAAM,CACP,CAAC;QACF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YAC3B,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,0BAA0B;gBAChC,OAAO,EAAE,iCAAiC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;aAC9E,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAChE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,UAAU,YAAY;QACzB,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,QAAiC,CAAC;QACtC,IAAI,CAAC;YACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAA4B,CAAC;QACtF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC;QAClE,MAAM,MAAM,GAAG,CAAC,IAA4B,EAAW,EAAE;YACvD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACtD,CAAC,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO;QAChC,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChD,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,MAAM,SAAS,CACb,MAAM,EACN,IAAI,CAAC,SAAS,CAAC;YACb,GAAG,QAAQ;YACX,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACrC,KAAK,EAAE,EAAE;YACT,UAAU,EAAE,EAAE;YACd,MAAM,EAAE,EAAE;YACV,KAAK,EAAE,EAAE;SACV,CAAC,EACF,MAAM,CACP,CAAC;QACF,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,UAAU,OAAO,CAAC,KAA4B;QACjD,IAAI,CAAC;YACH,OAAO,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,gBAAgB;gBACtB,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAChE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,CAAC,KAAK;YACX,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,4DAA4D;gBAC5D,IAAI,KAAK,KAAK,SAAS;oBAAE,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;gBAC/C,OAAO,OAAO,CAAC,MAAM,CAAC;YACxB,CAAC;YACD,MAAM,OAAO,GAAY,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,SAAkB,CAAC,EAAE,CAAC;YAChF,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;gBAC9B,IAAI,OAAO,KAAK,OAAO;oBAAE,OAAO,GAAG,SAAS,CAAC;gBAC7C,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAChC,CAAC,CAAC,CAAC;YACH,OAAO,GAAG,OAAO,CAAC;YAClB,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;YACtB,OAAO,OAAO,CAAC,MAAM,CAAC;QACxB,CAAC;QACD,KAAK,CAAC,IAAI;YACR,MAAM,IAAI,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAc,EACd,SAA2C;IAE3C,MAAM,GAAG,GAAG,KAGX,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,IAAa,EAAW,EAAE,CACzC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9D,OAAO;QACL,GAAG,GAAG;QACN,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI;YAC7B,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;SAC3E,CAAC;QACF,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI;YAClC,UAAU,EAAE,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACrC,GAAG,CAAC;gBACJ,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;aAC5C,CAAC,CAAC;SACJ,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,+FAA+F;AAC/F,SAAS,eAAe,CAAC,KAAc;IACrC,MAAM,CAAC,GAAG,KAA6E,CAAC;IACxF,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;QAC/B,OAAO,+BAA+B,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,iEAAiE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC;IACvO,CAAC;IACD,OAAO,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI;QAC5C,CAAC,CAAC,cAAc,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE;QACpD,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAiC;IACjE,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,QAAQ;YACX,OAAO,4BAA4B,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,gBAAgB,CAAC;QAChF,KAAK,SAAS;YACZ,OAAO,kCAAkC,KAAK,CAAC,QAAQ,6CAA6C,CAAC;QACvG,KAAK,KAAK;YACR,OAAO,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACtC;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/dev/paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Where `kindgi dev` writes the pack index and the dev api-server reads
+ * it — inside Kindgi's own `.kindgi/` (gitignored), never the pack root,
+ * which may be an existing application's root.
+ */
+export declare function devIndexPath(packDir: string): string;
+/**
+ * Where a re-index writes before the pack service has loaded it. It
+ * becomes `devIndexPath` only once a pack service is serving that code,
+ * so the api-server never lists tools whose code isn't running.
+ */
+export declare function devStagedIndexPath(packDir: string): string;
+/** Where `kindgi dev` bundles the pack's code. */
+export declare function devDistDir(packDir: string): string;
+/**
+ * The staged index as the pack service reads it: the same index, with
+ * each module path pointing at its bundle.
+ */
+export declare function devStagedPackIndexPath(packDir: string): string;
+/** The source → bundle map the indexer child reads. */
+export declare function devBundleMapPath(packDir: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/dev/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/dev/paths.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/dev/paths.js

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { join } from 'node:path';
+/**
+ * Where `kindgi dev` writes the pack index and the dev api-server reads
+ * it — inside Kindgi's own `.kindgi/` (gitignored), never the pack root,
+ * which may be an existing application's root.
+ */
+export function devIndexPath(packDir) {
+    return join(packDir, '.kindgi', 'dev', 'index.json');
+}
+/**
+ * Where a re-index writes before the pack service has loaded it. It
+ * becomes `devIndexPath` only once a pack service is serving that code,
+ * so the api-server never lists tools whose code isn't running.
+ */
+export function devStagedIndexPath(packDir) {
+    return join(packDir, '.kindgi', 'dev', 'index.next.json');
+}
+/** Where `kindgi dev` bundles the pack's code. */
+export function devDistDir(packDir) {
+    return join(packDir, '.kindgi', 'dev', 'dist');
+}
+/**
+ * The staged index as the pack service reads it: the same index, with
+ * each module path pointing at its bundle.
+ */
+export function devStagedPackIndexPath(packDir) {
+    return join(packDir, '.kindgi', 'dev', 'index.next.pack.json');
+}
+/** The source → bundle map the indexer child reads. */
+export function devBundleMapPath(packDir) {
+    return join(packDir, '.kindgi', 'dev', 'bundle-map.json');
+}
+//# sourceMappingURL=paths.js.map

package/dist/dev/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/dev/paths.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC;AAC5D,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,OAAO,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,sBAAsB,CAAC,CAAC;AACjE,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC;AAC5D,CAAC"}

package/dist/dev/postgres-container.d.ts

@@ -0,0 +1,77 @@
+import { type DockerOutcome } from './runtime-container.js';
+/** Runs one `docker` command (`runtime-container.ts`'s `docker`); tests hand in a fake. */
+export type DockerRunner = (args: readonly string[]) => Promise<DockerOutcome>;
+/** The bundled Postgres's container, as the compose file defines it. */
+export interface PostgresContainerSpec {
+    /** The compose project (`kindgi-dev`) and service (`postgres`) it belongs to. */
+    readonly project: string;
+    readonly service: string;
+    /** `container_name`. */
+    readonly name: string;
+    readonly image: string;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly command: readonly string[];
+    /** The named volume: its key in the compose file, its Docker name, and where it's mounted. */
+    readonly volume: {
+        readonly key: string;
+        readonly name: string;
+        readonly target: string;
+    };
+    /** The network: its key in the compose file (`default`) and its Docker name. */
+    readonly network: {
+        readonly key: string;
+        readonly name: string;
+    };
+    /** The container port, published to a random host port. */
+    readonly port: number;
+    /**
+     * The host address it's published on (`127.0.0.1`: loopback only, as
+     * the password is a fixed dev one); all of the host's when absent.
+     */
+    readonly hostIp?: string;
+    readonly healthcheck: {
+        /** Run by the container's shell (`CMD-SHELL`). */
+        readonly command: string;
+        readonly interval?: string;
+        readonly timeout?: string;
+        readonly retries?: number;
+        readonly startPeriod?: string;
+    };
+}
+/**
+ * The container `service` defines in a compose file, for `docker run`.
+ * Strict: a key or shape the plain-docker start can't carry over throws,
+ * so the two ways of starting it never drift apart silently.
+ */
+export declare function postgresSpecFromCompose(composeYaml: string, project: string, service?: string): PostgresContainerSpec;
+/** The `docker run` arguments for the container the compose file defines. */
+export declare function postgresRunArgs(spec: PostgresContainerSpec): string[];
+/**
+ * The host port in `docker port` / `docker compose port` output
+ * (`0.0.0.0:51741`, or `[::]:51741`); `undefined` when there is none.
+ */
+export declare function hostPortOf(portOutput: string): number | undefined;
+/** What `startPostgresContainer` found: the host port, and whether it made, started or reused the container. */
+export type PostgresContainerStart = {
+    readonly kind: 'ok';
+    readonly port: number;
+    /** `created`: none existed; `started`: it was stopped; `running`: reused as it was. */
+    readonly container: 'created' | 'started' | 'running';
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+/**
+ * Start the container `spec` defines with plain `docker`, wait until it's
+ * healthy, and read its host port back:
+ *
+ *   - none exists: create the network and the volume when missing, then
+ *     `docker run` it;
+ *   - it exists, whichever way it was started: reuse it as it is, and
+ *     start it when it's stopped. It is never recreated or removed.
+ */
+export declare function startPostgresContainer(spec: PostgresContainerSpec, run?: DockerRunner, wait?: {
+    readonly timeoutMs?: number;
+    readonly pollMs?: number;
+}): Promise<PostgresContainerStart>;
+//# sourceMappingURL=postgres-container.d.ts.map

package/dist/dev/postgres-container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-container.d.ts","sourceRoot":"","sources":["../../src/dev/postgres-container.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,KAAK,aAAa,EAAU,MAAM,wBAAwB,CAAC;AAEpE,2FAA2F;AAC3F,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAE/E,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1F,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE;QACpB,kDAAkD;QAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH;AAqBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,SAAa,GACnB,qBAAqB,CAqHvB;AAsBD,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAsBrE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIjE;AAWD,gHAAgH;AAChH,MAAM,MAAM,sBAAsB,GAC9B;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;CACvD,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AA2FzD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,qBAAqB,EAC3B,GAAG,GAAE,YAAqB,EAC1B,IAAI,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACnE,OAAO,CAAC,sBAAsB,CAAC,CAoDjC"}