@microwiseai/snapshot 0.5.2 → 0.7.0

package/dist/commands/current.d.ts

@@ -1,2 +1,6 @@
-export declare function currentCommand(): Promise<void>;
+export interface CurrentCommandOptions {
+    /** Emit machine-readable JSON (current snapshot + install ledger) instead of the pretty view. */
+    json?: boolean;
+}
+export declare function currentCommand(options?: CurrentCommandOptions): Promise<void>;
 //# sourceMappingURL=current.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"current.d.ts","sourceRoot":"","sources":["../../src/commands/current.ts"],"names":[],"mappings":"AAGA,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAiCpD"}
+{"version":3,"file":"current.d.ts","sourceRoot":"","sources":["../../src/commands/current.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,qBAAqB;IACpC,iGAAiG;IACjG,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAaD,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8CnF"}

package/dist/commands/current.js

@@ -1,12 +1,31 @@
 import chalk from 'chalk';
 import { getCurrentSnapshot } from '../lib/snapshot.js';
-export async function currentCommand() {
+import { readLedger } from '../lib/ledger.js';
+/**
+ * Whether the `--json` flag was passed. Read from the options object when the
+ * CLI wires it (index.ts), else self-parse process.argv so `snapshot current
+ * --json` works standalone (index.ts option definitions are the verify worker's
+ * lane; this keeps current.ts self-contained).
+ */
+function wantsJson(options) {
+    if (options?.json)
+        return true;
+    return process.argv.includes('--json');
+}
+export async function currentCommand(options) {
+    const current = getCurrentSnapshot();
+    const ledger = readLedger();
+    // ---- Machine-readable output (AC3.1: answer "where did this come from?"
+    // purely from the ledger, no reverse engineering) ----
+    if (wantsJson(options)) {
+        console.log(JSON.stringify({ current, ledger }, null, 2));
+        return;
+    }
     console.log(chalk.blue.bold(`
 ╔══════════════════════════════════════════════════════════════╗
 ║                  Current Snapshot                            ║
 ╚══════════════════════════════════════════════════════════════╝
 `));
-    const current = getCurrentSnapshot();
     if (!current) {
         console.log(chalk.yellow('No snapshot currently installed.'));
         console.log(chalk.gray('Use: snapshot install <name> to install a snapshot'));
@@ -28,5 +47,73 @@ export async function currentCommand() {
             console.log(chalk.green(`  ✓ ${skit}`));
         }
     }
+    // ---- Install ledger (S3): package provenance + step order ----
+    if (ledger) {
+        printLedger(ledger);
+    }
+}
+/** Pretty-print the ledger's provenance, install steps, overrides and verdict. */
+function printLedger(ledger) {
+    console.log('');
+    console.log(chalk.blue.bold('── Install ledger (provenance) ──'));
+    console.log(chalk.gray(`Recorded: ${new Date(ledger.recordedAt).toLocaleString()} · cli v${ledger.cliVersion} · registry ${ledger.registry}`));
+    if (ledger.packages.length > 0) {
+        console.log('');
+        console.log(chalk.gray('Package provenance (resolved ← expected):'));
+        for (const p of ledger.packages) {
+            const resolved = p.resolved ?? chalk.red('(not installed)');
+            const diverged = p.expected && p.resolved && p.expected !== p.resolved;
+            const head = diverged
+                ? chalk.yellow(`  ⚠ ${p.name}  ${p.resolved} ≠ pin ${p.expected}`)
+                : chalk.green(`  ✓ ${p.name}  ${resolved}`);
+            console.log(head);
+            console.log(chalk.gray(`      ${p.resolutionSource}`));
+            if (p.tarballUrl)
+                console.log(chalk.gray(`      tarball: ${p.tarballUrl}`));
+        }
+    }
+    if (ledger.installSteps.length > 0) {
+        console.log('');
+        console.log(chalk.gray('Install steps (in order):'));
+        for (const s of ledger.installSteps) {
+            const mark = s.result === 'ok' ? chalk.green('ok') : s.result === 'fallback' ? chalk.yellow('fallback') : chalk.red('failed');
+            console.log(chalk.gray(`  ${s.order}. [${s.phase}/${s.installer}] ${mark} — ${s.specs.length} spec(s)`));
+        }
+    }
+    if (ledger.overrides && Object.keys(ledger.overrides).length > 0) {
+        console.log('');
+        console.log(chalk.gray('Pin overrides (FB):'));
+        for (const [name, version] of Object.entries(ledger.overrides)) {
+            console.log(chalk.cyan(`  ⇄ ${name} → ${version}`));
+        }
+    }
+    if (ledger.verification) {
+        const v = ledger.verification;
+        console.log('');
+        if (v.ok) {
+            console.log(chalk.green(`✓ Verified ${v.verifiedCount}/${v.total} — disk matches manifest pins`));
+        }
+        else {
+            console.log(chalk.red(`✗ Verified ${v.verifiedCount}/${v.total} — disk diverged from manifest pins:`));
+            for (const m of v.mismatches) {
+                const got = m.got === null ? '(not installed)' : m.got;
+                console.log(chalk.red(`    ${m.name}: expected ${m.expected}, got ${got}`));
+            }
+        }
+    }
+    // AC1.4 — core-floor (nested singleton floor).
+    if (ledger.coreFloor) {
+        const cf = ledger.coreFloor;
+        console.log('');
+        if (cf.ok) {
+            console.log(chalk.green(`✓ Core-floor: every ${cf.pkg} copy is >= ${cf.minVersion} (S2 singleton intact)`));
+        }
+        else {
+            console.log(chalk.red(`✗ Core-floor: ${cf.offenders.length} ${cf.pkg} copy/copies below ${cf.minVersion}:`));
+            for (const o of cf.offenders) {
+                console.log(chalk.red(`    ${o.version} at ${o.path}`));
+            }
+        }
+    }
 }
 //# sourceMappingURL=current.js.map

package/dist/commands/current.js.map

@@ -1 +1 @@
-{"version":3,"file":"current.js","sourceRoot":"","sources":["../../src/commands/current.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;;;;CAI7B,CAAC,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;IAErC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,kCAAkC,CAAC,CAAC,CAAC;QAC9D,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC,CAAC;QAC9E,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACzE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC;IACxF,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhB,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC;QAC/C,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACnC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;QAC5C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YACjC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"current.js","sourceRoot":"","sources":["../../src/commands/current.ts"],"names":[],"mappings":"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"}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+export declare function doctorCommand(): Promise<void>;
+//# sourceMappingURL=doctor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAoDA,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAuCnD"}

package/dist/commands/doctor.js

@@ -0,0 +1,83 @@
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { checkPrerequisites, MINIMAL_PREREQUISITES } from '../lib/prerequisites.js';
+import { getConfig } from '../lib/config.js';
+import { verifyInstallMap, expectedMapFromLedger, } from '../lib/install-verify.js';
+/**
+ * S1 — offline install verification for `snapshot doctor`.
+ *
+ * Reads the manifest `expected` pins recorded in the install ledger
+ * (~/.config/ist-snapshot/ledger.json — schema owned by lib/ledger.ts) and
+ * re-checks them against the current global npm disk. This catches drift that
+ * happened AFTER install (e.g. a later `npm i -g` regressed a pin), turning
+ * silent "green on broken" into a visible ❌. Purely offline (no re-fetch).
+ *
+ * Degrades gracefully: if the ledger is absent/unparseable/empty (older install
+ * or none), it prints nothing and doctor behaves as before.
+ */
+function verifyInstallFromLedger() {
+    const ledgerPath = join(getConfig().configDir, 'ledger.json');
+    if (!existsSync(ledgerPath))
+        return;
+    let parsed = null;
+    try {
+        parsed = JSON.parse(readFileSync(ledgerPath, 'utf-8'));
+    }
+    catch {
+        return; // corrupt ledger — don't crash doctor
+    }
+    const expected = expectedMapFromLedger(parsed);
+    if (Object.keys(expected).length === 0)
+        return;
+    console.log('');
+    console.log(chalk.blue('Verifying install against manifest pins (from ledger)...\n'));
+    const v = verifyInstallMap(expected);
+    if (v.ok) {
+        console.log(chalk.green(`  ✅ verified ${v.verifiedCount}/${v.total} — disk matches manifest pins`));
+        return;
+    }
+    console.log(chalk.red(`  ❌ verified ${v.verifiedCount}/${v.total} — disk diverged from manifest pins:`));
+    for (const m of v.mismatches) {
+        const got = m.got === null ? '(not installed)' : m.got;
+        console.log(chalk.red(`     ${m.name}: expected ${m.expected}, got ${got}`));
+    }
+    console.log(chalk.gray('     Fix: snapshot install <name> --converge'));
+}
+export async function doctorCommand() {
+    console.log(chalk.blue('Checking prerequisites...\n'));
+    const results = checkPrerequisites(MINIMAL_PREREQUISITES);
+    const missing = results.filter(r => !r.installed);
+    // Print results
+    for (const r of results) {
+        const icon = r.installed ? chalk.green('✅') : chalk.red('❌');
+        console.log(`  ${icon} ${r.name}`);
+        if (!r.installed) {
+            console.log(chalk.gray(`     Required by: ${r.requiredBy.join(', ')}`));
+            if (r.installCommand) {
+                console.log(chalk.gray(`     Fix: ${r.installCommand}`));
+            }
+            if (r.guide) {
+                console.log(chalk.gray(`     ${r.guide}`));
+            }
+        }
+    }
+    console.log('');
+    if (missing.length === 0) {
+        console.log(chalk.green('All prerequisites satisfied! ✓'));
+    }
+    else {
+        console.log(chalk.yellow(`${missing.length} issue(s) found.`));
+        const fixable = missing.filter(r => r.installCommand);
+        if (fixable.length > 0) {
+            console.log(chalk.gray(`Run 'snapshot setup' to install ${fixable.length} missing prerequisite(s).`));
+        }
+        const manual = missing.filter(r => !r.installCommand);
+        if (manual.length > 0) {
+            console.log(chalk.gray(`${manual.length} require manual action (see above).`));
+        }
+    }
+    // S1 — surface install verification (disk vs manifest pins) from the ledger.
+    verifyInstallFromLedger();
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/doctor.js.map

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

package/dist/commands/install.d.ts

@@ -1,4 +1,5 @@
 import type { Snapshot, InstallerConfig } from '../lib/types.js';
+import { StepRecorder } from '../lib/ledger.js';
 export interface InstallResult {
     installed: string[];
     failed: string[];
@@ -7,11 +8,37 @@ export interface InstallSnapshotOptions {
     useProxy?: boolean;
     autoDetect?: boolean;
     sessionId?: string;
+    /**
+     * S3 — install-step recorder. When present, each npm batch / fallback /
+     * parallel / skit step appends an ordered entry for the install ledger. The
+     * same instance is threaded through the entire recursive extends chain.
+     */
+    recorder?: StepRecorder;
+    /**
+     * FB — pin overrides (name → exact version), applied to every install map in
+     * this snapshot AND its extends chain (threaded through the recursion) so a
+     * base layer cannot clobber an override with its original pin.
+     */
+    overrides?: Record<string, string>;
 }
+/**
+ * FB — the subset of pin overrides that actually apply to this install (i.e. the
+ * overridden package IS declared in the effective npm map). These are the
+ * packages we targeted-converge so a --pin always holds even without a global
+ * --converge. Overrides for packages not in the snapshot are dropped (already
+ * warned via unmatchedOverrides). Returns name → override version.
+ */
+export declare function overrideConvergeTargets(effectiveNpmMap: Record<string, string>, overrides: Record<string, string>): Record<string, string>;
 export declare function installSnapshot(snapshot: Snapshot, depth?: number, parentInstallers?: Record<string, InstallerConfig>, options?: InstallSnapshotOptions): Promise<{
     result: InstallResult;
     installers: Record<string, InstallerConfig>;
 }>;
+/**
+ * Recursively collect all packages from snapshot and its extends chain.
+ * This ensures .npmrc is configured with ALL scopes before installation begins,
+ * including scopes from base snapshots (e.g., @microwiseai from @ist/minimal).
+ */
+export declare function collectAllPackages(snapshot: Snapshot): Promise<Record<string, string>>;
 export interface InstallCommandOptions {
     /** Converge onto the new version: remove previous-version-only packages (ADR 001). */
     replace?: boolean;
@@ -19,6 +46,20 @@ export interface InstallCommandOptions {
     dryRun?: boolean;
     /** Skip the removal confirmation prompt. */
     yes?: boolean;
+    /**
+     * S1 — post-install convergence. ON BY DEFAULT (undefined ⇒ true). When true,
+     * a disk divergence from the manifest pins is auto-repaired (bounded rounds);
+     * an UNREPAIRABLE residual still fails-loud (exit 1) — no green-on-broken. Set
+     * false (CLI `--no-converge`) for a raw/fast install that only verifies and
+     * fails-loud on divergence without attempting repair. (Core-floor offenders
+     * always fail-loud regardless of mode.)
+     */
+    converge?: boolean;
+    /**
+     * FB — pin overrides without re-publishing, e.g. ["@ist/sesh@0.4.0"]
+     * (repeatable). Applied to the whole install + recorded in the ledger.
+     */
+    pin?: string[];
 }
 export declare function installCommand(name: string, options?: InstallCommandOptions): Promise<void>;
 //# sourceMappingURL=install.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/commands/install.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAwBjE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAsmBD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,KAAK,GAAE,MAAU,EACjB,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAM,EACtD,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,CAAC,CA8VjF;AA4FD,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAoLD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CA0brG"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/commands/install.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAgBjE,OAAO,EACL,YAAY,EAIb,MAAM,kBAAkB,CAAC;AAsB1B,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAqgBD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAuBD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,KAAK,GAAE,MAAU,EACjB,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAM,EACtD,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;CAAE,CAAC,CA0YjF;AAwDD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA6B5F;AAED,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAoLD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAwoBrG"}