@kindgi/cli 0.0.0-bootstrap.0 → 0.1.1

package/dist/dev/postgres-container.js

@@ -0,0 +1,346 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * The bundled Postgres with plain `docker`, for a Docker engine without
+ * `docker compose` (common on a bare Linux engine). `kindgi dev` starts
+ * the same container the compose file defines, read from that file:
+ *
+ *   - the same names: the container (`kindgi-dev_postgres`), its data
+ *     volume (`kindgi-dev_postgres-data`) and the network (`kindgi-dev`),
+ *     so the data is shared whichever way it was started;
+ *   - the same image, environment, command, healthcheck, and the port
+ *     published to a random host port on loopback (`127.0.0.1`): the
+ *     password is a fixed dev one, so the database must not be reachable
+ *     from the LAN;
+ *   - the compose project's labels on what it creates, so
+ *     `docker compose -p kindgi-dev` (`up --no-recreate`, `port`,
+ *     `down -v`) takes them as its own once compose is installed.
+ *
+ * An existing container is reused as it is, whichever way it was
+ * started: started if stopped, never recreated or removed, since
+ * another `kindgi dev` may be using it.
+ */
+import { parse as parseYaml } from 'yaml';
+import { docker } from './runtime-container.js';
+/** The service keys the plain-docker start carries over; any other is refused. */
+const SERVICE_KEYS = new Set([
+    'image',
+    'container_name',
+    'environment',
+    'command',
+    'volumes',
+    'ports',
+    'healthcheck',
+]);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isStringList(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === '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 function postgresSpecFromCompose(composeYaml, project, service = 'postgres') {
+    const unsupported = (what) => new Error(`the compose file's ${service} service: ${what}, which a plain docker start can't carry over`);
+    const file = parseYaml(composeYaml);
+    if (!isRecord(file) || !isRecord(file.services))
+        throw unsupported('no services');
+    const svc = file.services[service];
+    if (!isRecord(svc))
+        throw unsupported('not defined');
+    for (const key of Object.keys(svc)) {
+        if (!SERVICE_KEYS.has(key))
+            throw unsupported(`sets \`${key}\``);
+    }
+    if (typeof svc.image !== 'string')
+        throw unsupported('no image');
+    if (typeof svc.container_name !== 'string')
+        throw unsupported('no container_name');
+    const environment = {};
+    if (svc.environment !== undefined) {
+        if (!isRecord(svc.environment))
+            throw unsupported('environment is not a map');
+        for (const [name, value] of Object.entries(svc.environment)) {
+            if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+                throw unsupported(`environment ${name} has no value`);
+            }
+            environment[name] = String(value);
+        }
+    }
+    const command = svc.command ?? [];
+    if (!isStringList(command))
+        throw unsupported('command is not a list of strings');
+    if (!isStringList(svc.volumes) || svc.volumes.length !== 1) {
+        throw unsupported('not exactly one volume');
+    }
+    const mount = svc.volumes[0] ?? '';
+    const [volumeKey, target, ...rest] = mount.split(':');
+    const volumes = isRecord(file.volumes) ? file.volumes : {};
+    const volumeDef = volumes[volumeKey ?? ''];
+    if (volumeKey === undefined ||
+        target === undefined ||
+        rest.length > 0 ||
+        volumeDef === undefined) {
+        throw unsupported(`volume ${mount} is not a named volume`);
+    }
+    const volumeName = isRecord(volumeDef) && typeof volumeDef.name === 'string'
+        ? volumeDef.name
+        : `${project}_${volumeKey}`;
+    // `5432` or `127.0.0.1::5432`: a random host port, on one address or all.
+    const published = isStringList(svc.ports) && svc.ports.length === 1
+        ? /^(?:(\d{1,3}(?:\.\d{1,3}){3})::)?(\d+)$/.exec(svc.ports[0] ?? '')
+        : null;
+    if (published === null) {
+        throw unsupported('not exactly one port published to a random host port');
+    }
+    const hostIp = published[1];
+    const port = Number(published[2]);
+    const networks = isRecord(file.networks) ? file.networks : {};
+    for (const key of Object.keys(networks)) {
+        if (key !== 'default')
+            throw unsupported(`network ${key}`);
+    }
+    const defaultNetwork = networks.default;
+    const networkName = isRecord(defaultNetwork) && typeof defaultNetwork.name === 'string'
+        ? defaultNetwork.name
+        : `${project}_default`;
+    const hc = svc.healthcheck;
+    if (!isRecord(hc))
+        throw unsupported('no healthcheck');
+    const test = hc.test;
+    const healthCommand = typeof test === 'string'
+        ? test
+        : isStringList(test) && test.length === 2 && test[0] === 'CMD-SHELL'
+            ? test[1]
+            : undefined;
+    if (healthCommand === undefined)
+        throw unsupported('healthcheck test is not CMD-SHELL');
+    for (const key of Object.keys(hc)) {
+        if (!['test', 'interval', 'timeout', 'retries', 'start_period'].includes(key)) {
+            throw unsupported(`healthcheck sets \`${key}\``);
+        }
+    }
+    const duration = (key) => {
+        const value = hc[key];
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== 'string')
+            throw unsupported(`healthcheck ${key} is not a duration`);
+        return value;
+    };
+    if (hc.retries !== undefined && typeof hc.retries !== 'number') {
+        throw unsupported('healthcheck retries is not a number');
+    }
+    const interval = duration('interval');
+    const timeout = duration('timeout');
+    const startPeriod = duration('start_period');
+    return {
+        project,
+        service,
+        name: svc.container_name,
+        image: svc.image,
+        environment,
+        command,
+        volume: { key: volumeKey, name: volumeName, target },
+        network: { key: 'default', name: networkName },
+        port,
+        ...(hostIp !== undefined && { hostIp }),
+        healthcheck: {
+            command: healthCommand,
+            ...(interval !== undefined && { interval }),
+            ...(timeout !== undefined && { timeout }),
+            ...(typeof hc.retries === 'number' && { retries: hc.retries }),
+            ...(startPeriod !== undefined && { startPeriod }),
+        },
+    };
+}
+/**
+ * The compose project's labels for the container: compose finds a
+ * project's containers by them. The config hash is left empty, so compose
+ * takes the definition as changed: `--no-recreate` reuses the container,
+ * and only a recreate asked for (`--recreate-services`) replaces it.
+ */
+function containerLabels(spec) {
+    return [
+        `com.docker.compose.project=${spec.project}`,
+        `com.docker.compose.service=${spec.service}`,
+        'com.docker.compose.oneoff=False',
+        'com.docker.compose.container-number=1',
+        'com.docker.compose.config-hash=',
+    ];
+}
+function labelArgs(labels) {
+    return labels.flatMap((label) => ['--label', label]);
+}
+/** The `docker run` arguments for the container the compose file defines. */
+export function postgresRunArgs(spec) {
+    const args = ['run', '--detach', '--name', spec.name, ...labelArgs(containerLabels(spec))];
+    // On the project's network under its service name, as compose attaches it.
+    args.push('--network', spec.network.name, '--network-alias', spec.service);
+    args.push('--volume', `${spec.volume.name}:${spec.volume.target}`);
+    // `127.0.0.1::5432`: a random host port, on loopback only when the
+    // compose file says so (a fixed dev password stays off the LAN).
+    args.push('--publish', spec.hostIp === undefined ? String(spec.port) : `${spec.hostIp}::${spec.port}`);
+    for (const [name, value] of Object.entries(spec.environment)) {
+        args.push('--env', `${name}=${value}`);
+    }
+    const hc = spec.healthcheck;
+    args.push('--health-cmd', hc.command);
+    if (hc.interval !== undefined)
+        args.push('--health-interval', hc.interval);
+    if (hc.timeout !== undefined)
+        args.push('--health-timeout', hc.timeout);
+    if (hc.retries !== undefined)
+        args.push('--health-retries', String(hc.retries));
+    if (hc.startPeriod !== undefined)
+        args.push('--health-start-period', hc.startPeriod);
+    args.push(spec.image, ...spec.command);
+    return args;
+}
+/**
+ * The host port in `docker port` / `docker compose port` output
+ * (`0.0.0.0:51741`, or `[::]:51741`); `undefined` when there is none.
+ */
+export function hostPortOf(portOutput) {
+    const line = portOutput.trim().split('\n')[0] ?? '';
+    const port = Number(line.slice(line.lastIndexOf(':') + 1));
+    return Number.isInteger(port) && port > 0 ? port : undefined;
+}
+function lastLines(text, n = 5) {
+    return text.trim().split('\n').slice(-n).join('\n');
+}
+function failure(command, outcome) {
+    const detail = lastLines(outcome.stderr);
+    return `\`${command}\` failed (exit ${outcome.code ?? 'spawn error'})${detail === '' ? '' : `: ${detail}`}`;
+}
+/** Create the network or volume when it's missing; an existing one is used as it is. */
+async function ensureResource(kind, name, labels, run) {
+    if ((await run([kind, 'inspect', name])).code === 0)
+        return undefined;
+    const created = await run([kind, 'create', ...labelArgs(labels), name]);
+    if (created.code === 0)
+        return undefined;
+    // Another kindgi dev made it meanwhile.
+    if ((await run([kind, 'inspect', name])).code === 0)
+        return undefined;
+    return failure(`docker ${kind} create ${name}`, created);
+}
+/**
+ * The container's status (`docker container inspect`), or `missing`; an
+ * error when docker can't tell.
+ */
+async function containerStatus(name, run) {
+    const inspected = await run(['container', 'inspect', '--format', '{{.State.Status}}', name]);
+    if (inspected.code === 0)
+        return { status: inspected.stdout.trim() };
+    if (inspected.code !== null && /no such (container|object)/i.test(inspected.stderr)) {
+        return { status: 'missing' };
+    }
+    return { error: failure(`docker container inspect ${name}`, inspected) };
+}
+/** Reuse an existing container as it is: start it when it's stopped. */
+async function reuseContainer(name, status, run) {
+    if (status === 'running' || status === 'restarting')
+        return { kind: 'reused', container: 'running' };
+    if (status === 'created' || status === 'exited') {
+        const started = await run(['start', name]);
+        return started.code === 0
+            ? { kind: 'reused', container: 'started' }
+            : { kind: 'error', message: failure(`docker start ${name}`, started) };
+    }
+    if (status === 'paused') {
+        return {
+            kind: 'error',
+            message: `${name} is paused: unpause it (docker unpause ${name}), then run kindgi dev again`,
+        };
+    }
+    return { kind: 'error', message: `${name} is ${status}` };
+}
+/**
+ * Wait until the container is healthy (or running, without a
+ * healthcheck), as `docker compose up --wait` does; an error when it
+ * turns unhealthy or stops.
+ */
+async function waitHealthy(name, run, wait) {
+    const deadline = Date.now() + wait.timeoutMs;
+    const format = '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{end}}';
+    for (;;) {
+        const inspected = await run(['container', 'inspect', '--format', format, name]);
+        if (inspected.code !== 0)
+            return failure(`docker container inspect ${name}`, inspected);
+        const [status, health] = inspected.stdout.trim().split(/\s+/);
+        if (status === 'running' && (health === undefined || health === 'healthy'))
+            return undefined;
+        const stopped = status === 'exited' || status === 'dead';
+        if (stopped || health === 'unhealthy' || Date.now() > deadline) {
+            const what = stopped
+                ? `stopped while starting (${status})`
+                : health === 'unhealthy'
+                    ? 'is unhealthy'
+                    : `wasn't healthy after ${Math.round(wait.timeoutMs / 1000)}s`;
+            const logs = await run(['logs', '--tail', '15', name]);
+            const tail = lastLines(`${logs.stdout}\n${logs.stderr}`, 15);
+            return `${name} ${what}${tail === '' ? '' : `:\n${tail}`}`;
+        }
+        await new Promise((r) => setTimeout(r, wait.pollMs));
+    }
+}
+/**
+ * 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 async function startPostgresContainer(spec, run = docker, wait = {}) {
+    const found = await containerStatus(spec.name, run);
+    if ('error' in found)
+        return { kind: 'error', message: found.error };
+    let status = found.status;
+    let container;
+    if (status === 'missing') {
+        const project = `com.docker.compose.project=${spec.project}`;
+        const network = await ensureResource('network', spec.network.name, [project, `com.docker.compose.network=${spec.network.key}`], run);
+        if (network !== undefined)
+            return { kind: 'error', message: network };
+        const volume = await ensureResource('volume', spec.volume.name, [project, `com.docker.compose.volume=${spec.volume.key}`], run);
+        if (volume !== undefined)
+            return { kind: 'error', message: volume };
+        const created = await run(postgresRunArgs(spec));
+        if (created.code === 0) {
+            container = 'created';
+        }
+        else {
+            // Another kindgi dev made it meanwhile: reuse that one.
+            const again = await containerStatus(spec.name, run);
+            if ('error' in again || again.status === 'missing') {
+                return { kind: 'error', message: failure(`docker run --name ${spec.name}`, created) };
+            }
+            status = again.status;
+        }
+    }
+    if (container === undefined) {
+        const reused = await reuseContainer(spec.name, status, run);
+        if (reused.kind === 'error')
+            return reused;
+        container = reused.container;
+    }
+    const unhealthy = await waitHealthy(spec.name, run, {
+        timeoutMs: wait.timeoutMs ?? 120_000,
+        pollMs: wait.pollMs ?? 500,
+    });
+    if (unhealthy !== undefined)
+        return { kind: 'error', message: unhealthy };
+    const published = await run(['port', spec.name, String(spec.port)]);
+    const port = published.code === 0 ? hostPortOf(published.stdout) : undefined;
+    if (port === undefined) {
+        return { kind: 'error', message: failure(`docker port ${spec.name} ${spec.port}`, published) };
+    }
+    return { kind: 'ok', port, container };
+}
+//# sourceMappingURL=postgres-container.js.map

package/dist/dev/postgres-container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-container.js","sourceRoot":"","sources":["../../src/dev/postgres-container.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAsB,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAoCpE,kFAAkF;AAClF,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC;IAChD,OAAO;IACP,gBAAgB;IAChB,aAAa;IACb,SAAS;IACT,SAAS;IACT,OAAO;IACP,aAAa;CACd,CAAC,CAAC;AAEH,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;AAC3E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,WAAmB,EACnB,OAAe,EACf,OAAO,GAAG,UAAU;IAEpB,MAAM,WAAW,GAAG,CAAC,IAAY,EAAS,EAAE,CAC1C,IAAI,KAAK,CACP,sBAAsB,OAAO,aAAa,IAAI,+CAA+C,CAC9F,CAAC;IACJ,MAAM,IAAI,GAAY,SAAS,CAAC,WAAW,CAAC,CAAC;IAC7C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,MAAM,WAAW,CAAC,aAAa,CAAC,CAAC;IAClF,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,MAAM,WAAW,CAAC,aAAa,CAAC,CAAC;IACrD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,MAAM,WAAW,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;QAAE,MAAM,WAAW,CAAC,UAAU,CAAC,CAAC;IACjE,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ;QAAE,MAAM,WAAW,CAAC,mBAAmB,CAAC,CAAC;IAEnF,MAAM,WAAW,GAA2B,EAAE,CAAC;IAC/C,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC;YAAE,MAAM,WAAW,CAAC,0BAA0B,CAAC,CAAC;QAC9E,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;gBACzF,MAAM,WAAW,CAAC,eAAe,IAAI,eAAe,CAAC,CAAC;YACxD,CAAC;YACD,WAAW,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAClC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;QAAE,MAAM,WAAW,CAAC,kCAAkC,CAAC,CAAC;IAElF,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,WAAW,CAAC,wBAAwB,CAAC,CAAC;IAC9C,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAC3C,IACE,SAAS,KAAK,SAAS;QACvB,MAAM,KAAK,SAAS;QACpB,IAAI,CAAC,MAAM,GAAG,CAAC;QACf,SAAS,KAAK,SAAS,EACvB,CAAC;QACD,MAAM,WAAW,CAAC,UAAU,KAAK,wBAAwB,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,UAAU,GACd,QAAQ,CAAC,SAAS,CAAC,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;QACvD,CAAC,CAAC,SAAS,CAAC,IAAI;QAChB,CAAC,CAAC,GAAG,OAAO,IAAI,SAAS,EAAE,CAAC;IAEhC,0EAA0E;IAC1E,MAAM,SAAS,GACb,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAC/C,CAAC,CAAC,yCAAyC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACpE,CAAC,CAAC,IAAI,CAAC;IACX,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,WAAW,CAAC,sDAAsD,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAElC,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,IAAI,GAAG,KAAK,SAAS;YAAE,MAAM,WAAW,CAAC,WAAW,GAAG,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC;IACxC,MAAM,WAAW,GACf,QAAQ,CAAC,cAAc,CAAC,IAAI,OAAO,cAAc,CAAC,IAAI,KAAK,QAAQ;QACjE,CAAC,CAAC,cAAc,CAAC,IAAI;QACrB,CAAC,CAAC,GAAG,OAAO,UAAU,CAAC;IAE3B,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC;IAC3B,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,MAAM,WAAW,CAAC,gBAAgB,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;IACrB,MAAM,aAAa,GACjB,OAAO,IAAI,KAAK,QAAQ;QACtB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,WAAW;YAClE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YACT,CAAC,CAAC,SAAS,CAAC;IAClB,IAAI,aAAa,KAAK,SAAS;QAAE,MAAM,WAAW,CAAC,mCAAmC,CAAC,CAAC;IACxF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9E,MAAM,WAAW,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAsB,EAAE;QACnD,MAAM,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,MAAM,WAAW,CAAC,eAAe,GAAG,oBAAoB,CAAC,CAAC;QACzF,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,IAAI,EAAE,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,EAAE,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC/D,MAAM,WAAW,CAAC,qCAAqC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;IAE7C,OAAO;QACL,OAAO;QACP,OAAO;QACP,IAAI,EAAE,GAAG,CAAC,cAAc;QACxB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,WAAW;QACX,OAAO;QACP,MAAM,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE;QACpD,OAAO,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE;QAC9C,IAAI;QACJ,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC;QACvC,WAAW,EAAE;YACX,OAAO,EAAE,aAAa;YACtB,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3C,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC;YACzC,GAAG,CAAC,OAAO,EAAE,CAAC,OAAO,KAAK,QAAQ,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC;YAC9D,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,CAAC;SAClD;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,IAA2B;IAClD,OAAO;QACL,8BAA8B,IAAI,CAAC,OAAO,EAAE;QAC5C,8BAA8B,IAAI,CAAC,OAAO,EAAE;QAC5C,iCAAiC;QACjC,uCAAuC;QACvC,iCAAiC;KAClC,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,MAAyB;IAC1C,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,IAA2B;IACzD,MAAM,IAAI,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,SAAS,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3F,2EAA2E;IAC3E,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3E,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACnE,mEAAmE;IACnE,iEAAiE;IACjE,IAAI,CAAC,IAAI,CACP,WAAW,EACX,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,IAAI,EAAE,CAC/E,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7D,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC;IAC5B,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,EAAE,CAAC,QAAQ,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC3E,IAAI,EAAE,CAAC,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;IACxE,IAAI,EAAE,CAAC,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAChF,IAAI,EAAE,CAAC,WAAW,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC;IACrF,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IACvC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,UAAkB;IAC3C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3D,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,CAAC,GAAG,CAAC;IACpC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,OAAO,CAAC,OAAe,EAAE,OAAsB;IACtD,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,OAAO,KAAK,OAAO,mBAAmB,OAAO,CAAC,IAAI,IAAI,aAAa,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,EAAE,CAAC;AAC9G,CAAC;AAYD,wFAAwF;AACxF,KAAK,UAAU,cAAc,CAC3B,IAA0B,EAC1B,IAAY,EACZ,MAAyB,EACzB,GAAiB;IAEjB,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACtE,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACxE,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,wCAAwC;IACxC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACtE,OAAO,OAAO,CAAC,UAAU,IAAI,WAAW,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,eAAe,CAC5B,IAAY,EACZ,GAAiB;IAEjB,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,mBAAmB,EAAE,IAAI,CAAC,CAAC,CAAC;IAC7F,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;IACrE,IAAI,SAAS,CAAC,IAAI,KAAK,IAAI,IAAI,6BAA6B,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QACpF,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,4BAA4B,IAAI,EAAE,EAAE,SAAS,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED,wEAAwE;AACxE,KAAK,UAAU,cAAc,CAC3B,IAAY,EACZ,MAAc,EACd,GAAiB;IAKjB,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,YAAY;QACjD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;IAClD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC3C,OAAO,OAAO,CAAC,IAAI,KAAK,CAAC;YACvB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE;YAC1C,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,gBAAgB,IAAI,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;IAC3E,CAAC;IACD,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,OAAO;YACL,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,GAAG,IAAI,0CAA0C,IAAI,8BAA8B;SAC7F,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,OAAO,MAAM,EAAE,EAAE,CAAC;AAC5D,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,WAAW,CACxB,IAAY,EACZ,GAAiB,EACjB,IAA6D;IAE7D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;IAC7C,MAAM,MAAM,GAAG,uEAAuE,CAAC;IACvF,SAAS,CAAC;QACR,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;QAChF,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,OAAO,CAAC,4BAA4B,IAAI,EAAE,EAAE,SAAS,CAAC,CAAC;QACxF,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9D,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;QAC7F,MAAM,OAAO,GAAG,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,MAAM,CAAC;QACzD,IAAI,OAAO,IAAI,MAAM,KAAK,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC/D,MAAM,IAAI,GAAG,OAAO;gBAClB,CAAC,CAAC,2BAA2B,MAAM,GAAG;gBACtC,CAAC,CAAC,MAAM,KAAK,WAAW;oBACtB,CAAC,CAAC,cAAc;oBAChB,CAAC,CAAC,wBAAwB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC;YACnE,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YACvD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;YAC7D,OAAO,GAAG,IAAI,IAAI,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QAC7D,CAAC;QACD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACvD,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAA2B,EAC3B,MAAoB,MAAM,EAC1B,OAAkE,EAAE;IAEpE,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACpD,IAAI,OAAO,IAAI,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IAErE,IAAI,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1B,IAAI,SAAwD,CAAC;IAC7D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,8BAA8B,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7D,MAAM,OAAO,GAAG,MAAM,cAAc,CAClC,SAAS,EACT,IAAI,CAAC,OAAO,CAAC,IAAI,EACjB,CAAC,OAAO,EAAE,8BAA8B,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,EAC3D,GAAG,CACJ,CAAC;QACF,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QACtE,MAAM,MAAM,GAAG,MAAM,cAAc,CACjC,QAAQ,EACR,IAAI,CAAC,MAAM,CAAC,IAAI,EAChB,CAAC,OAAO,EAAE,6BAA6B,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EACzD,GAAG,CACJ,CAAC;QACF,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACpE,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QACjD,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACvB,SAAS,GAAG,SAAS,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,wDAAwD;YACxD,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACpD,IAAI,OAAO,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,qBAAqB,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;YACxF,CAAC;YACD,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QACxB,CAAC;IACH,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5D,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,MAAM,CAAC;QAC3C,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IAC/B,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE;QAClD,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,OAAO;QACpC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,GAAG;KAC3B,CAAC,CAAC;IACH,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAE1E,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7E,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,eAAe,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC,EAAE,CAAC;IACjG,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AACzC,CAAC"}

package/dist/dev/python-builder.d.ts

@@ -0,0 +1,16 @@
+import { watch } from 'node:fs';
+import type { PackBuilder } from './runners.js';
+export interface PythonPackBuilderOptions {
+    readonly packDir: string;
+    /** The pack's interpreter (an argv prefix). */
+    readonly python: readonly [string, ...string[]];
+    /** The pack's environment. */
+    readonly env: () => Promise<Readonly<Record<string, string>>>;
+    readonly debounceMs?: number;
+    /** Test seam: `node:fs.watch`. */
+    readonly watchFs?: typeof watch;
+}
+/** Whether a change to `relPath` (relative to the pack root) is a change to the pack's code. */
+export declare function isPythonSourceChange(relPath: string): boolean;
+export declare function createPythonPackBuilder(options: PythonPackBuilderOptions): PackBuilder;
+//# sourceMappingURL=python-builder.d.ts.map

