@microwiseai/snapshot 0.5.2 → 0.7.0

package/dist/lib/install-verify.js.map

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

package/dist/lib/ledger.d.ts

@@ -0,0 +1,212 @@
+/**
+ * ============================================================
+ * Install Ledger (S3 — beta-pipeline-robustness-2026-08-30 §4)
+ * ============================================================
+ *
+ * Records, at the END of an install, the provenance of every npm package that
+ * was installed: the manifest pin we asked for (`expected`), the version that
+ * actually landed on disk (`resolved`), the tarball URL it came from, the
+ * installer/step that produced it, and the ordered list of install steps.
+ *
+ * Goal (AC3.1): after any install, "이 버전이 어디서 왔나" ("where did this
+ * version come from?") is answerable from the ledger ALONE — no reverse
+ * engineering of the global node_modules.
+ *
+ * SCHEMA OWNERSHIP (manager freeze 2026-08-30): this file is the SSOT for the
+ * ledger schema; ledger.json is owned by S3 (this worker). Field names follow
+ * the 기획서. S1 (verify) and FB (pin override) live in verify-owned libs and
+ * do NOT own this schema. Dependency direction is one-way (verify → ledger):
+ * ledger.ts imports NOTHING from install-verify.ts / pin-override.ts.
+ *
+ * Writing the ledger MUST NOT break an install — every entry point here is
+ * best-effort and swallows its own errors.
+ */
+/** Current ledger schema version. Bump on breaking field changes. */
+export declare const LEDGER_SCHEMA_VERSION: 1;
+/** One recorded install step, in execution order. */
+export interface LedgerStep {
+    /** 1-based execution order across the whole install. */
+    order: number;
+    /**
+     * Which phase of the install produced this step. Stable identifiers:
+     *   'pre-install-batch'     — the single up-front `npm install -g` batch
+     *   'pre-install-fallback'  — per-package retry after the pre-install batch failed
+     *   'layer-batch'           — a per-snapshot-layer npm batch (installSnapshot)
+     *   'layer-fallback'        — per-package retry after a layer batch failed
+     *   'layer-parallel'        — non-npm (glpkg/generic) parallel install
+     *   'skit'                  — skit-adapter install
+     */
+    phase: string;
+    /** Installer name: 'npm-proxy' | 'glpkg' | 'skit' | ... */
+    installer: string;
+    /** The exact command executed (or a synthetic label for non-shell installers). */
+    command: string;
+    /** name@version specs this step targeted. */
+    specs: string[];
+    /** Outcome of the step. */
+    result: 'ok' | 'fallback' | 'failed';
+}
+/** Provenance for a single npm package, resolved after install. */
+export interface LedgerPackage {
+    /** Package name, e.g. "@ist/sesh". */
+    name: string;
+    /** Manifest pin we requested (SSOT intent). null if not declared as npm here. */
+    expected: string | null;
+    /** Version actually on disk after install (from `npm ls -g`). null if absent. */
+    resolved: string | null;
+    /** Tarball URL the resolved version was fetched from (from `npm ls -g`). */
+    tarballUrl: string | null;
+    /** Human/structured summary answering "where did this version come from?". */
+    resolutionSource: string;
+    /** Installer that handled this package. */
+    installer: string;
+}
+/**
+ * S1 (verify) verdict, folded into the ledger so verification and provenance
+ * live in one artifact. WRITTEN BY THE VERIFY WIRING (install.ts integrator),
+ * shaped to verifyInstallMap()'s return contract. Optional: absent until the
+ * verify pass runs.
+ */
+export interface LedgerVerification {
+    ok: boolean;
+    verifiedCount: number;
+    total: number;
+    mismatches: Array<{
+        name: string;
+        expected: string | null;
+        got: string | null;
+    }>;
+}
+/**
+ * AC1.4 — core-floor verdict folded into the ledger. Records every below-floor
+ * copy of the singleton package (@ist/adapters-core) found in the nested tree.
+ * Written by the install.ts integrator (coreFloorAssert lives in core-floor.ts).
+ */
+export interface LedgerCoreFloor {
+    ok: boolean;
+    pkg: string;
+    minVersion: string;
+    offenders: Array<{
+        path: string;
+        version: string;
+    }>;
+}
+/** The install ledger written to ~/.config/ist-snapshot/ledger.json. */
+export interface InstallLedger {
+    schemaVersion: typeof LEDGER_SCHEMA_VERSION;
+    snapshot: {
+        name: string;
+        version: string;
+    };
+    /** ISO timestamp the ledger was recorded. */
+    recordedAt: string;
+    /** snapshot CLI version that produced this ledger. */
+    cliVersion: string;
+    /** Registry the packages were fetched through (registry-proxy URL). */
+    registry: string;
+    packages: LedgerPackage[];
+    installSteps: LedgerStep[];
+    /** FB pin overrides applied this install (name → version). Empty unless FB used. */
+    overrides: Record<string, string>;
+    /** S1 verification verdict, if the verify pass ran. */
+    verification?: LedgerVerification;
+    /** AC1.4 core-floor verdict (nested singleton floor), if the assert ran. */
+    coreFloor?: LedgerCoreFloor;
+    /**
+     * DEEP (NOT --depth=0) `npm ls -g <names> --json --all` output captured
+     * post-install, stored verbatim. Scoped to the install's npm packages +
+     * @ist/adapters-core so NESTED copies are visible — this both (a) recovers
+     * "who required version X?" and (b) feeds coreFloorAssert (AC1.4). null if the
+     * query failed.
+     */
+    dependencyTreeRaw: unknown | null;
+}
+/**
+ * Accumulates install steps in execution order. One instance per install;
+ * threaded through installSnapshot via InstallSnapshotOptions.recorder.
+ */
+export declare class StepRecorder {
+    private steps;
+    record(step: Omit<LedgerStep, 'order'>): void;
+    getSteps(): LedgerStep[];
+}
+/** Path to the ledger file (sits next to current.json). */
+export declare function getLedgerPath(): string;
+export interface ResolvedQuery {
+    /** name → { version, tarballUrl } as read from the global tree. */
+    map: Map<string, {
+        version: string | null;
+        tarballUrl: string | null;
+    }>;
+    /** The raw parsed `npm ls` JSON (for dependencyTreeRaw), or null on failure. */
+    raw: unknown | null;
+}
+/**
+ * Query the globally-installed version + tarball URL for the given package
+ * names via a single `npm ls -g ... --json` call, and return the raw tree too.
+ * Best-effort: on total failure returns an all-null map and raw=null.
+ *
+ * NOTE: this is provenance extraction (version + tarball + raw tree), NOT the
+ * verify worker's single-name readInstalledNpmVersion(). No duplication of
+ * that helper — S3 never imports install-verify.
+ */
+export declare function queryResolvedVersions(names: string[]): ResolvedQuery;
+/**
+ * Derive the canonical npm tarball URL for a resolved package.
+ *
+ * npm 7+ does NOT persist the fetched tarball URL for global installs
+ * (`npm ls -g --json` omits `resolved`, package.json is stripped of `_resolved`,
+ * and there is no global lockfile). So when the authoritative URL is missing we
+ * reconstruct the standard registry path — the same one npm would fetch from the
+ * scope's configured registry:  `<registry>/<name>/-/<unscoped>-<version>.tgz`.
+ *
+ * Returns null when the version is unknown (nothing to point at). Best-effort:
+ * the registry is the one configured for the scope during install (registry-proxy).
+ */
+export declare function deriveTarballUrl(registry: string, name: string, version: string | null): string | null;
+/**
+ * Capture a DEEP dependency tree (`npm ls -g <names> --json --all`) for the
+ * ledger's `dependencyTreeRaw` and for coreFloorAssert (AC1.4).
+ *
+ * ★ Deliberately NOT `--depth=0`: nested copies must be visible (an old
+ * @ist/adapters-core buried under another package is exactly what re-fragments
+ * the registry). To avoid the cost of dumping the ENTIRE global tree, we scope
+ * the query to the install's npm packages + the singleton package — with filter
+ * args, `npm ls` prunes to the paths that reach those names (full depth), which
+ * is bounded yet still surfaces every nested copy of the targets.
+ *
+ * Best-effort: returns null on failure (ledger writing never fails an install).
+ */
+export declare function queryDependencyTree(names: string[]): unknown | null;
+export interface BuildLedgerInput {
+    snapshotName: string;
+    snapshotVersion: string;
+    cliVersion: string;
+    registry: string;
+    /** Manifest pins for npm packages: name -> version. The "expected" set. */
+    expected: Record<string, string>;
+    /** Installer used for the npm packages (typically 'npm-proxy'). */
+    installer: string;
+    steps: LedgerStep[];
+    /** FB pin overrides (name -> version), if any. */
+    overrides?: Record<string, string>;
+    /**
+     * DEEP dependency tree for `dependencyTreeRaw` (from queryDependencyTree).
+     * When provided it takes precedence over the resolver's shallow tree — the
+     * integrator captures a nested-visible tree (AC1.4). null/undefined → fall
+     * back to the resolver's tree.
+     */
+    dependencyTreeRaw?: unknown | null;
+}
+/**
+ * Assemble the ledger: query disk for resolved versions/tarballs, then join
+ * against the expected pins and install steps to explain each package's origin.
+ * `now` is injected (callers stamp the timestamp) to keep this pure/testable.
+ * `resolver` is injectable for tests; defaults to the real `npm ls -g` query.
+ */
+export declare function buildLedger(input: BuildLedgerInput, now: string, resolver?: (names: string[]) => ResolvedQuery): InstallLedger;
+/** Write the ledger to disk. Best-effort — never throws into the caller. */
+export declare function writeLedger(ledger: InstallLedger): boolean;
+/** Read the ledger from disk, or null if absent/unreadable. */
+export declare function readLedger(): InstallLedger | null;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/lib/ledger.d.ts.map

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

