@pleri/olam-cli 0.1.70 → 0.1.72

package/dist/commands/worldspec/compile.js

@@ -0,0 +1,130 @@
+/**
+ * `olam worldspec compile <path>... [--out <dir>] [--no-digests]` —
+ * compile one or more worldspec YAMLs into a deterministic execution-
+ * graph.json + lockfile.json. v1 SEAM contract per Decision #9.
+ *
+ * Multiple paths layer in argument order (later overrides earlier);
+ * matches plan body's "per-project default + orchestrator (highest
+ * priority) + task-level overrides" pattern.
+ *
+ * `--no-digests` skips Docker subprocess invocations (writes <digest-
+ * pending> sentinels). Useful for: dry-run validation, CI environments
+ * where Docker isn't available, deterministic-output tests.
+ *
+ * Defaults output to `./compiled/{execution-graph,lockfile}.json` if
+ * --out is provided; otherwise prints execution-graph to stdout (for
+ * piping / inspection).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import YAML from 'yaml';
+import { canonicalStringify, compileWorldspec, dockerDigestResolver, resolveDigests, WorldspecSchema, } from '@olam/core/src/worldspec/index.js';
+import { EXIT_DIGEST_UNRESOLVED, EXIT_GENERIC_ERROR, EXIT_WORLDSPEC_FILE_NOT_FOUND, EXIT_WORLDSPEC_INVALID, } from '../../exit-codes.js';
+import { printError, printSuccess } from '../../output.js';
+export function registerWorldspecCompile(parent) {
+    parent
+        .command('compile <path...>')
+        .description('Compile worldspec YAMLs into a deterministic execution-graph + lockfile')
+        .option('--out <dir>', 'Write artifacts to <dir>/{execution-graph,lockfile}.json')
+        .option('--no-digests', 'Skip Docker digest resolution (emits <digest-pending> sentinels)')
+        .option('--allow-pending-digests', 'Continue with <digest-pending> sentinels if Docker digest resolution fails (CI / dry-run); without this flag, digest failure exits 23 to preserve Decision #13 fail-fast invariant', false)
+        .action(async (paths, opts) => {
+        // Step 1: load + validate each worldspec
+        const specs = [];
+        const sourcePolicies = [];
+        for (const p of paths) {
+            const abs = resolvePath(process.cwd(), p);
+            if (!existsSync(abs)) {
+                printError(`worldspec not found at ${abs}`);
+                process.exit(EXIT_WORLDSPEC_FILE_NOT_FOUND);
+            }
+            let yaml;
+            try {
+                yaml = YAML.parse(readFileSync(abs, 'utf8'));
+            }
+            catch (err) {
+                printError(`${p}: YAML parse error: ${err.message}`);
+                process.exit(EXIT_WORLDSPEC_INVALID);
+            }
+            const parsed = WorldspecSchema.safeParse(yaml);
+            if (!parsed.success) {
+                printError(`${p}: schema violation — run 'olam worldspec validate ${p}' for details`);
+                process.exit(EXIT_WORLDSPEC_INVALID);
+            }
+            specs.push(parsed.data);
+            sourcePolicies.push(p);
+        }
+        // Step 2: read package version (compilerVersion in execution-graph)
+        const compilerVersion = `@pleri/olam-cli@${getPkgVersion()}`;
+        // Step 3: compile (synchronous; <50ms target)
+        let result;
+        try {
+            result = compileWorldspec(specs, {
+                compilerVersion,
+                sourcePolicies,
+            });
+        }
+        catch (err) {
+            printError(`compile failed: ${err.message}`);
+            process.exit(EXIT_GENERIC_ERROR);
+        }
+        // Step 4: optionally resolve digests via Docker.
+        // MEDIUM fix (A6 CP3 2026-05-09): default behaviour now FAILS FAST
+        // when digest resolution fails. Decision #13 says lockfile records
+        // sha256 for fail-fast at world-spawn; silently committing
+        // <digest-pending> regresses that invariant. Operators who want
+        // dry-run / no-Docker CI explicitly opt in via --allow-pending-digests.
+        let lockfile = result.lockfile;
+        if (opts.digests !== false) {
+            try {
+                lockfile = await resolveDigests(lockfile, dockerDigestResolver);
+            }
+            catch (err) {
+                if (opts.allowPendingDigests) {
+                    process.stderr.write(`warn: digest resolution failed (${err.message}); ` +
+                        `lockfile will contain <digest-pending> sentinels per --allow-pending-digests. ` +
+                        `Re-compile with Docker reachable to populate digests before relying on world-spawn fail-fast.\n`);
+                }
+                else {
+                    printError(`digest resolution failed: ${err.message}\n` +
+                        `Lockfile cannot fail-fast on tampered images without sha256 records (Decision #13).\n` +
+                        `Resolutions:\n` +
+                        `  • Ensure Docker is running + image is locally present (\`docker pull\`)\n` +
+                        `  • Or pass --allow-pending-digests to opt INTO <digest-pending> sentinels (CI / dry-run)\n` +
+                        `  • Or pass --no-digests to skip resolution entirely`);
+                    process.exit(EXIT_DIGEST_UNRESOLVED);
+                }
+            }
+        }
+        // Step 5: emit
+        const graphJson = canonicalStringify(result.executionGraph);
+        const lockfileJson = canonicalStringify(lockfile);
+        if (opts.out) {
+            const outDir = resolvePath(process.cwd(), opts.out);
+            try {
+                mkdirSync(outDir, { recursive: true });
+                writeFileSync(resolvePath(outDir, 'execution-graph.json'), graphJson, 'utf8');
+                writeFileSync(resolvePath(outDir, 'lockfile.json'), lockfileJson, 'utf8');
+                printSuccess(`wrote execution-graph + lockfile to ${outDir}`);
+            }
+            catch (err) {
+                printError(`failed to write ${outDir}: ${err.message}`);
+                process.exit(EXIT_GENERIC_ERROR);
+            }
+        }
+        else {
+            // Stdout: just the execution-graph (lockfile suppressed; use --out for both)
+            process.stdout.write(graphJson);
+        }
+        process.exit(0);
+    });
+}
+function getPkgVersion() {
+    // v1: static fallback. The CLI's actual version comes from its
+    // package.json at publish time; for execution-graph.compilerVersion
+    // the static value is sufficient (deterministic-output tests need a
+    // stable version string anyway). Phase B may wire dynamic version
+    // injection at bundle time.
+    return '0.2.0';
+}
+//# sourceMappingURL=compile.js.map

package/dist/commands/worldspec/compile.js.map

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

package/dist/commands/worldspec/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `olam worldspec` parent command — registers `validate`, `schema`, `init`
+ * subcommands. v1 catalogue. Future subcommands (e.g., `olam worldspec
+ * compile`) will register here.
+ *
+ * Co-exists with the existing `olam policy-check` subcommand (PR-time
+ * `.md` policy enforcement). Decision #10: namespace separation, not
+ * shared. Both surfaces remain after v1 ships.
+ */
+import type { Command } from 'commander';
+export declare function registerWorldspec(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/worldspec/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/worldspec/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAWxD"}

package/dist/commands/worldspec/index.js

@@ -0,0 +1,23 @@
+/**
+ * `olam worldspec` parent command — registers `validate`, `schema`, `init`
+ * subcommands. v1 catalogue. Future subcommands (e.g., `olam worldspec
+ * compile`) will register here.
+ *
+ * Co-exists with the existing `olam policy-check` subcommand (PR-time
+ * `.md` policy enforcement). Decision #10: namespace separation, not
+ * shared. Both surfaces remain after v1 ships.
+ */
+import { registerWorldspecCompile } from './compile.js';
+import { registerWorldspecInit } from './init.js';
+import { registerWorldspecSchema } from './schema.js';
+import { registerWorldspecValidate } from './validate.js';
+export function registerWorldspec(program) {
+    const worldspec = program
+        .command('worldspec')
+        .description('Author + validate + compile .olam/worldspecs/*.yaml — declarative dev-environment contracts');
+    registerWorldspecValidate(worldspec);
+    registerWorldspecSchema(worldspec);
+    registerWorldspecInit(worldspec);
+    registerWorldspecCompile(worldspec);
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/worldspec/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/worldspec/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,MAAM,SAAS,GAAG,OAAO;SACtB,OAAO,CAAC,WAAW,CAAC;SACpB,WAAW,CACV,6FAA6F,CAC9F,CAAC;IAEJ,yBAAyB,CAAC,SAAS,CAAC,CAAC;IACrC,uBAAuB,CAAC,SAAS,CAAC,CAAC;IACnC,qBAAqB,CAAC,SAAS,CAAC,CAAC;IACjC,wBAAwB,CAAC,SAAS,CAAC,CAAC;AACtC,CAAC"}

package/dist/commands/worldspec/init.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `olam worldspec init [--from-adb-yaml]` — scaffold a `default.yaml`
+ * worldspec in the current repo. Detects project shape from existing
+ * files (package.json / Gemfile / .ruby-version / .adb.yaml) and seeds
+ * sensible capability defaults.
+ *
+ * Output: `<cwd>/.olam/worldspecs/default.yaml`
+ *
+ * Idempotent: refuses to overwrite an existing file unless `--force`.
+ * Emits a clear next-step UX line on success (closes Decision-#11
+ * onboarding banner gap surfaced in plan body).
+ */
+import type { Command } from 'commander';
+export declare function registerWorldspecInit(parent: Command): void;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/worldspec/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/worldspec/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBzC,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAyE3D"}

package/dist/commands/worldspec/init.js

@@ -0,0 +1,166 @@
+/**
+ * `olam worldspec init [--from-adb-yaml]` — scaffold a `default.yaml`
+ * worldspec in the current repo. Detects project shape from existing
+ * files (package.json / Gemfile / .ruby-version / .adb.yaml) and seeds
+ * sensible capability defaults.
+ *
+ * Output: `<cwd>/.olam/worldspecs/default.yaml`
+ *
+ * Idempotent: refuses to overwrite an existing file unless `--force`.
+ * Emits a clear next-step UX line on success (closes Decision-#11
+ * onboarding banner gap surfaced in plan body).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { basename, dirname, resolve as resolvePath } from 'node:path';
+import { EXIT_GENERIC_ERROR, EXIT_WORLDSPEC_EXISTS, } from '../../exit-codes.js';
+import { printError, printSuccess } from '../../output.js';
+export function registerWorldspecInit(parent) {
+    parent
+        .command('init')
+        .description('Scaffold a default.yaml worldspec in the current repo (.olam/worldspecs/)')
+        .option('--force', 'Overwrite an existing .olam/worldspecs/default.yaml', false)
+        .option('--from-adb-yaml', 'Read project shape from .adb.yaml when present', false)
+        .action((opts) => {
+        const cwd = process.cwd();
+        const targetDir = resolvePath(cwd, '.olam/worldspecs');
+        const targetFile = resolvePath(targetDir, 'default.yaml');
+        if (existsSync(targetFile) && !opts.force) {
+            printError(`${targetFile} already exists; pass --force to overwrite`);
+            // MEDIUM fix (A3 CP3 audit 2026-05-09): EXIT_WORLDSPEC_EXISTS
+            // distinguishes "you forgot --force" from EXIT_GENERIC_ERROR=1
+            // (internal/parse crash). Pipelines that grep $? can branch.
+            process.exit(EXIT_WORLDSPEC_EXISTS);
+        }
+        // MEDIUM fix (A3 CP3 audit 2026-05-09): warn-then-exit on
+        // --from-adb-yaml — flag was a dead stub (presence-only). Either
+        // ship parser or surface explicit "not yet implemented" so
+        // operators don't assume their .adb.yaml shape was read.
+        if (opts.fromAdbYaml) {
+            printError('--from-adb-yaml is not yet implemented (deferred to v1.1); ' +
+                'remove the flag and re-run, or proceed with manual edit.');
+            process.exit(EXIT_GENERIC_ERROR);
+        }
+        const shape = detectProjectShape(cwd, opts.fromAdbYaml);
+        const yaml = renderWorldspecYaml(shape);
+        try {
+            mkdirSync(targetDir, { recursive: true });
+            // MEDIUM fix (A3 CP3 audit 2026-05-09): use 'wx' flag in
+            // non-force path AND open with 'w' explicitly when --force.
+            // 'wx' refuses if the path exists OR is a symlink → closes
+            // TOCTOU between existsSync above and writeFileSync below.
+            // (existsSync gate above is the user-facing UX; 'wx' is the
+            // race-resistant lower-bound guarantee.)
+            writeFileSync(targetFile, yaml, {
+                encoding: 'utf8',
+                flag: opts.force ? 'w' : 'wx',
+            });
+        }
+        catch (err) {
+            printError(`failed to scaffold ${targetFile}: ${err.message}`);
+            process.exit(EXIT_GENERIC_ERROR);
+        }
+        printSuccess(`scaffolded ${targetFile}`);
+        // Two-arg printInfo expects (label, value); craft a label-less line
+        // via console.log so the next-step UX renders cleanly without padding.
+        console.log(`  Edit it to fit your repo, then run: olam worldspec validate ${relativeFromCwd(targetFile, cwd)}`);
+        process.exit(0);
+    });
+}
+function detectProjectShape(root, useAdbYaml) {
+    const hasGemfile = existsSync(resolvePath(root, 'Gemfile'));
+    const hasNodePackageJson = existsSync(resolvePath(root, 'package.json'));
+    const hasAdbYaml = existsSync(resolvePath(root, '.adb.yaml'));
+    let rubyVersion = null;
+    const rubyVersionPath = resolvePath(root, '.ruby-version');
+    if (existsSync(rubyVersionPath)) {
+        try {
+            const raw = readFileSync(rubyVersionPath, 'utf8').trim();
+            // .ruby-version can be `3.3.0` or `ruby-3.3.0`; extract the SemVer.
+            const match = raw.match(/(\d+\.\d+\.\d+)/);
+            if (match)
+                rubyVersion = match[1] ?? null;
+        }
+        catch {
+            // ignore — fall back to null
+        }
+    }
+    // --from-adb-yaml is a future hook (parse .adb.yaml's runtime block);
+    // for v1 we just record presence so the scaffolded YAML's comment
+    // references it correctly. Real adb-yaml parsing is deferred to v2.
+    void useAdbYaml;
+    return {
+        repoName: getRepoName(root),
+        hasGemfile,
+        rubyVersion,
+        hasNodePackageJson,
+        hasAdbYaml,
+    };
+}
+function getRepoName(root) {
+    try {
+        const url = execSync('git remote get-url origin', {
+            cwd: root,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const match = url.match(/\/([^/]+?)(?:\.git)?$/);
+        if (match && match[1])
+            return match[1];
+    }
+    catch {
+        // not a git repo or no origin; fall back to dir basename
+    }
+    return basename(root);
+}
+function renderWorldspecYaml(shape) {
+    const lines = [];
+    lines.push('# Scaffolded by `olam worldspec init`. Edit to fit your repo.');
+    if (shape.hasAdbYaml) {
+        lines.push('# Detected .adb.yaml — consider migrating its runtime + service blocks here.');
+    }
+    lines.push('schemaVersion: 1');
+    lines.push(`name: ${kebab(shape.repoName)}-default`);
+    lines.push('description: ""');
+    lines.push('repos:');
+    // MEDIUM fix (A3 CP3 audit 2026-05-09): kebab the repoName before
+    // emitting into YAML — git remote URLs can contain newlines / colons
+    // that smuggle YAML structure if interpolated raw (covered by name:
+    // line via kebab() but missed here in the first commit).
+    lines.push(`  - ${kebab(shape.repoName)}`);
+    lines.push('images:');
+    lines.push('  devbox: ghcr.io/REPLACE_ME/olam-devbox:latest');
+    lines.push('  imageSource: local-first');
+    lines.push('capabilities:');
+    if (shape.hasGemfile) {
+        lines.push('  - type: runtime.ruby');
+        lines.push(`    version: "${shape.rubyVersion ?? '3.3.0'}"`);
+        lines.push(`    forRepo: ${kebab(shape.repoName)}`);
+        lines.push('  - type: database.postgres');
+        lines.push('    version: "13"');
+    }
+    if (shape.hasNodePackageJson && !shape.hasGemfile) {
+        lines.push('  # Node.js project detected. runtime.node is deferred to v1.1');
+        lines.push('  # (boot-d hook can pin node version in the meantime).');
+    }
+    lines.push('  - type: auth.ghcr');
+    lines.push('    scopes:');
+    lines.push('      - read:packages');
+    lines.push('  - type: dispatch.readiness');
+    lines.push('    mode: regex');
+    lines.push('    pattern: "❯"');
+    lines.push('');
+    return lines.join('\n');
+}
+function kebab(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function relativeFromCwd(absPath, cwd) {
+    if (absPath.startsWith(cwd + '/'))
+        return absPath.slice(cwd.length + 1);
+    return absPath;
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/worldspec/init.js.map

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

package/dist/commands/worldspec/schema.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `olam worldspec schema --version 1 [--out <path>]` — emit a composite
+ * JSON Schema (Draft 2019-09) for IDE integration (VS Code yaml.schemas,
+ * etc). Single-source-of-truth: derived from WorldspecSchema via
+ * zod-to-json-schema, so v1.x evolution stays in sync without drift.
+ *
+ * Defaults to stdout; pass --out to write a file.
+ */
+import type { Command } from 'commander';
+export declare function registerWorldspecSchema(parent: Command): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/commands/worldspec/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/commands/worldspec/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYzC,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAsD7D"}

package/dist/commands/worldspec/schema.js

@@ -0,0 +1,55 @@
+/**
+ * `olam worldspec schema --version 1 [--out <path>]` — emit a composite
+ * JSON Schema (Draft 2019-09) for IDE integration (VS Code yaml.schemas,
+ * etc). Single-source-of-truth: derived from WorldspecSchema via
+ * zod-to-json-schema, so v1.x evolution stays in sync without drift.
+ *
+ * Defaults to stdout; pass --out to write a file.
+ */
+import { writeFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { WorldspecSchema } from '@olam/core/src/worldspec/index.js';
+import { EXIT_GENERIC_ERROR } from '../../exit-codes.js';
+import { printError, printSuccess } from '../../output.js';
+export function registerWorldspecSchema(parent) {
+    parent
+        .command('schema')
+        .description('Emit composite JSON Schema for the worldspec (IDE / yaml.schemas)')
+        .requiredOption('--version <n>', 'Schema version to emit (currently only 1 is supported)')
+        .option('--out <path>', 'Write JSON Schema to this path instead of stdout')
+        .action((opts) => {
+        if (opts.version !== '1') {
+            printError(`unsupported schema version "${opts.version}"; only "1" is shipped in this CLI`);
+            process.exit(EXIT_GENERIC_ERROR);
+        }
+        // zod-to-json-schema target — explicit Draft 2019-09 (matches
+        // VS Code yaml.schemas + most IDE consumers in the wild;
+        // unevaluatedProperties from Draft 2020-12 is not yet broadly
+        // supported by JSON-Schema-aware editors). When IDE coverage of
+        // 2020-12 catches up, re-evaluate the upgrade. MEDIUM-fix (A3 CP3
+        // audit 2026-05-09): aligned header comment + code + test
+        // expectation on Draft 2019-09 (was inconsistent across all three).
+        const schema = zodToJsonSchema(WorldspecSchema, {
+            name: 'Worldspec',
+            target: 'jsonSchema2019-09',
+            $refStrategy: 'root',
+        });
+        const json = JSON.stringify(schema, null, 2);
+        if (opts.out) {
+            const absPath = resolvePath(process.cwd(), opts.out);
+            try {
+                writeFileSync(absPath, json + '\n', 'utf8');
+            }
+            catch (err) {
+                printError(`failed to write ${absPath}: ${err.message}`);
+                process.exit(EXIT_GENERIC_ERROR);
+            }
+            printSuccess(`wrote JSON Schema (v${opts.version}) to ${absPath}`);
+            process.exit(0);
+        }
+        process.stdout.write(json + '\n');
+        process.exit(0);
+    });
+}
+//# sourceMappingURL=schema.js.map

package/dist/commands/worldspec/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/commands/worldspec/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAGnD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAO3D,MAAM,UAAU,uBAAuB,CAAC,MAAe;IACrD,MAAM;SACH,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CACV,mEAAmE,CACpE;SACA,cAAc,CACb,eAAe,EACf,wDAAwD,CACzD;SACA,MAAM,CACL,cAAc,EACd,kDAAkD,CACnD;SACA,MAAM,CAAC,CAAC,IAAgB,EAAE,EAAE;QAC3B,IAAI,IAAI,CAAC,OAAO,KAAK,GAAG,EAAE,CAAC;YACzB,UAAU,CACR,+BAA+B,IAAI,CAAC,OAAO,oCAAoC,CAChF,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACnC,CAAC;QAED,8DAA8D;QAC9D,yDAAyD;QACzD,8DAA8D;QAC9D,gEAAgE;QAChE,kEAAkE;QAClE,0DAA0D;QAC1D,oEAAoE;QACpE,MAAM,MAAM,GAAG,eAAe,CAAC,eAAe,EAAE;YAC9C,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,mBAAmB;YAC3B,YAAY,EAAE,MAAM;SACrB,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAE7C,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YACrD,IAAI,CAAC;gBACH,aAAa,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;YAC9C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,UAAU,CACR,mBAAmB,OAAO,KAAM,GAAa,CAAC,OAAO,EAAE,CACxD,CAAC;gBACF,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACnC,CAAC;YACD,YAAY,CAAC,uBAAuB,IAAI,CAAC,OAAO,QAAQ,OAAO,EAAE,CAAC,CAAC;YACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/worldspec/validate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `olam worldspec validate <path>` — validate a worldspec YAML against the
+ * v1 schema. Exits 0 on valid, 20 on schema violation, 21 on file-not-found,
+ * 1 on internal error.
+ *
+ * Output format:
+ *   - --format=human (default): location-aware error frames with hints
+ *   - --format=json: structured ValidationError[] for IDE / CI consumption
+ *
+ * Pre-rendered errors carry attacker-controlled strings sanitised via
+ * stripCtrl from @olam/core/worldspec — see error-formatter.ts header.
+ */
+import type { Command } from 'commander';
+export declare function registerWorldspecValidate(parent: Command): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/commands/worldspec/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/commands/worldspec/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiBzC,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA2D/D"}

package/dist/commands/worldspec/validate.js

@@ -0,0 +1,66 @@
+/**
+ * `olam worldspec validate <path>` — validate a worldspec YAML against the
+ * v1 schema. Exits 0 on valid, 20 on schema violation, 21 on file-not-found,
+ * 1 on internal error.
+ *
+ * Output format:
+ *   - --format=human (default): location-aware error frames with hints
+ *   - --format=json: structured ValidationError[] for IDE / CI consumption
+ *
+ * Pre-rendered errors carry attacker-controlled strings sanitised via
+ * stripCtrl from @olam/core/worldspec — see error-formatter.ts header.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { formatValidationErrors, validateWorldspec, } from '@olam/core/src/worldspec/index.js';
+import { EXIT_GENERIC_ERROR, EXIT_WORLDSPEC_FILE_NOT_FOUND, EXIT_WORLDSPEC_INVALID, } from '../../exit-codes.js';
+import { printError, printSuccess } from '../../output.js';
+export function registerWorldspecValidate(parent) {
+    parent
+        .command('validate <path>')
+        .description('Validate a worldspec YAML against the v1 schema')
+        .option('--format <format>', 'Output format: human | json', (value) => {
+        if (value !== 'human' && value !== 'json') {
+            throw new Error(`--format must be 'human' or 'json' (got '${value}')`);
+        }
+        return value;
+    }, 'human')
+        .action(async (pathArg, opts) => {
+        const absPath = resolvePath(process.cwd(), pathArg);
+        if (!existsSync(absPath)) {
+            printError(`worldspec not found at ${absPath}`);
+            process.exit(EXIT_WORLDSPEC_FILE_NOT_FOUND);
+        }
+        let yamlSource;
+        try {
+            yamlSource = readFileSync(absPath, 'utf8');
+        }
+        catch (err) {
+            printError(`failed to read ${absPath}: ${err.message}`);
+            process.exit(EXIT_GENERIC_ERROR);
+        }
+        const result = validateWorldspec(yamlSource);
+        if (result.ok) {
+            if (opts.format === 'json') {
+                process.stdout.write(JSON.stringify({ ok: true }, null, 2) + '\n');
+            }
+            else {
+                printSuccess(`${pathArg}: valid worldspec (schemaVersion: 1)`);
+            }
+            process.exit(0);
+        }
+        if (opts.format === 'json') {
+            process.stdout.write(JSON.stringify({ ok: false, errors: result.errors }, null, 2) + '\n');
+        }
+        else {
+            const formatted = formatValidationErrors(result.errors, {
+                sourcePath: pathArg,
+                yamlSource,
+                color: process.stdout.isTTY,
+            });
+            process.stderr.write(formatted + '\n');
+        }
+        process.exit(EXIT_WORLDSPEC_INVALID);
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/commands/worldspec/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/commands/worldspec/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAGnD,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,kBAAkB,EAClB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAM3D,MAAM,UAAU,yBAAyB,CAAC,MAAe;IACvD,MAAM;SACH,OAAO,CAAC,iBAAiB,CAAC;SAC1B,WAAW,CAAC,iDAAiD,CAAC;SAC9D,MAAM,CACL,mBAAmB,EACnB,6BAA6B,EAC7B,CAAC,KAAa,EAAoB,EAAE;QAClC,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,4CAA4C,KAAK,IAAI,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,EACD,OAAO,CACR;SACA,MAAM,CAAC,KAAK,EAAE,OAAe,EAAE,IAAkB,EAAE,EAAE;QACpD,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC;QAEpD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,UAAU,CAAC,0BAA0B,OAAO,EAAE,CAAC,CAAC;YAChD,OAAO,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;QAC9C,CAAC;QAED,IAAI,UAAkB,CAAC;QACvB,IAAI,CAAC;YACH,UAAU,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,UAAU,CACR,kBAAkB,OAAO,KAAM,GAAa,CAAC,OAAO,EAAE,CACvD,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACnC,CAAC;QAED,MAAM,MAAM,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAE7C,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YACrE,CAAC;iBAAM,CAAC;gBACN,YAAY,CAAC,GAAG,OAAO,sCAAsC,CAAC,CAAC;YACjE,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CACrE,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,SAAS,GAAG,sBAAsB,CAAC,MAAM,CAAC,MAAM,EAAE;gBACtD,UAAU,EAAE,OAAO;gBACnB,UAAU;gBACV,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK;aAC5B,CAAC,CAAC;YACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;QACzC,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/exit-codes.d.ts

@@ -32,4 +32,36 @@ export declare const EXIT_PROTOCOL_MISMATCH = 4;
  * attention" — distinct from EXIT_PLERI_NOT_CONFIGURED (= 2).
  */
 export declare const EXIT_AUTH_NEEDS_ATTENTION = 5;
+/**
+ * `olam worldspec validate` failed because the worldspec violates the
+ * v1 schema (one or more Zod issues surfaced). Plan AC #4 reserves a
+ * worldspec-scoped range (20–29) so future worldspec commands can sub-
+ * distinguish without colliding with codes 1–5 which already carry
+ * CLI-wide meaning.
+ *
+ * `olam worldspec validate <path>`:
+ *   exit 0  → worldspec valid
+ *   exit 20 → schema violation (one or more issues)
+ *   exit 21 → worldspec file not found / not readable
+ *   exit 1  → internal error (parse crash, etc)
+ */
+export declare const EXIT_WORLDSPEC_INVALID = 20;
+export declare const EXIT_WORLDSPEC_FILE_NOT_FOUND = 21;
+/**
+ * `olam worldspec compile` failed to resolve image content-digests
+ * (Docker unreachable / image not present locally). Distinct from
+ * EXIT_GENERIC_ERROR=1 so CI pipelines can fail-fast on lockfile-
+ * digest gaps. Decision #13 invariant: lockfile MUST record digests
+ * for fail-fast at world-spawn. MEDIUM-fix (A6 CP3 audit 2026-05-09):
+ * digest resolution failure now exits 23 by default; `--allow-pending-
+ * digests` opts INTO the soft-warning path for dry-run / no-Docker CI.
+ */
+export declare const EXIT_DIGEST_UNRESOLVED = 23;
+/**
+ * `olam worldspec init` refused to overwrite an existing default.yaml
+ * without `--force`. Distinct from EXIT_GENERIC_ERROR=1 (internal/parse
+ * crash) so pipelines can distinguish "user forgot --force" from
+ * "something is broken." A3 CP3 audit MEDIUM-fix 2026-05-09.
+ */
+export declare const EXIT_WORLDSPEC_EXISTS = 22;
 //# sourceMappingURL=exit-codes.d.ts.map

package/dist/exit-codes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC"}
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC"}

package/dist/exit-codes.js

@@ -32,4 +32,36 @@ export const EXIT_PROTOCOL_MISMATCH = 4;
  * attention" — distinct from EXIT_PLERI_NOT_CONFIGURED (= 2).
  */
 export const EXIT_AUTH_NEEDS_ATTENTION = 5;
+/**
+ * `olam worldspec validate` failed because the worldspec violates the
+ * v1 schema (one or more Zod issues surfaced). Plan AC #4 reserves a
+ * worldspec-scoped range (20–29) so future worldspec commands can sub-
+ * distinguish without colliding with codes 1–5 which already carry
+ * CLI-wide meaning.
+ *
+ * `olam worldspec validate <path>`:
+ *   exit 0  → worldspec valid
+ *   exit 20 → schema violation (one or more issues)
+ *   exit 21 → worldspec file not found / not readable
+ *   exit 1  → internal error (parse crash, etc)
+ */
+export const EXIT_WORLDSPEC_INVALID = 20;
+export const EXIT_WORLDSPEC_FILE_NOT_FOUND = 21;
+/**
+ * `olam worldspec compile` failed to resolve image content-digests
+ * (Docker unreachable / image not present locally). Distinct from
+ * EXIT_GENERIC_ERROR=1 so CI pipelines can fail-fast on lockfile-
+ * digest gaps. Decision #13 invariant: lockfile MUST record digests
+ * for fail-fast at world-spawn. MEDIUM-fix (A6 CP3 audit 2026-05-09):
+ * digest resolution failure now exits 23 by default; `--allow-pending-
+ * digests` opts INTO the soft-warning path for dry-run / no-Docker CI.
+ */
+export const EXIT_DIGEST_UNRESOLVED = 23;
+/**
+ * `olam worldspec init` refused to overwrite an existing default.yaml
+ * without `--force`. Distinct from EXIT_GENERIC_ERROR=1 (internal/parse
+ * crash) so pipelines can distinguish "user forgot --force" from
+ * "something is broken." A3 CP3 audit MEDIUM-fix 2026-05-09.
+ */
+export const EXIT_WORLDSPEC_EXISTS = 22;
 //# sourceMappingURL=exit-codes.js.map

package/dist/exit-codes.js.map

@@ -1 +1 @@
-{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC"}
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC"}