@pleri/olam-cli 0.1.11 → 0.1.13

package/dist/commands/upgrade-log.js

@@ -0,0 +1,146 @@
+/**
+ * `~/.olam/upgrade.log` — JSONL append-only audit log for `olam upgrade`.
+ *
+ * Phase 2c — C1.
+ *
+ * Schema:
+ *   {
+ *     ts: ISO 8601,
+ *     started_at: epoch ms,
+ *     ended_at: epoch ms,
+ *     sha_target: string (40-char SHA, captured-after-pull),
+ *     sha_before: { hostCp, authService, devbox },
+ *     sha_after:  { hostCp, authService, devbox },
+ *     status: "success" | "failed" | "rolled_back",
+ *     failed_step: string | null,
+ *     durations_ms: { [step_label]: number }
+ *   }
+ *
+ * Open-per-write semantics — open() + write() + close() per row so
+ * external log-rotators can rename the file mid-run without us writing
+ * to a now-unlinked fd. Best-effort; errors logged to stderr and
+ * swallowed so the audit log never blocks an upgrade from completing.
+ *
+ * `failed_step` MUST hold a step LABEL only (e.g. "bash build-auth.sh"),
+ * NEVER raw stdout/stderr — paths and credentials may leak. (Per audit
+ * security finding A6-007.) The CLI's terminal already shows the full
+ * stderr; the log row records the step name for queryability.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/**
+ * Resolve the upgrade-log path lazily so tests can override HOME via
+ * process.env. Lazy resolution is also forward-compatible with operators
+ * who set XDG_DATA_HOME or similar overrides at session start.
+ */
+export function getUpgradeLogPath() {
+    const home = process.env['HOME'] ?? os.homedir();
+    return path.join(home, '.olam', 'upgrade.log');
+}
+/** Convenience constant for callers who want the production path string. */
+export const UPGRADE_LOG_PATH = getUpgradeLogPath();
+/**
+ * Append a single row to ~/.olam/upgrade.log.
+ *
+ * Open-per-write to survive log rotation. Errors swallowed to stderr —
+ * audit log failure must never block an upgrade.
+ *
+ * `logPath` parameter is a test seam; production callers omit it.
+ */
+export function appendUpgradeLog(row, logPath = getUpgradeLogPath()) {
+    try {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        const line = JSON.stringify(row) + '\n';
+        fs.appendFileSync(logPath, line, { mode: 0o644 });
+    }
+    catch (err) {
+        process.stderr.write(`[upgrade-log] failed to append: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+/**
+ * Read up to N most-recent rows from ~/.olam/upgrade.log.
+ *
+ * Returns an empty array on missing file (first-run UX).
+ *
+ * Per audit invariant: corrupt JSON lines (partial mid-write, manual
+ * tampering) are SKIPPED with a stderr warning rather than crashing
+ * `--history`.
+ */
+export function readUpgradeLog(limit = 10, logPath = getUpgradeLogPath()) {
+    if (!fs.existsSync(logPath))
+        return [];
+    let raw;
+    try {
+        raw = fs.readFileSync(logPath, 'utf-8');
+    }
+    catch (err) {
+        process.stderr.write(`[upgrade-log] failed to read: ${err instanceof Error ? err.message : String(err)}\n`);
+        return [];
+    }
+    const lines = raw.split('\n').filter((l) => l.length > 0);
+    const rows = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        try {
+            const parsed = JSON.parse(line);
+            // Defensive shape check — silently skip rows that don't look right.
+            if (typeof parsed.ts === 'string' &&
+                typeof parsed.started_at === 'number' &&
+                typeof parsed.status === 'string') {
+                rows.push(parsed);
+            }
+            else {
+                process.stderr.write(`[upgrade-log] skipped malformed row at line ${i + 1}\n`);
+            }
+        }
+        catch {
+            process.stderr.write(`[upgrade-log] skipped corrupt JSON at line ${i + 1}\n`);
+        }
+    }
+    // Most recent last (file is chronological); return last N.
+    return rows.slice(-Math.max(0, limit));
+}
+/** Format duration ms → "1.4s" / "12m04s" / "1h23m" for table display. */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const totalSec = Math.round(ms / 1000);
+    if (totalSec < 60)
+        return `${totalSec}s`;
+    const min = Math.floor(totalSec / 60);
+    const sec = totalSec % 60;
+    if (min < 60)
+        return `${min}m${String(sec).padStart(2, '0')}s`;
+    const hr = Math.floor(min / 60);
+    const remMin = min % 60;
+    return `${hr}h${String(remMin).padStart(2, '0')}m`;
+}
+/**
+ * Format an array of upgrade-log rows as a 5-column ASCII table:
+ *   timestamp | sha (8-char) | status | duration | failed_step
+ *
+ * Status column uses ✓/✗/↩ icons + plain text for grep-friendliness.
+ */
+export function formatHistoryTable(rows) {
+    if (rows.length === 0) {
+        return 'No upgrade history yet. Run `olam upgrade` to create your first record.';
+    }
+    const lines = [];
+    lines.push('TIMESTAMP                   SHA       STATUS         DURATION   FAILED-STEP');
+    lines.push('────────────────────────────────────────────────────────────────────────────────');
+    for (const r of rows) {
+        const ts = r.ts.slice(0, 19).replace('T', ' ');
+        const sha = r.sha_target.slice(0, 8);
+        const statusIcon = r.status === 'success' ? '✓ success' : r.status === 'rolled_back' ? '↩ rolled_back' : '✗ failed';
+        const dur = formatDuration(r.ended_at - r.started_at);
+        const failed = r.failed_step ?? '';
+        lines.push(`${ts.padEnd(28)}${sha.padEnd(10)}${statusIcon.padEnd(15)}${dur.padEnd(11)}${failed}`);
+    }
+    return lines.join('\n');
+}
+/** Format rows as one JSON object per line (JSONL passthrough — same as on-disk format). */
+export function formatHistoryJson(rows) {
+    return rows.map((r) => JSON.stringify(r)).join('\n');
+}
+//# sourceMappingURL=upgrade-log.js.map

package/dist/commands/upgrade-log.js.map

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

package/dist/commands/upgrade.d.ts

@@ -16,6 +16,17 @@ export interface UpgradeOpts {
     readonly skipImage: boolean;
     readonly skipInstall: boolean;
     readonly branch: string | null;
+    /** Phase 2b — B1: roll back to :olam-rollback set instead of upgrading. */
+    readonly rollback: boolean;
+    /** Phase 2b — B2: bypass HEAD-drift refusal at swap boundary. */
+    readonly force: boolean;
+    /** Phase 2b — B3: pass --no-cache through to all three build scripts. */
+    readonly noCache: boolean;
+    /** Phase 2c — C2: read upgrade history instead of running an upgrade. */
+    readonly history: boolean;
+    /** Phase 2c — C2: --history -n <N>; --history --json. */
+    readonly historyN: number;
+    readonly historyJson: boolean;
 }
 /**
  * Check whether node_modules is in sync with package-lock.json.
@@ -57,11 +68,265 @@ export declare function parseUpgradeOpts(raw: {
     skipImage?: boolean;
     skipInstall?: boolean;
     branch?: string;
+    rollback?: boolean;
+    force?: boolean;
+    noCache?: boolean;
+    history?: boolean;
+    n?: string | number;
+    json?: boolean;
 }): UpgradeOpts;
 /**
  * Extract the JS bundle hash from index.html.
  * Looks for the canonical Vite output pattern: `/assets/index-<hash>.js`.
  */
 export declare function extractBundleHash(indexHtml: string): string | null;
+/**
+ * Capture HEAD SHA via `git rev-parse HEAD`. Returns null on failure.
+ *
+ * Phase 2a — A2: must be invoked AFTER `git pull --ff-only` so the captured
+ * SHA reflects the state we're upgrading TO (not the pre-pull state). The
+ * pull's whole purpose is to advance HEAD; capturing before would refuse the
+ * CLI's own pull as drift at A6's swap-boundary check.
+ *
+ * The returned SHA is sticky for the rest of the run (no per-step re-reads);
+ * A6 / B4 re-read once at the swap boundary to detect operator-driven mid-flight
+ * `git checkout` / `git reset` that happen DURING the build window.
+ */
+export declare function captureHeadSha(cwd: string): string | null;
+/** Abbreviate a 40-char SHA to 8 chars for human-readable output. */
+export declare function abbreviateSha(sha: string): string;
+/**
+ * Check whether a docker image tag exists locally (Phase 2b — B1).
+ *
+ * Uses `docker image inspect` which exits 0 only when ALL specified
+ * images exist locally. Single-image variant for the rollback pre-flight.
+ */
+export declare function imageExists(tag: string): boolean;
+/**
+ * Pre-flight check for `olam upgrade --rollback` (Phase 2b — B1).
+ *
+ * Verifies that all three `:olam-rollback` tags exist. Returns an error
+ * message naming the missing image(s) when any are absent — typically
+ * the first-upgrade case where no prior canonical existed for one or
+ * more components, leaving the rollback set incoherent (see audit A6-001).
+ *
+ * Returns null when all three are present (rollback is safe to proceed).
+ */
+export declare function checkRollbackSetExists(plan: ReadonlyArray<SwapPlan>): string | null;
+/**
+ * Per-image smoke result (Phase 2a — A5).
+ *
+ * `docker create + docker inspect` validates the freshly-built `:olam-next`
+ * image is well-formed AND its baked OLAM_BUILD_SHA label matches the
+ * captured target SHA. Catches build-corrupt cases (compile errors hidden,
+ * missing files, etc.) before A6's atomic swap touches canonical tags.
+ *
+ * Does NOT bind ports (docker create only allocates the container's
+ * filesystem; doesn't start the entrypoint), so it's safe to run while
+ * the existing host-cp/auth containers are running on their canonical ports.
+ *
+ * Runtime startup bugs are caught later by /api/version/status post-recreate
+ * (A8), per the local-dev/dogfood priority axis (logic correctness > security
+ * hardening).
+ */
+export interface SmokeResult {
+    readonly image: string;
+    readonly ok: boolean;
+    readonly bakedSha: string | null;
+    readonly error?: string;
+}
+/**
+ * Run docker create + docker inspect for a single image.
+ *
+ * Returns ok=true when:
+ *   - `docker create <image>` exits 0 (image manifest valid, layers downloadable).
+ *   - `docker inspect <image> --format '{{.Config.Labels.olam_build_sha}}'`
+ *     returns the expected `targetSha`.
+ *
+ * The container created by `docker create` is removed via `docker rm` even on
+ * failure paths (best-effort cleanup; orphans are harmless and pruned by the
+ * daemon's GC eventually).
+ */
+export declare function smokeImage(image: string, targetSha: string): SmokeResult;
+/**
+ * Per-image swap mapping (Phase 2a — A6).
+ *
+ * Auth uses `:local` (NOT `:latest`) per AuthContainerController.DEFAULT_IMAGE.
+ * Host-cp + devbox use `:latest`. The transient `:olam-next` and rollback
+ * `:olam-rollback` namespaces are uniform across all three.
+ */
+export interface SwapPlan {
+    readonly transient: string;
+    readonly canonical: string;
+    readonly rollback: string;
+}
+export declare const PRODUCTION_SWAP_PLAN: ReadonlyArray<SwapPlan>;
+/** Result of a single `docker tag` op. */
+interface DockerTagResult {
+    readonly ok: boolean;
+    readonly error?: string;
+}
+/**
+ * Run `docker tag <source> <dest>`. Returns ok=false with stderr trimmed
+ * on failure (e.g. source image absent). No retry — caller decides.
+ *
+ * Per audit A6-003: spawnSync may throw synchronously under fork pressure
+ * (libuv clone(2) failures). The try/catch ensures performAtomicSwap can
+ * always proceed to its summary phase — a thrown exception escaping
+ * dockerTag would leak the upgrade lock and produce no SwapResult, which
+ * confuses both the operator AND Phase 2b's --rollback recovery path.
+ */
+export declare function dockerTag(source: string, dest: string): DockerTagResult;
+/**
+ * Per-image swap result. The two phases (rollback-save + canonical-advance)
+ * are tracked separately so SIGKILL-recovery paths can diagnose partial state.
+ */
+export interface SwapStepResult {
+    readonly image: string;
+    /** Did rollback-save (canonical → :olam-rollback) succeed? false on first-upgrade — non-fatal. */
+    readonly rollbackSaved: boolean;
+    /** Did canonical-advance (:olam-next → canonical) succeed? Fatal if false. */
+    readonly canonicalAdvanced: boolean;
+    readonly rollbackError?: string;
+    readonly canonicalError?: string;
+}
+export interface SwapResult {
+    readonly ok: boolean;
+    readonly steps: ReadonlyArray<SwapStepResult>;
+    readonly partialAdvance: boolean;
+    /**
+     * True when ALL three :olam-rollback tags were successfully written before
+     * any canonical-advance was attempted. False when at least one Phase-1
+     * rollback-save failed (typically first-upgrade where the canonical didn't
+     * exist; Phase 2b's --rollback pre-flight detects empty-or-partial
+     * rollback set and refuses).
+     *
+     * Per audit A6-001: the partial-Phase-1 + Phase-2-fail combination would
+     * otherwise emit a misleading "run --rollback" hint when the rollback set
+     * is INCOHERENT and `--rollback` would either partially restore or refuse.
+     * The summary string branches on this flag.
+     */
+    readonly rollbackCoherent: boolean;
+    readonly summary: string;
+}
+/**
+ * Atomic-ish 3-image set swap.
+ *
+ * Six sequential `docker tag` ops in two phases:
+ *
+ *   Phase 1 (rollback-save):
+ *     1. canonical → :olam-rollback (image 1)
+ *     2. canonical → :olam-rollback (image 2)
+ *     3. canonical → :olam-rollback (image 3)
+ *
+ *   Phase 2 (canonical-advance):
+ *     4. :olam-next → canonical (image 1)
+ *     5. :olam-next → canonical (image 2)
+ *     6. :olam-next → canonical (image 3)
+ *
+ * Invariants:
+ *
+ * - **First-upgrade tolerance**: any of steps 1-3 may fail with "no such
+ *   image" if the operator has never had a canonical-tagged image. Those
+ *   failures are NON-FATAL (recorded in rollbackError but not aborted) —
+ *   `:olam-rollback` simply doesn't exist for that image; Phase 2b's
+ *   `--rollback` pre-flight detects this and refuses.
+ *
+ * - **Canonical-advance fatality**: any failure in steps 4-6 is fatal.
+ *   The swap is partially advanced; canonical tags are now mixed (some
+ *   at SHA-Y, some at SHA-X). Operator runs `olam upgrade --rollback`
+ *   (Phase 2b) which uses the FULL `:olam-rollback` set written in Phase 1
+ *   to restore coherent prior state.
+ *
+ * - **SIGKILL recovery**: if killed during Phase 1, partial `:olam-rollback`
+ *   exists but canonical is intact — operator's next `olam upgrade` succeeds
+ *   normally (the partial `:olam-rollback` is overwritten by the next
+ *   successful run). If killed during Phase 2, canonical is mixed —
+ *   operator must `olam upgrade --rollback` to recover.
+ *
+ * The "atomic-ish" qualifier: `docker tag` is per-image atomic (POSIX rename
+ * of a symbolic name), but the SET of 3 canonical tags is updated sequentially
+ * across ~1s wall-clock. Sub-second window is acceptable for solo-dev/dogfood
+ * per the plan's local-dev/dogfood priority axis.
+ */
+export declare function performAtomicSwap(plan: ReadonlyArray<SwapPlan>): SwapResult;
+/**
+ * Inverse of performAtomicSwap — restore canonical from :olam-rollback
+ * (Phase 2b — B1). Three sequential `docker tag` ops:
+ *
+ *   docker tag olam-auth:olam-rollback     olam-auth:local
+ *   docker tag olam-devbox:olam-rollback   olam-devbox:latest
+ *   docker tag olam-host-cp:olam-rollback  olam-host-cp:latest
+ *
+ * No two-phase ceremony — the source `:olam-rollback` set is already a
+ * coherent prior-good captured by a previous successful `olam upgrade`,
+ * so we don't need to preserve current canonical (it's known-broken,
+ * which is why we're rolling back).
+ *
+ * Caller MUST pre-flight via `checkRollbackSetExists()` before invoking.
+ * Behavior on missing source is per-image fatal (returns ok=false +
+ * error naming the missing image).
+ */
+export declare function performRollbackSwap(plan: ReadonlyArray<SwapPlan>): {
+    ok: boolean;
+    results: ReadonlyArray<{
+        image: string;
+        ok: boolean;
+        error?: string;
+    }>;
+    summary: string;
+};
+/**
+ * Snapshot of /api/version/status response (Phase 1 contract).
+ *
+ * Mirrors the VersionSnapshot type from packages/host-cp/src/version-status.mjs.
+ * Kept inline (no shared module import) to avoid CLI ↔ host-cp import cycles.
+ */
+export interface VersionSnapshot {
+    readonly hostCp: {
+        readonly running: string;
+        readonly latest: string;
+        readonly upgradeAvailable: boolean;
+    };
+    readonly authService: {
+        readonly running: string;
+        readonly latest: string;
+        readonly upgradeAvailable: boolean;
+    };
+    readonly devbox: {
+        readonly running: string;
+        readonly latest: string;
+        readonly upgradeAvailable: boolean;
+    };
+    readonly operatorHead: string;
+    readonly checkedAt: string;
+}
+/**
+ * Poll /api/version/status until all three component `.running` SHAs match
+ * `targetSha`, or until `timeoutMs` elapses. Returns the final snapshot.
+ *
+ * Phase 2a — A8: this is the success criterion for the entire upgrade.
+ * After A6's atomic swap + A7's recreate, the new images should report
+ * the new SHA via OLAM_BUILD_SHA baked at build time. Round-trip through
+ * Phase 1's detection path closes the loop.
+ *
+ * Returns:
+ *   - { matched: true, snapshot } when all three SHAs equal targetSha within timeout.
+ *   - { matched: false, snapshot } when timeout expires; caller decides
+ *     whether to warn (recreate succeeded but propagation slow) or error.
+ *   - { matched: false, snapshot: null } when /api/version/status is
+ *     unreachable for the entire timeout (host-cp didn't come back up).
+ */
+export declare function waitForVersionMatch(targetSha: string, timeoutMs?: number, pollIntervalMs?: number): Promise<{
+    matched: boolean;
+    snapshot: VersionSnapshot | null;
+}>;
+/**
+ * Format a version-snapshot mismatch into a readable per-component diff
+ * (Phase 2a — A8). Used in the timeout-warn path so the operator sees
+ * which component is lagging.
+ */
+export declare function formatVersionMismatch(targetSha: string, snapshot: VersionSnapshot | null): string;
 export declare function registerUpgrade(program: Command): void;
+export {};
 //# sourceMappingURL=upgrade.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUzC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAaxD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,EAC9B,GAAG,EAAE,MAAM,GACV;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAQlD;AAED,+CAA+C;AAC/C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAWzF;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE;IACpC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,WAAW,CAOd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlE;AAmUD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAetD"}
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"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"}