package/dist/dev/python-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-builder.d.ts","sourceRoot":"","sources":["../../src/dev/python-builder.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAkB,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhD,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,cAAc,CAAC;AAgC3D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IAChD,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED,gGAAgG;AAChG,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,WAAW,CAmEtF"}

package/dist/dev/python-builder.js

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * The `PackBuilder` of a Python pack. Python runs its sources, so a build
+ * produces no bundles (an empty bundle map); what it does is the job the
+ * bundler's parse does for a Node pack: compile every `.py` file under the
+ * pack root with the pack's own interpreter and report syntax errors
+ * located `file:line:col`. A build with errors leaves the previous pack
+ * service and index in place, as a bundle error does.
+ *
+ * The watch covers any `.py` file under the pack root — shared modules
+ * outside the discovery folders included — and `pyproject.toml`.
+ */
+import { spawn } from 'node:child_process';
+import { watch } from 'node:fs';
+const SKIPPED_DIRS = ['__pycache__', 'node_modules', 'venv', 'site-packages'];
+const DEFAULT_DEBOUNCE_MS = 150;
+/**
+ * Compiles every source under the pack root (argv[1]); prints a JSON list of
+ * `{file, line, col, message}` for the ones that don't. Self-contained:
+ * nothing of the pack is imported.
+ */
+const COMPILE_SCRIPT = `
+import json, os, sys
+root = sys.argv[1]
+skip = set(${JSON.stringify(SKIPPED_DIRS)})
+errors = []
+for dirpath, dirnames, filenames in os.walk(root):
+    dirnames[:] = sorted(d for d in dirnames if not d.startswith(".") and d not in skip)
+    for name in sorted(filenames):
+        if not name.endswith(".py") or name.startswith("."):
+            continue
+        path = os.path.join(dirpath, name)
+        rel = os.path.relpath(path, root).replace(os.sep, "/")
+        try:
+            with open(path, "rb") as f:
+                compile(f.read(), rel, "exec", dont_inherit=True)
+        except SyntaxError as e:
+            errors.append({"file": rel, "line": e.lineno or 0, "col": e.offset or 0, "message": f"{type(e).__name__}: {e.msg}"})
+        except (ValueError, OSError) as e:
+            errors.append({"file": rel, "line": 0, "col": 0, "message": f"{type(e).__name__}: {e}"})
+print(json.dumps(errors))
+`;
+/** Whether a change to `relPath` (relative to the pack root) is a change to the pack's code. */
+export function isPythonSourceChange(relPath) {
+    const segments = relPath.split(/[\\/]/);
+    const dirs = segments.slice(0, -1);
+    if (dirs.some((s) => s.startsWith('.') || SKIPPED_DIRS.includes(s)))
+        return false;
+    const name = segments[segments.length - 1] ?? '';
+    return relPath === 'pyproject.toml' || (name.endsWith('.py') && !name.startsWith('.'));
+}
+export function createPythonPackBuilder(options) {
+    const watchFs = options.watchFs ?? watch;
+    let watcher;
+    let timer;
+    async function build() {
+        const [program, ...prefix] = options.python;
+        const env = await options.env();
+        const run = await new Promise((resolve) => {
+            const child = spawn(program, [...prefix, '-c', COMPILE_SCRIPT, options.packDir], {
+                env,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.on('data', (chunk) => {
+                stdout += chunk.toString('utf8');
+            });
+            child.stderr.on('data', (chunk) => {
+                stderr += chunk.toString('utf8');
+            });
+            child.once('error', (cause) => resolve({ code: null, stdout, stderr: cause.message }));
+            child.once('close', (code) => resolve({ code, stdout, stderr }));
+        });
+        let errors;
+        try {
+            errors = JSON.parse(run.stdout.trim().split('\n').pop() ?? '');
+        }
+        catch {
+            return {
+                kind: 'err',
+                errors: [
+                    `the pack's Python could not check the sources (${run.code}): ${run.stderr.trim()}`,
+                ],
+            };
+        }
+        if (errors.length > 0) {
+            return {
+                kind: 'err',
+                errors: errors.map((e) => `${e.file}:${e.line}:${e.col}: ${e.message}`),
+            };
+        }
+        return { kind: 'ok', bundleMap: {} };
+    }
+    return {
+        build,
+        async watch(onBuild) {
+            if (watcher !== undefined)
+                return;
+            watcher = watchFs(options.packDir, { recursive: true }, (_event, filename) => {
+                if (filename === null || !isPythonSourceChange(filename.toString()))
+                    return;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                timer = setTimeout(() => {
+                    timer = undefined;
+                    void build().then(onBuild);
+                }, options.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+            });
+        },
+        // New or removed files need no entry list: the next build sees what is there.
+        syncEntries: () => Promise.resolve(false),
+        async dispose() {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            watcher?.close();
+            watcher = undefined;
+        },
+    };
+}
+//# sourceMappingURL=python-builder.js.map

package/dist/dev/python-builder.js.map

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

package/dist/dev/register.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Registration bridge — reports the four pack primitives from the
+ * parsed `index.json` produced by `runIndexer`. This is a pure
+ * read-side reporter: the api-server's disk bindings serve
+ * tool / agent / guardrail / flow manifests directly from disk, so
+ * the CLI doesn't need to POST anything for these primitives.
+ *
+ * Kept as a boundary so `dev.ts` still gets a `RegistrationReport`
+ * shape for boot + watch-tick summaries. Prod deploy path (when
+ * `kindgi deploy` lands) will bring back the transformation +
+ * POST loop this file used to contain, likely in a dedicated
+ * server-side helper rather than the CLI.
+ */
+import type { KindgiClient } from '@kindgi/client';
+import type { AgentId, FlowId, GuardrailId, Semver, ToolId } from '@kindgi/types';
+export interface RegistrationOutcome {
+    readonly kind: 'tool' | 'guardrail' | 'agent' | 'flow';
+    readonly id: string;
+    readonly ok: boolean;
+    readonly message?: string;
+    /**
+     * Non-fatal advisory the CLI surfaces even when `ok === true`.
+     * Currently unused: it used to carry the "bump version to
+     * publish local edits" nudge on `already-registered` outcomes,
+     * but the authoring-tools skill (v0.3.0) explicitly
+     * teaches "don't bump on save" — the advice contradicted itself
+     * and fired every watch tick regardless of whether the primitive
+     * had actually changed. Kept on the interface for future
+     * drift-detection use (compare stored vs. local hash → warn only
+     * on real drift).
+     */
+    readonly warning?: string;
+}
+export interface RegistrationReport {
+    readonly registered: RegistrationOutcome[];
+    readonly failed: RegistrationOutcome[];
+}
+export interface RegisterInputs {
+    readonly index: unknown;
+    readonly apiUrl: string;
+    readonly token: string;
+    readonly client: KindgiClient;
+    readonly fetchImpl: typeof fetch;
+    /**
+     * Tenant's Default project id, resolved by `kindgi dev` from
+     * `RunningApiServer.defaultProjectId`. Included in every POST body
+     * because tools/agents/guardrails/flows routes require it.
+     * Without this, all registrations fail with
+     * `bad-input: projectId is required`.
+     */
+    readonly projectId: string;
+    /**
+     * Absolute path to the pack root. Used to resolve indexer-emitted
+     * relative `modulePath` / `checkModulePath` into absolute paths
+     * before they land in `codeArtifactRef.modulePath` — the sandbox
+     * worker imports them by absolute path, so relative-to-pack won't
+     * resolve after the api-server process (a different cwd) picks
+     * them up.
+     */
+    readonly packDir: string;
+}
+/**
+ * Register every primitive in the parsed index into the running
+ * api-server. Never throws; per-primitive failures land in
+ * `report.failed`. Idempotent-friendly: `409 tool-already-registered`
+ * outcomes are treated as success — dev mode is meant to be safe to
+ * re-run after a save.
+ */
+export declare function registerFromIndex(inputs: RegisterInputs): Promise<RegistrationReport>;
+export type { AgentId, FlowId, GuardrailId, Semver, ToolId };
+//# sourceMappingURL=register.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/dev/register.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAElF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;IACvD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,mBAAmB,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,KAAK,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AASD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA6C3F;AAKD,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC"}

package/dist/dev/register.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Register every primitive in the parsed index into the running
+ * api-server. Never throws; per-primitive failures land in
+ * `report.failed`. Idempotent-friendly: `409 tool-already-registered`
+ * outcomes are treated as success — dev mode is meant to be safe to
+ * re-run after a save.
+ */
+export async function registerFromIndex(inputs) {
+    const idx = (inputs.index ?? {});
+    const registered = [];
+    const failed = [];
+    // All four pack primitives are served from disk in dev — the api-
+    // server's disk bindings (tools, agents, guardrails, flows) read
+    // `index.json` directly. POSTing them
+    // here would round-trip to read-only endpoints. Reporting as
+    // `from-disk` `ok` outcomes so the boot / watch-tick summary line
+    // still shows accurate counts.
+    for (const rawTool of idx.tools ?? []) {
+        registered.push({
+            kind: 'tool',
+            id: String(rawTool.id ?? '(unknown-tool)'),
+            ok: true,
+            message: 'from-disk',
+        });
+    }
+    for (const rawInv of idx.guardrails ?? []) {
+        registered.push({
+            kind: 'guardrail',
+            id: String(rawInv.id ?? '(unknown-guardrail)'),
+            ok: true,
+            message: 'from-disk',
+        });
+    }
+    for (const rawAgent of idx.agents ?? []) {
+        registered.push({
+            kind: 'agent',
+            id: String(rawAgent.id ?? '(unknown-agent)'),
+            ok: true,
+            message: 'from-disk',
+        });
+    }
+    for (const rawGraph of idx.flows ?? []) {
+        registered.push({
+            kind: 'flow',
+            id: String(rawGraph.id ?? '(unknown-flow)'),
+            ok: true,
+            message: 'from-disk',
+        });
+    }
+    return { registered, failed };
+}
+//# sourceMappingURL=register.js.map

package/dist/dev/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/dev/register.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AA2EjC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAAsB;IAC5D,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAe,CAAC;IAC/C,MAAM,UAAU,GAA0B,EAAE,CAAC;IAC7C,MAAM,MAAM,GAA0B,EAAE,CAAC;IAEzC,kEAAkE;IAClE,iEAAiE;IACjE,sCAAsC;IACtC,6DAA6D;IAC7D,kEAAkE;IAClE,+BAA+B;IAC/B,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QACtC,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,MAAM;YACZ,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,gBAAgB,CAAC;YAC1C,EAAE,EAAE,IAAI;YACR,OAAO,EAAE,WAAW;SACrB,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QAC1C,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,WAAW;YACjB,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,qBAAqB,CAAC;YAC9C,EAAE,EAAE,IAAI;YACR,OAAO,EAAE,WAAW;SACrB,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,QAAQ,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QACxC,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,OAAO;YACb,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,iBAAiB,CAAC;YAC5C,EAAE,EAAE,IAAI;YACR,OAAO,EAAE,WAAW;SACrB,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,QAAQ,IAAI,GAAG,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QACvC,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,MAAM;YACZ,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,gBAAgB,CAAC;YAC3C,EAAE,EAAE,IAAI;YACR,OAAO,EAAE,WAAW;SACrB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAChC,CAAC"}