@pleri/olam-cli 0.1.7

package/dist/commands/upgrade.js

@@ -0,0 +1,358 @@
+/**
+ * `olam upgrade` — self-upgrade the local Olam dev stack.
+ *
+ * Runs the full manual sequence in one command:
+ *   git fetch + git pull --ff-only
+ *   npm install
+ *   npm run build
+ *   vite build (SPA)
+ *   bash build-host-cp.sh (image)
+ *   docker compose up -d --force-recreate
+ *   wait for /health
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import pc from 'picocolors';
+import { printError, printSuccess, printInfo, printWarning, printHeader } from '../output.js';
+import { buildComposeEnv, readAuthSecret, runCompose } from './host-cp.js';
+/**
+ * Check whether node_modules is in sync with package-lock.json.
+ *
+ * npm writes node_modules/.package-lock.json after every successful install.
+ * If its mtime is >= package-lock.json's mtime, the last install ran after
+ * the last lockfile change — node_modules is current.
+ *
+ * Returns true  → skip install (node_modules reflects the current lockfile).
+ * Returns false → run install (lockfile changed or marker absent).
+ */
+export function isNodeModulesInSync(cwd) {
+    const lockPath = path.join(cwd, 'package-lock.json');
+    const markerPath = path.join(cwd, 'node_modules', '.package-lock.json');
+    if (!fs.existsSync(lockPath) || !fs.existsSync(markerPath))
+        return false;
+    try {
+        const lockStat = fs.statSync(lockPath);
+        const markerStat = fs.statSync(markerPath);
+        return markerStat.mtimeMs >= lockStat.mtimeMs;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide whether the npm install step should be skipped.
+ *
+ * Priority:
+ *   1. --skip-install flag → always skip
+ *   2. node_modules in sync with lockfile → skip (log reason)
+ *   3. otherwise → run install
+ */
+export function shouldSkipInstall(opts, cwd) {
+    if (opts.skipInstall) {
+        return { skip: true, reason: '--skip-install flag set' };
+    }
+    if (isNodeModulesInSync(cwd)) {
+        return { skip: true, reason: 'node_modules in sync with package-lock.json' };
+    }
+    return { skip: false };
+}
+/** Check cwd looks like the olam repo root. */
+export function validateRepoRoot(cwd) {
+    const marker = path.join(cwd, 'packages/host-cp/compose.yaml');
+    if (!fs.existsSync(marker)) {
+        return {
+            ok: false,
+            error: `Not an olam repo root (expected ${marker}).\n` +
+                'Run `olam upgrade` from the root of your olam checkout.',
+        };
+    }
+    return { ok: true };
+}
+/** Normalise raw Commander option object into typed opts. */
+export function parseUpgradeOpts(raw) {
+    return {
+        yes: raw.yes === true,
+        skipImage: raw.skipImage === true,
+        skipInstall: raw.skipInstall === true,
+        branch: raw.branch ?? null,
+    };
+}
+/**
+ * Extract the JS bundle hash from index.html.
+ * Looks for the canonical Vite output pattern: `/assets/index-<hash>.js`.
+ */
+export function extractBundleHash(indexHtml) {
+    const match = indexHtml.match(/\/assets\/index-([A-Za-z0-9_-]+)\.js/);
+    return match ? (match[1] ?? null) : null;
+}
+function runStep(label, cmd, args, opts = {}) {
+    const start = Date.now();
+    process.stdout.write(`  ${pc.dim(label.padEnd(34))}`);
+    const result = spawnSync(cmd, [...args], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd: opts.cwd ?? process.cwd(),
+        env: { ...process.env, ...(opts.env ?? {}) },
+    });
+    const durationMs = Date.now() - start;
+    const ok = result.status === 0 && result.error === undefined;
+    const dur = `${(durationMs / 1000).toFixed(1)}s`;
+    process.stdout.write(`${ok ? pc.green('✓') : pc.red('✗')} ${dur}\n`);
+    return {
+        ok,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        durationMs,
+    };
+}
+function isGitDirty(cwd) {
+    const result = spawnSync('git', ['status', '--porcelain'], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd,
+    });
+    return (result.stdout ?? '').trim().length > 0;
+}
+function hasGitUpstream(cwd) {
+    const result = spawnSync('git', ['rev-parse', '--abbrev-ref', '@{u}'], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd,
+    });
+    return result.status === 0;
+}
+async function confirm(message) {
+    if (!process.stdin.isTTY)
+        return true;
+    const { createInterface } = await import('node:readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+        });
+    });
+}
+async function waitForHealth(timeoutMs = 10_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch('http://127.0.0.1:19000/health', {
+                signal: AbortSignal.timeout(2000),
+            });
+            if (res.ok)
+                return true;
+        }
+        catch {
+            // not up yet
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    return false;
+}
+function readBundleHash(cwd) {
+    const indexPath = path.join(cwd, 'packages/control-plane/public/index.html');
+    if (!fs.existsSync(indexPath))
+        return null;
+    return extractBundleHash(fs.readFileSync(indexPath, 'utf-8'));
+}
+// ── Main handler ──────────────────────────────────────────────────
+async function handleUpgrade(opts) {
+    const cwd = process.cwd();
+    // 1. Verify repo root.
+    const rootCheck = validateRepoRoot(cwd);
+    if (!rootCheck.ok) {
+        printError(rootCheck.error);
+        process.exitCode = 1;
+        return;
+    }
+    // 2. Print plan.
+    printHeader('olam upgrade');
+    const steps = [
+        'git fetch origin --prune',
+        'git pull --ff-only',
+        'npm install',
+        'npm run build (TS workspaces)',
+        'vite build (SPA)',
+        ...(opts.skipImage ? [] : [
+            'bash build-host-cp.sh (docker image)',
+            'docker compose up -d --force-recreate',
+            'wait for /health',
+        ]),
+    ];
+    printInfo('Steps', steps.join(', '));
+    if (opts.skipImage)
+        printInfo('Mode', '--skip-image: no docker rebuild');
+    if (opts.skipInstall)
+        printInfo('Mode', '--skip-install: npm install will be skipped');
+    if (opts.branch)
+        printInfo('Branch', opts.branch);
+    process.stdout.write('\n');
+    // 3. Confirm unless --yes.
+    if (!opts.yes) {
+        const proceed = await confirm('Proceed?');
+        if (!proceed) {
+            printInfo('Aborted', 'no changes made');
+            return;
+        }
+    }
+    // 4a. Branch switch (--branch).
+    if (opts.branch !== null) {
+        if (isGitDirty(cwd)) {
+            printError(`Working tree is dirty. Stash changes first:\n  git stash\nThen retry with --branch ${opts.branch}`);
+            process.exitCode = 1;
+            return;
+        }
+        const switchResult = runStep(`git checkout ${opts.branch}`, 'git', ['checkout', opts.branch], { cwd });
+        if (!switchResult.ok) {
+            printError(`Failed to switch to branch ${opts.branch}:\n${switchResult.stderr}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // 4b. Dirty check before pull (skip if we just switched).
+    if (opts.branch === null && isGitDirty(cwd)) {
+        printError('Working tree is dirty. Stash or commit changes first:\n  git stash\nThen re-run `olam upgrade`.');
+        process.exitCode = 1;
+        return;
+    }
+    // 4c. Upstream check.
+    if (!hasGitUpstream(cwd)) {
+        printError('Current branch has no upstream remote. Set one first:\n  git branch --set-upstream-to=origin/<branch>\nThen re-run `olam upgrade`.');
+        process.exitCode = 1;
+        return;
+    }
+    const timings = [];
+    // Step a: git fetch.
+    const fetchResult = runStep('git fetch origin --prune', 'git', ['fetch', 'origin', '--prune'], { cwd });
+    timings.push({ label: 'git fetch', durationMs: fetchResult.durationMs });
+    if (!fetchResult.ok) {
+        printError(`git fetch failed:\n${fetchResult.stderr}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Step b: git pull --ff-only.
+    const pullResult = runStep('git pull --ff-only', 'git', ['pull', '--ff-only'], { cwd });
+    timings.push({ label: 'git pull', durationMs: pullResult.durationMs });
+    if (!pullResult.ok) {
+        printError(`git pull --ff-only failed:\n${pullResult.stderr}\n` +
+            'If there are conflicts, resolve them manually then re-run `olam upgrade`.');
+        process.exitCode = 1;
+        return;
+    }
+    // Step c: npm install (skip when in sync or --skip-install).
+    const installDecision = shouldSkipInstall(opts, cwd);
+    if (installDecision.skip) {
+        printInfo('npm install', `skipped — ${installDecision.reason}`);
+        timings.push({ label: 'npm install', durationMs: 0 });
+    }
+    else {
+        const installResult = runStep('npm install', 'npm', ['install', '--silent', '--no-audit', '--no-fund'], { cwd });
+        timings.push({ label: 'npm install', durationMs: installResult.durationMs });
+        if (!installResult.ok) {
+            printError(`npm install failed:\n${installResult.stderr}\n\n` +
+                'Recovery options:\n' +
+                '  • If a native module (e.g. better-sqlite3) failed to compile on your Node version:\n' +
+                '      olam upgrade --skip-install\n' +
+                '    This skips npm install and uses the existing node_modules.\n' +
+                '  • To fix the native module, upgrade it in the relevant package.json,\n' +
+                '    run `npm install` manually, then retry `olam upgrade --skip-install`.');
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // Step d: npm run build (TS workspaces).
+    const buildResult = runStep('npm run build', 'npm', ['run', 'build'], { cwd });
+    timings.push({ label: 'npm run build', durationMs: buildResult.durationMs });
+    if (!buildResult.ok) {
+        printError(`npm run build failed:\n${buildResult.stderr}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Step e: vite build (SPA).
+    const authSecret = readAuthSecret();
+    const spaDir = path.join(cwd, 'packages/control-plane/app');
+    const spaResult = runStep('vite build (SPA)', 'npx', ['vite', 'build'], { cwd: spaDir, env: buildComposeEnv(authSecret) });
+    timings.push({ label: 'vite build (SPA)', durationMs: spaResult.durationMs });
+    if (!spaResult.ok) {
+        printError(`vite build failed:\n${spaResult.stderr}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.skipImage) {
+        // Summary — no docker steps.
+        process.stdout.write('\n');
+        printSuccess('Source rebuilt (--skip-image: docker not touched)');
+        const hash = readBundleHash(cwd);
+        if (hash)
+            printInfo('Bundle hash', hash);
+        printTimings(timings);
+        return;
+    }
+    // Step f: docker image build.
+    const buildScript = path.join(cwd, 'packages/adapters/src/docker/build-host-cp.sh');
+    const imageResult = runStep('bash build-host-cp.sh', 'bash', [buildScript], { cwd });
+    timings.push({ label: 'docker image build', durationMs: imageResult.durationMs });
+    if (!imageResult.ok) {
+        printError(`Docker image build failed:\n${imageResult.stderr}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Step g: docker compose up -d --force-recreate.
+    const composeFile = path.join(cwd, 'packages/host-cp/compose.yaml');
+    process.stdout.write(`  ${pc.dim('docker compose recreate'.padEnd(34))}`);
+    const composeStart = Date.now();
+    const composeResult = runCompose(['up', '-d', '--force-recreate'], composeFile, buildComposeEnv(authSecret));
+    const composeDurationMs = Date.now() - composeStart;
+    const composeOk = composeResult.ok;
+    const composeDur = `${(composeDurationMs / 1000).toFixed(1)}s`;
+    process.stdout.write(`${composeOk ? pc.green('✓') : pc.red('✗')} ${composeDur}\n`);
+    timings.push({ label: 'container recreate', durationMs: composeDurationMs });
+    if (!composeOk) {
+        printError(`docker compose up --force-recreate failed:\n${composeResult.stderr}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Step h: wait for /health.
+    process.stdout.write(`  ${pc.dim('waiting for /health'.padEnd(34))}`);
+    const healthStart = Date.now();
+    const healthy = await waitForHealth(10_000);
+    const healthDurationMs = Date.now() - healthStart;
+    const healthDur = `${(healthDurationMs / 1000).toFixed(1)}s`;
+    process.stdout.write(`${healthy ? pc.green('✓') : pc.yellow('?')} ${healthDur}\n`);
+    timings.push({ label: '/health', durationMs: healthDurationMs });
+    if (!healthy) {
+        printWarning('Host CP started but /health did not respond within 10s. Check: docker logs olam-host-cp');
+    }
+    // 5. Summary.
+    process.stdout.write('\n');
+    printSuccess('Upgrade complete');
+    const hash = readBundleHash(cwd);
+    if (hash)
+        printInfo('Bundle hash', hash);
+    printTimings(timings);
+}
+function printTimings(timings) {
+    const total = timings.reduce((s, t) => s + t.durationMs, 0);
+    process.stdout.write('\n');
+    for (const t of timings) {
+        printInfo(t.label, `${(t.durationMs / 1000).toFixed(1)}s`);
+    }
+    printInfo('total', `${(total / 1000).toFixed(1)}s`);
+}
+// ── Register ──────────────────────────────────────────────────────
+export function registerUpgrade(program) {
+    program
+        .command('upgrade')
+        .description('Self-upgrade the local Olam dev stack (pull + rebuild + restart host-cp)')
+        .option('-y, --yes', 'Skip the confirmation prompt')
+        .option('--skip-image', 'Skip docker image rebuild + container recreate (source rebuild only)')
+        .option('--skip-install', 'Skip npm install entirely (use existing node_modules as-is). ' +
+        'Useful when a native-module build failure blocks the normal upgrade path.')
+        .option('--branch <name>', 'Switch to this branch before pulling (refuses if working tree is dirty)')
+        .action(async (opts) => {
+        await handleUpgrade(parseUpgradeOpts(opts));
+    });
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/commands/upgrade.js.map

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

package/dist/commands/workspace.d.ts

@@ -0,0 +1,23 @@
+/**
+ * olam workspace — manage the named catalog of repo bundles that
+ * worlds instantiate from.
+ *
+ *   olam workspace list                                 list all workspaces
+ *   olam workspace add <name> [--from-config]           create from repeated --repo flags
+ *                             [--repo url[:branch]]...  or from the current project's
+ *                             [--default-branch <b>]    .olam/config.yaml
+ *                             [--force]
+ *   olam workspace show <name>                          pretty-print YAML
+ *   olam workspace remove <name> [--force]              delete a workspace
+ *
+ * Data at `~/.olam/workspaces/<name>.yaml`. Schema is the CF
+ * `Workspace` shape + `updatedAt` — see packages/core/src/workspace.
+ */
+import type { Command } from 'commander';
+export declare function registerWorkspace(program: Command): void;
+/** Ensure a project-scoped workspace exists, called from `olam init`. */
+export declare function ensureProjectWorkspaceFromConfig(projectRoot: string, workspaceName: string): {
+    created: boolean;
+    file: string;
+};
+//# sourceMappingURL=workspace.d.ts.map

package/dist/commands/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/commands/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8CzC,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8HxD;AAED,yEAAyE;AACzE,wBAAgB,gCAAgC,CAC9C,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GACpB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA6BpC"}

package/dist/commands/workspace.js

@@ -0,0 +1,198 @@
+/**
+ * olam workspace — manage the named catalog of repo bundles that
+ * worlds instantiate from.
+ *
+ *   olam workspace list                                 list all workspaces
+ *   olam workspace add <name> [--from-config]           create from repeated --repo flags
+ *                             [--repo url[:branch]]...  or from the current project's
+ *                             [--default-branch <b>]    .olam/config.yaml
+ *                             [--force]
+ *   olam workspace show <name>                          pretty-print YAML
+ *   olam workspace remove <name> [--force]              delete a workspace
+ *
+ * Data at `~/.olam/workspaces/<name>.yaml`. Schema is the CF
+ * `Workspace` shape + `updatedAt` — see packages/core/src/workspace.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import pc from 'picocolors';
+import { stringify as stringifyYaml } from 'yaml';
+import { listWorkspaces, readWorkspace, removeWorkspace, workspacesDir, writeWorkspace, WorkspaceExistsError, WorkspaceNameError, } from '@olam/core/src/workspace/index.js';
+import { loadConfig } from '@olam/core/src/config/loader.js';
+import { printError, printHeader, printInfo, printSuccess } from '../output.js';
+function printWorkspaceNotFound(name) {
+    printError(`No workspace named "${name}" under ${workspacesDir()}`);
+}
+/**
+ * Parse `url` or `url#branch`. Using `#` (not `:`) as the branch
+ * separator because URLs legitimately contain `:` (`https://host:port/...`,
+ * `git@host:user/repo`) which makes `url:branch` ambiguous. `#` never
+ * appears in a repo URL, so this split is unambiguous.
+ */
+function parseRepoFlag(raw) {
+    const hashIdx = raw.indexOf('#');
+    const url = hashIdx === -1 ? raw : raw.slice(0, hashIdx);
+    const branch = hashIdx === -1 ? undefined : raw.slice(hashIdx + 1);
+    if (url.length === 0)
+        throw new Error(`invalid --repo value "${raw}" (empty url)`);
+    if (branch !== undefined && branch.length === 0) {
+        throw new Error(`invalid --repo value "${raw}" (empty branch after #)`);
+    }
+    const nameFromUrl = url
+        .replace(/\.git$/, '')
+        .split(/[\/:]/)
+        .filter(Boolean)
+        .at(-1) ?? 'repo';
+    return branch ? { name: nameFromUrl, url, branch } : { name: nameFromUrl, url };
+}
+export function registerWorkspace(program) {
+    const workspace = program
+        .command('workspace')
+        .description('Manage the named catalog of repo bundles that worlds instantiate from');
+    workspace
+        .command('list')
+        .description('List all workspaces (name, repoCount, updatedAt)')
+        .action(() => {
+        const all = listWorkspaces();
+        if (all.length === 0) {
+            console.log(pc.dim(`No workspaces under ${workspacesDir()}`));
+            return;
+        }
+        printHeader(`${all.length} workspace(s)`);
+        for (const ws of all) {
+            const when = new Date(ws.updatedAt).toISOString().slice(0, 10);
+            console.log(`  ${pc.bold(ws.name.padEnd(24))} ${String(ws.repos.length).padEnd(3)} repos   ${pc.dim(when)}`);
+        }
+    });
+    workspace
+        .command('show')
+        .description('Show a workspace as YAML')
+        .argument('<name>', 'Workspace name')
+        .action((name) => {
+        try {
+            const ws = readWorkspace(name);
+            if (!ws) {
+                printWorkspaceNotFound(name);
+                process.exitCode = 1;
+                return;
+            }
+            process.stdout.write(stringifyYaml(ws));
+        }
+        catch (err) {
+            printError(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    });
+    workspace
+        .command('remove')
+        .description('Delete a workspace (does NOT touch worlds that already referenced it)')
+        .argument('<name>', 'Workspace name')
+        .option('--force', 'Skip confirmation', false)
+        .action((name, _opts) => {
+        try {
+            if (removeWorkspace(name)) {
+                printSuccess(`Removed workspace "${name}"`);
+            }
+            else {
+                printWorkspaceNotFound(name);
+                process.exitCode = 1;
+            }
+        }
+        catch (err) {
+            printError(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    });
+    workspace
+        .command('add')
+        .description('Create a workspace from --from-config (reads current .olam/config.yaml) or repeated --repo flags')
+        .argument('<name>', 'Workspace name')
+        .option('--from-config', 'Seed from the repos in the current project\'s .olam/config.yaml', false)
+        .option('--repo <url>', 'Repeatable. Format: <url> or <url>#<branch>', (val, acc) => {
+        acc.push(parseRepoFlag(val));
+        return acc;
+    }, [])
+        .option('--default-branch <branch>', 'Fallback branch for repos that don\'t specify one')
+        .option('--force', 'Overwrite an existing workspace with the same name', false)
+        .action((name, opts) => {
+        try {
+            const repos = [...opts.repo];
+            if (opts.fromConfig) {
+                try {
+                    const cfg = loadConfig(process.cwd());
+                    for (const r of cfg.repos) {
+                        repos.push({
+                            name: r.name,
+                            url: r.url,
+                            ...(r.submodules ? { submodules: true } : {}),
+                        });
+                    }
+                }
+                catch (err) {
+                    printError(`--from-config: ${err instanceof Error ? err.message : String(err)}`);
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            if (repos.length === 0) {
+                printError('No repos provided — pass --from-config or at least one --repo');
+                process.exitCode = 1;
+                return;
+            }
+            const ws = {
+                name,
+                repos,
+                ...(opts.defaultBranch ? { defaults: { branch: opts.defaultBranch } } : {}),
+                updatedAt: Date.now(),
+            };
+            writeWorkspace(ws, { force: opts.force });
+            const file = path.join(workspacesDir(), `${name}.yaml`);
+            printSuccess(`Created workspace "${name}" (${repos.length} repo${repos.length === 1 ? '' : 's'})`);
+            printInfo('File', file);
+            printInfo('Next', `olam create --name <world> --workspace ${name} --task "..."`);
+        }
+        catch (err) {
+            if (err instanceof WorkspaceExistsError || err instanceof WorkspaceNameError) {
+                printError(err.message);
+                process.exitCode = 1;
+                return;
+            }
+            printError(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    });
+}
+/** Ensure a project-scoped workspace exists, called from `olam init`. */
+export function ensureProjectWorkspaceFromConfig(projectRoot, workspaceName) {
+    const existing = (() => {
+        try {
+            return readWorkspace(workspaceName);
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (existing) {
+        return { created: false, file: path.join(workspacesDir(), `${workspaceName}.yaml`) };
+    }
+    // Derive repos from config.yaml at projectRoot — tolerant of read
+    // failure so init still works when config.yaml is minimal.
+    const cfg = loadConfig(projectRoot);
+    const repos = cfg.repos.map((r) => ({
+        name: r.name,
+        url: r.url,
+        ...(r.submodules ? { submodules: true } : {}),
+    }));
+    const ws = {
+        name: workspaceName,
+        repos,
+        updatedAt: Date.now(),
+    };
+    writeWorkspace(ws);
+    const file = path.join(workspacesDir(), `${workspaceName}.yaml`);
+    return { created: true, file };
+}
+// Silence "fs imported but unused" when caller builds a tree without
+// touching fs directly.
+void fs;
+//# sourceMappingURL=workspace.js.map

package/dist/commands/workspace.js.map

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

package/dist/commands/world-snapshot.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `olam world snapshot` — Phase A snapshot capture/list commands.
+ *
+ * Subcommands:
+ *   create <worldId> --kind gems|node|pg|all
+ *     Capture installed state (gems, node_modules, postgres data) from a
+ *     running world into tarballs under ~/.olam/snapshots/<worldId>/.
+ *     Writes a manifest JSON alongside each tarball.
+ *
+ *   list [--world <id>]
+ *     List captured snapshots with fingerprints, sizes, and ages.
+ *
+ * Phase B (auto-restore on create) and Phase C (eviction / auto-capture)
+ * are NOT wired here — they live in follow-up PRs.
+ */
+import type { Command } from 'commander';
+export declare function registerWorldSnapshot(program: Command): void;
+//# sourceMappingURL=world-snapshot.d.ts.map

package/dist/commands/world-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-snapshot.d.ts","sourceRoot":"","sources":["../../src/commands/world-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8B5D"}