@pleri/olam-cli 0.1.12 → 0.1.14

package/dist/index.js.map

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

package/dist/protocol-version.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Devbox image protocol-version handshake (Decision #14).
+ *
+ * Closes T13 — cross-namespace protocol skew between CLI and overridden
+ * devbox image (e.g. atlas devbox v0.5 + CLI 0.2 with new host-cp wire
+ * format). Without this handshake, a CLI/devbox version mismatch
+ * silently corrupts; with it, the CLI refuses to start the world and
+ * exits with a named code + actionable remedy.
+ *
+ * Contract: every devbox image declares `LABEL olam.protocol.versions=
+ * "<comma-separated-major-list>"` (see docs/architecture/devbox-contract.md
+ * §1). The CLI carries a compiled-in `OLAM_PROTOCOL_VERSIONS_SUPPORTED`
+ * list and demands non-empty intersection with the image's declaration
+ * post-pull, before any container is started.
+ */
+/**
+ * Protocol versions this CLI release knows how to drive.
+ *
+ * **Bump procedure**:
+ *   1. When the CLI ↔ host-cp wire format gains a backward-incompatible
+ *      change, append the new version to this list.
+ *   2. Update `packages/adapters/src/docker/devbox.Dockerfile` to set
+ *      `LABEL olam.protocol.versions="<old>,<new>"` during the
+ *      deprecation window (typically 2 minor releases).
+ *   3. Drop the old version from this list once the deprecation window
+ *      closes.
+ *
+ * **Compatibility rule**: a CLI MAY support newer versions than its
+ * devbox declares — pick the highest mutually-supported version at
+ * handshake time. Empty intersection → refuse with EXIT_PROTOCOL_MISMATCH.
+ */
+export declare const OLAM_PROTOCOL_VERSIONS_SUPPORTED: readonly number[];
+/**
+ * Parse the value of `olam.protocol.versions` LABEL into a sorted,
+ * deduplicated list of major-version integers. Tolerates whitespace,
+ * empty strings, and malformed entries (silently skipped — the CLI's
+ * empty-intersection check handles "image declares nothing valid").
+ */
+export declare function parseProtocolVersionsLabel(labelValue: string | undefined | null): number[];
+export interface ProtocolHandshake {
+    readonly overlap: number[];
+    readonly imageVersions: number[];
+    readonly cliVersions: readonly number[];
+    readonly compatible: boolean;
+    readonly remedy: string;
+}
+/**
+ * Check whether the image's declared protocol versions overlap with the
+ * CLI's supported list. Returns the overlap (empty when incompatible)
+ * plus a named-remedy string for stderr emission on `compatible: false`.
+ *
+ * The remedy names BOTH version sets so the operator can see exactly
+ * why the handshake failed and which CLI version pins they should try.
+ */
+export declare function checkProtocolOverlap(imageVersions: readonly number[], cliVersions?: readonly number[]): ProtocolHandshake;
+/**
+ * Read the `olam.protocol.versions` LABEL from a docker image via
+ * `docker inspect`. Returns the parsed version list (empty if the label
+ * is absent or malformed — the caller routes that into
+ * `checkProtocolOverlap` which produces the missing-LABEL remedy).
+ *
+ * Exposed as a separate function so tests can stub the docker call by
+ * passing a mock implementation through `dockerInspect` (see test file).
+ */
+export interface DockerInspectFn {
+    (imageRef: string): {
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    };
+}
+export interface InspectResult {
+    readonly imageRef: string;
+    readonly versions: number[];
+    readonly inspectFailed: boolean;
+    readonly inspectError: string | undefined;
+}
+export declare function inspectImageProtocolVersions(imageRef: string, dockerInspect?: DockerInspectFn): InspectResult;
+//# sourceMappingURL=protocol-version.d.ts.map

package/dist/protocol-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-version.d.ts","sourceRoot":"","sources":["../src/protocol-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gCAAgC,EAAE,SAAS,MAAM,EAAiB,CAAC;AAEhF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,EAAE,CAW1F;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,WAAW,GAAE,SAAS,MAAM,EAAqC,GAChE,iBAAiB,CA8CnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1E;AAeD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,EAChB,aAAa,GAAE,eAAmC,GACjD,aAAa,CAqBf"}

package/dist/protocol-version.js

@@ -0,0 +1,133 @@
+/**
+ * Devbox image protocol-version handshake (Decision #14).
+ *
+ * Closes T13 — cross-namespace protocol skew between CLI and overridden
+ * devbox image (e.g. atlas devbox v0.5 + CLI 0.2 with new host-cp wire
+ * format). Without this handshake, a CLI/devbox version mismatch
+ * silently corrupts; with it, the CLI refuses to start the world and
+ * exits with a named code + actionable remedy.
+ *
+ * Contract: every devbox image declares `LABEL olam.protocol.versions=
+ * "<comma-separated-major-list>"` (see docs/architecture/devbox-contract.md
+ * §1). The CLI carries a compiled-in `OLAM_PROTOCOL_VERSIONS_SUPPORTED`
+ * list and demands non-empty intersection with the image's declaration
+ * post-pull, before any container is started.
+ */
+import { spawnSync } from 'node:child_process';
+/**
+ * Protocol versions this CLI release knows how to drive.
+ *
+ * **Bump procedure**:
+ *   1. When the CLI ↔ host-cp wire format gains a backward-incompatible
+ *      change, append the new version to this list.
+ *   2. Update `packages/adapters/src/docker/devbox.Dockerfile` to set
+ *      `LABEL olam.protocol.versions="<old>,<new>"` during the
+ *      deprecation window (typically 2 minor releases).
+ *   3. Drop the old version from this list once the deprecation window
+ *      closes.
+ *
+ * **Compatibility rule**: a CLI MAY support newer versions than its
+ * devbox declares — pick the highest mutually-supported version at
+ * handshake time. Empty intersection → refuse with EXIT_PROTOCOL_MISMATCH.
+ */
+export const OLAM_PROTOCOL_VERSIONS_SUPPORTED = [1];
+/**
+ * Parse the value of `olam.protocol.versions` LABEL into a sorted,
+ * deduplicated list of major-version integers. Tolerates whitespace,
+ * empty strings, and malformed entries (silently skipped — the CLI's
+ * empty-intersection check handles "image declares nothing valid").
+ */
+export function parseProtocolVersionsLabel(labelValue) {
+    if (!labelValue)
+        return [];
+    const parts = labelValue.split(',').map((s) => s.trim()).filter(Boolean);
+    const versions = new Set();
+    for (const part of parts) {
+        const n = Number.parseInt(part, 10);
+        if (Number.isFinite(n) && n > 0 && String(n) === part) {
+            versions.add(n);
+        }
+    }
+    return Array.from(versions).sort((a, b) => a - b);
+}
+/**
+ * Check whether the image's declared protocol versions overlap with the
+ * CLI's supported list. Returns the overlap (empty when incompatible)
+ * plus a named-remedy string for stderr emission on `compatible: false`.
+ *
+ * The remedy names BOTH version sets so the operator can see exactly
+ * why the handshake failed and which CLI version pins they should try.
+ */
+export function checkProtocolOverlap(imageVersions, cliVersions = OLAM_PROTOCOL_VERSIONS_SUPPORTED) {
+    const cliSet = new Set(cliVersions);
+    const overlap = imageVersions.filter((v) => cliSet.has(v));
+    if (imageVersions.length === 0) {
+        return {
+            overlap: [],
+            imageVersions: [],
+            cliVersions,
+            compatible: false,
+            remedy: 'Devbox image is missing the `olam.protocol.versions` LABEL. ' +
+                `This CLI requires versions [${cliVersions.join(', ')}]. ` +
+                'See docs/architecture/devbox-contract.md §1 for the contract; ' +
+                'rebuild the image with `LABEL olam.protocol.versions="1"`.',
+        };
+    }
+    if (overlap.length === 0) {
+        const imgLow = Math.min(...imageVersions);
+        const imgHigh = Math.max(...imageVersions);
+        const cliLow = Math.min(...cliVersions);
+        const cliHigh = Math.max(...cliVersions);
+        return {
+            overlap: [],
+            imageVersions: [...imageVersions],
+            cliVersions,
+            compatible: false,
+            remedy: `Devbox image protocol versions [${imageVersions.join(', ')}] ` +
+                `don't overlap CLI's [${cliVersions.join(', ')}]. ` +
+                (imgHigh < cliLow
+                    ? `The image is older than this CLI supports — rebuild against the contract version ${cliLow}+ at docs/architecture/devbox-contract.md.`
+                    : imgLow > cliHigh
+                        ? `The image is newer than this CLI supports — pin a compatible CLI: \`npm install -g @pleri/olam-cli@<version-with-protocol-${imgLow}>\`.`
+                        : `Pin a compatible CLI version that overlaps with the image's range.`),
+        };
+    }
+    return {
+        overlap,
+        imageVersions: [...imageVersions],
+        cliVersions,
+        compatible: true,
+        remedy: '',
+    };
+}
+const realDockerInspect = (imageRef) => {
+    const result = spawnSync('docker', ['inspect', imageRef, '--format', '{{ index .Config.Labels "olam.protocol.versions" }}'], { encoding: 'utf8', timeout: 10_000 });
+    return {
+        exitCode: result.status ?? -1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+};
+export function inspectImageProtocolVersions(imageRef, dockerInspect = realDockerInspect) {
+    const { exitCode, stdout, stderr } = dockerInspect(imageRef);
+    if (exitCode !== 0) {
+        return {
+            imageRef,
+            versions: [],
+            inspectFailed: true,
+            inspectError: stderr.trim() || `docker inspect exited ${exitCode}`,
+        };
+    }
+    // `docker inspect --format` for a missing LABEL returns the literal
+    // string "<no value>" or just an empty newline depending on engine
+    // version. Parse defensively.
+    const raw = stdout.trim();
+    const value = raw === '<no value>' ? '' : raw;
+    return {
+        imageRef,
+        versions: parseProtocolVersionsLabel(value),
+        inspectFailed: false,
+        inspectError: undefined,
+    };
+}
+//# sourceMappingURL=protocol-version.js.map

package/dist/protocol-version.js.map

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

package/dist/registry-allowlist.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Registry allowlist for `OLAM_DEVBOX_IMAGE` overrides.
+ *
+ * Closes T9 — unconstrained env-var overrides redirecting docker pulls
+ * to attacker-controlled images. The default allowlist is `ghcr.io/pleri/*`
+ * (the namespace olam itself publishes to). Out-of-allowlist refs require
+ * the explicit `--allow-custom-registry` CLI flag.
+ *
+ * Decision #19 dropped the env-var bypass form (`OLAM_ALLOW_CUSTOM_REGISTRY=1`)
+ * to avoid ambient bypass via shell inheritance / CI-secret leakage. Flag-only.
+ *
+ * Atlas-parity (Decision #15) lives at `ghcr.io/pleri/olam-devbox-atlas:<v>`
+ * — same `pleri` namespace, so the allowlist accepts it without the flag.
+ * Other extenders publishing under their own org (e.g. `ghcr.io/atlas/atlas-devbox`)
+ * must pass `--allow-custom-registry` per invocation.
+ */
+export interface AllowlistDecision {
+    readonly imageRef: string;
+    readonly allowedByDefault: boolean;
+    /**
+     * `true` when:
+     *   - allowedByDefault, OR
+     *   - the operator passed --allow-custom-registry.
+     */
+    readonly accepted: boolean;
+    /**
+     * The stderr line to emit before pull (or rejection). Always populated:
+     *   - allowedByDefault   → empty string (no warning needed)
+     *   - allowed-via-flag   → warning line ("using custom devbox image …")
+     *   - rejected (no flag) → error line ("custom registry blocked; use --allow-custom-registry to override")
+     */
+    readonly stderrLine: string;
+}
+/** Sentinel to keep call sites readable and the API explicit. */
+export interface AllowlistInput {
+    readonly imageRef: string;
+    readonly allowCustomRegistry: boolean;
+}
+export declare function decideAllowlist(input: AllowlistInput): AllowlistDecision;
+/**
+ * Resolve the devbox-image reference from the operator's input, in
+ * order of precedence: explicit CLI flag > env var > default. Returns
+ * `undefined` when neither flag nor env var is set — caller falls back
+ * to the digest-pinned default from `image-digests.json` (Phase B).
+ */
+export declare function resolveDevboxImageOverride(flagValue: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=registry-allowlist.d.ts.map

package/dist/registry-allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-allowlist.d.ts","sourceRoot":"","sources":["../src/registry-allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACvC;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,iBAAiB,CAkCxE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CASpB"}

package/dist/registry-allowlist.js

@@ -0,0 +1,67 @@
+/**
+ * Registry allowlist for `OLAM_DEVBOX_IMAGE` overrides.
+ *
+ * Closes T9 — unconstrained env-var overrides redirecting docker pulls
+ * to attacker-controlled images. The default allowlist is `ghcr.io/pleri/*`
+ * (the namespace olam itself publishes to). Out-of-allowlist refs require
+ * the explicit `--allow-custom-registry` CLI flag.
+ *
+ * Decision #19 dropped the env-var bypass form (`OLAM_ALLOW_CUSTOM_REGISTRY=1`)
+ * to avoid ambient bypass via shell inheritance / CI-secret leakage. Flag-only.
+ *
+ * Atlas-parity (Decision #15) lives at `ghcr.io/pleri/olam-devbox-atlas:<v>`
+ * — same `pleri` namespace, so the allowlist accepts it without the flag.
+ * Other extenders publishing under their own org (e.g. `ghcr.io/atlas/atlas-devbox`)
+ * must pass `--allow-custom-registry` per invocation.
+ */
+const DEFAULT_ALLOWLIST_PATTERNS = [
+    // ghcr.io/pleri/<anything>:<tag> or ghcr.io/pleri/<anything>@sha256:<digest>
+    /^ghcr\.io\/pleri\/[^/\s]+(?::[^\s]+|@sha256:[a-f0-9]+)?$/,
+];
+export function decideAllowlist(input) {
+    const { imageRef, allowCustomRegistry } = input;
+    const allowedByDefault = DEFAULT_ALLOWLIST_PATTERNS.some((re) => re.test(imageRef));
+    if (allowedByDefault) {
+        return {
+            imageRef,
+            allowedByDefault: true,
+            accepted: true,
+            stderrLine: '',
+        };
+    }
+    if (allowCustomRegistry) {
+        return {
+            imageRef,
+            allowedByDefault: false,
+            accepted: true,
+            stderrLine: `Warning: using custom devbox image '${imageRef}'. ` +
+                `(--allow-custom-registry was specified.) ` +
+                `Verify the source and digest before proceeding.`,
+        };
+    }
+    return {
+        imageRef,
+        allowedByDefault: false,
+        accepted: false,
+        stderrLine: `Error: image '${imageRef}' is outside allowed registries (ghcr.io/pleri/*).\n` +
+            `  To override: re-run with --allow-custom-registry\n` +
+            `  Verify the source and digest before doing so.`,
+    };
+}
+/**
+ * Resolve the devbox-image reference from the operator's input, in
+ * order of precedence: explicit CLI flag > env var > default. Returns
+ * `undefined` when neither flag nor env var is set — caller falls back
+ * to the digest-pinned default from `image-digests.json` (Phase B).
+ */
+export function resolveDevboxImageOverride(flagValue, env = process.env) {
+    if (flagValue && flagValue.trim().length > 0) {
+        return flagValue.trim();
+    }
+    const envValue = env.OLAM_DEVBOX_IMAGE;
+    if (envValue && envValue.trim().length > 0) {
+        return envValue.trim();
+    }
+    return undefined;
+}
+//# sourceMappingURL=registry-allowlist.js.map

package/dist/registry-allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-allowlist.js","sourceRoot":"","sources":["../src/registry-allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,0BAA0B,GAAsB;IACpD,6EAA6E;IAC7E,0DAA0D;CAClD,CAAC;AA0BX,MAAM,UAAU,eAAe,CAAC,KAAqB;IACnD,MAAM,EAAE,QAAQ,EAAE,mBAAmB,EAAE,GAAG,KAAK,CAAC;IAChD,MAAM,gBAAgB,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEpF,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO;YACL,QAAQ;YACR,gBAAgB,EAAE,IAAI;YACtB,QAAQ,EAAE,IAAI;YACd,UAAU,EAAE,EAAE;SACf,CAAC;IACJ,CAAC;IAED,IAAI,mBAAmB,EAAE,CAAC;QACxB,OAAO;YACL,QAAQ;YACR,gBAAgB,EAAE,KAAK;YACvB,QAAQ,EAAE,IAAI;YACd,UAAU,EACR,uCAAuC,QAAQ,KAAK;gBACpD,2CAA2C;gBAC3C,iDAAiD;SACpD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ;QACR,gBAAgB,EAAE,KAAK;QACvB,QAAQ,EAAE,KAAK;QACf,UAAU,EACR,iBAAiB,QAAQ,sDAAsD;YAC/E,sDAAsD;YACtD,iDAAiD;KACpD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,SAA6B,EAC7B,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7C,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,iBAAiB,CAAC;IACvC,IAAI,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pleri/olam-cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "type": "module",
   "bin": {
     "olam": "./dist/index.js"