package/dist/lib/ledger.js

@@ -0,0 +1,266 @@
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { getConfig } from './config.js';
+/**
+ * ============================================================
+ * Install Ledger (S3 — beta-pipeline-robustness-2026-08-30 §4)
+ * ============================================================
+ *
+ * Records, at the END of an install, the provenance of every npm package that
+ * was installed: the manifest pin we asked for (`expected`), the version that
+ * actually landed on disk (`resolved`), the tarball URL it came from, the
+ * installer/step that produced it, and the ordered list of install steps.
+ *
+ * Goal (AC3.1): after any install, "이 버전이 어디서 왔나" ("where did this
+ * version come from?") is answerable from the ledger ALONE — no reverse
+ * engineering of the global node_modules.
+ *
+ * SCHEMA OWNERSHIP (manager freeze 2026-08-30): this file is the SSOT for the
+ * ledger schema; ledger.json is owned by S3 (this worker). Field names follow
+ * the 기획서. S1 (verify) and FB (pin override) live in verify-owned libs and
+ * do NOT own this schema. Dependency direction is one-way (verify → ledger):
+ * ledger.ts imports NOTHING from install-verify.ts / pin-override.ts.
+ *
+ * Writing the ledger MUST NOT break an install — every entry point here is
+ * best-effort and swallows its own errors.
+ */
+/** Current ledger schema version. Bump on breaking field changes. */
+export const LEDGER_SCHEMA_VERSION = 1;
+/**
+ * Accumulates install steps in execution order. One instance per install;
+ * threaded through installSnapshot via InstallSnapshotOptions.recorder.
+ */
+export class StepRecorder {
+    steps = [];
+    record(step) {
+        this.steps.push({ order: this.steps.length + 1, ...step });
+    }
+    getSteps() {
+        return this.steps.slice();
+    }
+}
+/** Path to the ledger file (sits next to current.json). */
+export function getLedgerPath() {
+    const config = getConfig();
+    return join(config.configDir, 'ledger.json');
+}
+/**
+ * Query the globally-installed version + tarball URL for the given package
+ * names via a single `npm ls -g ... --json` call, and return the raw tree too.
+ * Best-effort: on total failure returns an all-null map and raw=null.
+ *
+ * NOTE: this is provenance extraction (version + tarball + raw tree), NOT the
+ * verify worker's single-name readInstalledNpmVersion(). No duplication of
+ * that helper — S3 never imports install-verify.
+ */
+export function queryResolvedVersions(names) {
+    const map = new Map();
+    if (names.length === 0)
+        return { map, raw: null };
+    const parse = (text) => {
+        const data = JSON.parse(text);
+        const deps = data.dependencies || {};
+        for (const name of names) {
+            const node = deps[name];
+            map.set(name, { version: node?.version ?? null, tarballUrl: node?.resolved ?? null });
+        }
+        lastRaw = data;
+        return true;
+    };
+    let lastRaw = null;
+    try {
+        // --json gives { dependencies: { "<name>": { version, resolved } } }.
+        // depth=0 keeps the tree shallow (top-level globals only).
+        const cmd = `npm ls -g ${names.map((n) => JSON.stringify(n)).join(' ')} --json --depth=0`;
+        const out = execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        parse(out);
+        return { map, raw: lastRaw };
+    }
+    catch (err) {
+        // `npm ls` exits non-zero on peer/extraneous warnings yet still prints valid
+        // JSON on stdout — recover it before giving up.
+        const stdout = err?.stdout;
+        if (stdout) {
+            try {
+                parse(stdout.toString());
+                return { map, raw: lastRaw };
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        for (const name of names)
+            map.set(name, { version: null, tarballUrl: null });
+        return { map, raw: null };
+    }
+}
+/**
+ * Derive the canonical npm tarball URL for a resolved package.
+ *
+ * npm 7+ does NOT persist the fetched tarball URL for global installs
+ * (`npm ls -g --json` omits `resolved`, package.json is stripped of `_resolved`,
+ * and there is no global lockfile). So when the authoritative URL is missing we
+ * reconstruct the standard registry path — the same one npm would fetch from the
+ * scope's configured registry:  `<registry>/<name>/-/<unscoped>-<version>.tgz`.
+ *
+ * Returns null when the version is unknown (nothing to point at). Best-effort:
+ * the registry is the one configured for the scope during install (registry-proxy).
+ */
+export function deriveTarballUrl(registry, name, version) {
+    if (!version)
+        return null;
+    if (!registry)
+        return null;
+    const base = registry.replace(/\/+$/, '');
+    // Scoped "@ist/sesh" → unscoped "sesh"; unscoped "foo" → "foo".
+    const unscoped = name.includes('/') ? name.slice(name.indexOf('/') + 1) : name;
+    return `${base}/${name}/-/${unscoped}-${version}.tgz`;
+}
+/**
+ * Capture a DEEP dependency tree (`npm ls -g <names> --json --all`) for the
+ * ledger's `dependencyTreeRaw` and for coreFloorAssert (AC1.4).
+ *
+ * ★ Deliberately NOT `--depth=0`: nested copies must be visible (an old
+ * @ist/adapters-core buried under another package is exactly what re-fragments
+ * the registry). To avoid the cost of dumping the ENTIRE global tree, we scope
+ * the query to the install's npm packages + the singleton package — with filter
+ * args, `npm ls` prunes to the paths that reach those names (full depth), which
+ * is bounded yet still surfaces every nested copy of the targets.
+ *
+ * Best-effort: returns null on failure (ledger writing never fails an install).
+ */
+export function queryDependencyTree(names) {
+    if (names.length === 0)
+        return null;
+    const args = names.map((n) => JSON.stringify(n)).join(' ');
+    const cmd = `npm ls -g ${args} --json --all`;
+    try {
+        const out = execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        return JSON.parse(out);
+    }
+    catch (err) {
+        // `npm ls` exits non-zero on peer/extraneous warnings yet still prints valid
+        // JSON on stdout — recover it before giving up.
+        const stdout = err?.stdout;
+        if (stdout) {
+            try {
+                return JSON.parse(stdout.toString());
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        return null;
+    }
+}
+/** Derive the registry host label from a tarball URL, for resolutionSource. */
+function registryHostOf(tarballUrl, fallback) {
+    if (!tarballUrl)
+        return fallback;
+    try {
+        return new URL(tarballUrl).host;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Find the step (if any) whose specs targeted this package name. */
+function findInstallingStep(name, steps) {
+    // Prefer the LAST step that targeted the package: fallbacks run after a failed
+    // batch, so the later step is the authoritative one.
+    let found;
+    for (const step of steps) {
+        if (step.specs.some((s) => s === name || s.startsWith(`${name}@`))) {
+            found = step;
+        }
+    }
+    return found;
+}
+/**
+ * Assemble the ledger: query disk for resolved versions/tarballs, then join
+ * against the expected pins and install steps to explain each package's origin.
+ * `now` is injected (callers stamp the timestamp) to keep this pure/testable.
+ * `resolver` is injectable for tests; defaults to the real `npm ls -g` query.
+ */
+export function buildLedger(input, now, resolver = queryResolvedVersions) {
+    const names = Object.keys(input.expected);
+    const { map: resolvedMap, raw } = resolver(names);
+    // Prefer the injected DEEP tree (nested-visible) for dependencyTreeRaw; the
+    // resolver's shallow (--depth=0) tree is only a fallback for provenance.
+    const dependencyTreeRaw = input.dependencyTreeRaw !== undefined ? input.dependencyTreeRaw : raw;
+    const packages = [...names].sort().map((name) => {
+        const expected = input.expected[name] ?? null;
+        const resolvedInfo = resolvedMap.get(name) ?? { version: null, tarballUrl: null };
+        const resolved = resolvedInfo.version;
+        // Prefer the authoritative tarball URL from `npm ls` if present; npm 7+ does
+        // not persist it for globals, so fall back to the canonical registry path
+        // derived from the configured registry + resolved version (provenance
+        // completeness). null only when the version itself is unknown.
+        const tarballUrl = resolvedInfo.tarballUrl ?? deriveTarballUrl(input.registry, name, resolved);
+        const step = findInstallingStep(name, input.steps);
+        const host = registryHostOf(tarballUrl, registryHostOf(input.registry, input.registry));
+        const parts = [];
+        parts.push(resolved
+            ? `resolved ${resolved} from ${host}`
+            : `not found on disk (expected ${expected ?? 'unknown'})`);
+        if (step) {
+            parts.push(`via ${step.installer} (${step.phase} step #${step.order}, ${step.result})`);
+        }
+        else {
+            parts.push(`via ${input.installer}`);
+        }
+        if (expected && resolved && expected !== resolved) {
+            parts.push(`⚠ manifest expected ${expected} — DIVERGED`);
+        }
+        else if (expected) {
+            parts.push(`manifest pin ${expected}`);
+        }
+        return {
+            name,
+            expected,
+            resolved,
+            tarballUrl,
+            resolutionSource: parts.join('; '),
+            installer: step?.installer ?? input.installer,
+        };
+    });
+    return {
+        schemaVersion: LEDGER_SCHEMA_VERSION,
+        snapshot: { name: input.snapshotName, version: input.snapshotVersion },
+        recordedAt: now,
+        cliVersion: input.cliVersion,
+        registry: input.registry,
+        packages,
+        installSteps: input.steps,
+        overrides: input.overrides ?? {},
+        dependencyTreeRaw,
+    };
+}
+/** Write the ledger to disk. Best-effort — never throws into the caller. */
+export function writeLedger(ledger) {
+    try {
+        const path = getLedgerPath();
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(path, JSON.stringify(ledger, null, 2));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read the ledger from disk, or null if absent/unreadable. */
+export function readLedger() {
+    try {
+        const path = getLedgerPath();
+        if (!existsSync(path))
+            return null;
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/dist/lib/ledger.js.map

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

package/dist/lib/pin-override.d.ts

@@ -0,0 +1,53 @@
+/**
+ * FB — Pin override fallback (hotfix path).
+ *
+ * `snapshot install @ist/beta --pin @ist/sesh@0.4.0` (repeatable) lets an owner
+ * override a single package's version WITHOUT re-publishing the whole manifest.
+ * This is the "1-package hotfix / pullback" lever from
+ * architecture/beta-pipeline-robustness-2026-08-30 §4 (FB).
+ *
+ * Overrides are exact-pin only (same reproducibility rule as publish) and are
+ * recorded in the install ledger so the override leaves a trace (AC FB.2).
+ */
+export interface PinOverride {
+    name: string;
+    version: string;
+}
+/** Thrown when a --pin spec is malformed (fail-loud; never silently ignored). */
+export declare class PinParseError extends Error {
+}
+/**
+ * Parse a single `--pin` spec of the form `<name>@<exact-version>`.
+ *
+ * Handles scoped names ("@ist/sesh@0.4.0") by splitting on the LAST '@'. The
+ * version must be an exact semver — ranges/tags/wildcards are rejected so an
+ * override cannot re-introduce the non-determinism it exists to fix.
+ */
+export declare function parsePin(spec: string): PinOverride;
+/**
+ * Parse a repeatable list of `--pin` specs into an override map (name → version).
+ * A later spec for the same name wins (last-write). Throws on the first invalid
+ * spec (fail-loud).
+ */
+export declare function parsePins(specs: string[] | undefined): Record<string, string>;
+/**
+ * Apply pin overrides to an install map, returning a NEW map (input untouched).
+ * Only overrides packages that are already present in the map — an override for
+ * a package the snapshot doesn't declare is surfaced by the caller (see
+ * `unmatchedOverrides`) rather than silently injected.
+ */
+export declare function applyPinOverrides(installMap: Record<string, string>, overrides: Record<string, string>): Record<string, string>;
+/**
+ * Return the override names that did NOT match any package in the install map.
+ * The caller warns on these (a --pin for a package not in the snapshot is almost
+ * always a typo).
+ */
+export declare function unmatchedOverrides(installMap: Record<string, string>, overrides: Record<string, string>): string[];
+/**
+ * The effective version for a package given a set of overrides — the override
+ * if one exists, otherwise the manifest version. Used to thread overrides
+ * through the recursive installer so a base-snapshot layer cannot clobber an
+ * override with its original pin.
+ */
+export declare function effectiveVersion(name: string, version: string, overrides: Record<string, string>): string;
+//# sourceMappingURL=pin-override.d.ts.map

package/dist/lib/pin-override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pin-override.d.ts","sourceRoot":"","sources":["../../src/lib/pin-override.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAE3C;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAqBlD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ7E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,EAAE,CAEV;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAER"}

package/dist/lib/pin-override.js

@@ -0,0 +1,77 @@
+import { isExactSemver } from './version-validator.js';
+/** Thrown when a --pin spec is malformed (fail-loud; never silently ignored). */
+export class PinParseError extends Error {
+}
+/**
+ * Parse a single `--pin` spec of the form `<name>@<exact-version>`.
+ *
+ * Handles scoped names ("@ist/sesh@0.4.0") by splitting on the LAST '@'. The
+ * version must be an exact semver — ranges/tags/wildcards are rejected so an
+ * override cannot re-introduce the non-determinism it exists to fix.
+ */
+export function parsePin(spec) {
+    const trimmed = spec.trim();
+    const atIdx = trimmed.lastIndexOf('@');
+    // atIdx <= 0 → no version separator, or only the leading scope '@'.
+    if (atIdx <= 0) {
+        throw new PinParseError(`Invalid --pin "${spec}": expected <name>@<version> (e.g. @ist/sesh@0.4.0)`);
+    }
+    const name = trimmed.substring(0, atIdx);
+    const version = trimmed.substring(atIdx + 1);
+    if (!name) {
+        throw new PinParseError(`Invalid --pin "${spec}": missing package name`);
+    }
+    if (!isExactSemver(version)) {
+        throw new PinParseError(`Invalid --pin "${spec}": "${version}" is not an exact semver ` +
+            `(ranges, tags, and wildcards are not allowed for overrides)`);
+    }
+    return { name, version };
+}
+/**
+ * Parse a repeatable list of `--pin` specs into an override map (name → version).
+ * A later spec for the same name wins (last-write). Throws on the first invalid
+ * spec (fail-loud).
+ */
+export function parsePins(specs) {
+    const overrides = {};
+    if (!specs)
+        return overrides;
+    for (const spec of specs) {
+        const { name, version } = parsePin(spec);
+        overrides[name] = version;
+    }
+    return overrides;
+}
+/**
+ * Apply pin overrides to an install map, returning a NEW map (input untouched).
+ * Only overrides packages that are already present in the map — an override for
+ * a package the snapshot doesn't declare is surfaced by the caller (see
+ * `unmatchedOverrides`) rather than silently injected.
+ */
+export function applyPinOverrides(installMap, overrides) {
+    const out = { ...installMap };
+    for (const [name, version] of Object.entries(overrides)) {
+        if (name in out) {
+            out[name] = version;
+        }
+    }
+    return out;
+}
+/**
+ * Return the override names that did NOT match any package in the install map.
+ * The caller warns on these (a --pin for a package not in the snapshot is almost
+ * always a typo).
+ */
+export function unmatchedOverrides(installMap, overrides) {
+    return Object.keys(overrides).filter((name) => !(name in installMap));
+}
+/**
+ * The effective version for a package given a set of overrides — the override
+ * if one exists, otherwise the manifest version. Used to thread overrides
+ * through the recursive installer so a base-snapshot layer cannot clobber an
+ * override with its original pin.
+ */
+export function effectiveVersion(name, version, overrides) {
+    return overrides[name] ?? version;
+}
+//# sourceMappingURL=pin-override.js.map

package/dist/lib/pin-override.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pin-override.js","sourceRoot":"","sources":["../../src/lib/pin-override.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAmBvD,iFAAiF;AACjF,MAAM,OAAO,aAAc,SAAQ,KAAK;CAAG;AAE3C;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,oEAAoE;IACpE,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,aAAa,CACrB,kBAAkB,IAAI,qDAAqD,CAC5E,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAC7C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,aAAa,CAAC,kBAAkB,IAAI,yBAAyB,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,aAAa,CACrB,kBAAkB,IAAI,OAAO,OAAO,2BAA2B;YAC7D,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAA2B;IACnD,MAAM,SAAS,GAA2B,EAAE,CAAC;IAC7C,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzC,SAAS,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IAC5B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAkC,EAClC,SAAiC;IAEjC,MAAM,GAAG,GAA2B,EAAE,GAAG,UAAU,EAAE,CAAC;IACtD,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACxD,IAAI,IAAI,IAAI,GAAG,EAAE,CAAC;YAChB,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAkC,EAClC,SAAiC;IAEjC,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,UAAU,CAAC,CAAC,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,OAAe,EACf,SAAiC;IAEjC,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC;AACpC,CAAC"}