@microwiseai/snapshot 0.5.0 → 0.5.2

package/dist/lib/distkit-routing-port.js

@@ -0,0 +1,72 @@
+/**
+ * ============================================================================
+ *  Phase-2b §1.2/§1.3 (decision A) — production scope-routing PackumentPort
+ * ============================================================================
+ *
+ * Decision A (owner-confirmed): distkit resolves the npm closure CLIENT-SIDE with
+ * PER-SCOPE registry routing. A real closure mixes lanes — PRIVATE roots/deps
+ * (`@ist/*`, `@microwiseai/*` … the snapshot's registry scopes) served by our
+ * proxy (+ session token), and PUBLIC transitive deps (`semver`, `commander`, …)
+ * served by npmjs (token-less). distkit's npm adapter takes ONE PackumentPort, so
+ * this port DISPATCHES per package name to the right registry.
+ *
+ * ★ TOKEN ISOLATION (C1 — the whole point): the two lanes are SEPARATE
+ *   {@link createFetchPackumentPort} instances. The public port is constructed
+ *   WITHOUT a token, so `createFetchPackumentPort` never attaches an
+ *   `Authorization` header to an npmjs read — it is structurally impossible for
+ *   the license/session token to leak to npmjs. Only the private port carries the
+ *   Bearer token.
+ * ★ FAIL-LOUD (§1.4): each sub-port surfaces a non-2xx as `PackumentResolutionError`
+ *   (an unentitled private read → 401 → throw). This port adds NO catch — a miss
+ *   propagates; it NEVER silently degrades to a public read for a private name.
+ */
+import { NPMJS_PUBLIC_REGISTRY_URL } from '@microwiseai/distkit';
+import { createFetchPackumentPort } from '@microwiseai/distkit/adapters';
+/**
+ * True iff `name` belongs to one of the PRIVATE scopes (the snapshot's registry
+ * scope-map keys, e.g. `@ist`, `@microwiseai`). A private name routes to the
+ * proxy (+ token); everything else is PUBLIC (npmjs, token-less).
+ *
+ * ★ Task-5 / ADR 0003 (ecosystem-neutral identity): `scope` here is an
+ * npm-adapter-LOCAL projection — the private/public LANE selector for the npm
+ * closure — NOT a core identity axis. It carries no npm privilege: any name not
+ * in `privateScopes` (an unscoped-npm public dep AND a pypi-style name alike) is
+ * uniformly PUBLIC. The core (group, name) identity is delegated downstream to
+ * distkit's `resolveManifestToLock` / `resolvePackageOriginByIdentity`, and the
+ * emitted lock keys on (name, group) — never on scope.
+ */
+export function isPrivateScope(name, privateScopes) {
+    return privateScopes.some((s) => {
+        const scope = s.endsWith('/') ? s.slice(0, -1) : s;
+        return name === scope || name.startsWith(`${scope}/`);
+    });
+}
+/**
+ * Build a {@link PackumentPort} that routes each `fetchPackument(name)` to the
+ * proxy (private, tokened) or npmjs (public, token-less) by scope. Plug into
+ * `createNpmAdapter(port)`.
+ */
+export function createScopeRoutingPackumentPort(opts) {
+    // PRIVATE lane — proxy + Bearer token (guardrail 1).
+    const privatePort = createFetchPackumentPort({
+        registryUrl: opts.proxyUrl,
+        token: opts.token,
+        fetchImpl: opts.fetchImpl,
+        timeoutMs: opts.timeoutMs,
+    });
+    // PUBLIC lane — npmjs, NO token passed (guardrail 2 / C1). Token isolation by
+    // construction: this port has no credential to send.
+    const publicPort = createFetchPackumentPort({
+        registryUrl: opts.npmjsUrl ?? NPMJS_PUBLIC_REGISTRY_URL,
+        fetchImpl: opts.fetchImpl,
+        timeoutMs: opts.timeoutMs,
+    });
+    return {
+        fetchPackument(name) {
+            return isPrivateScope(name, opts.privateScopes)
+                ? privatePort.fetchPackument(name)
+                : publicPort.fetchPackument(name);
+        },
+    };
+}
+//# sourceMappingURL=distkit-routing-port.js.map

package/dist/lib/distkit-routing-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"distkit-routing-port.js","sourceRoot":"","sources":["../../src/lib/distkit-routing-port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAsB,MAAM,+BAA+B,CAAC;AAE7F;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,aAAgC;IAC3E,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;QAC9B,MAAM,KAAK,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnD,OAAO,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;AACL,CAAC;AAkBD;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAAC,IAA6B;IAC3E,qDAAqD;IACrD,MAAM,WAAW,GAAG,wBAAwB,CAAC;QAC3C,WAAW,EAAE,IAAI,CAAC,QAAQ;QAC1B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;IACH,8EAA8E;IAC9E,qDAAqD;IACrD,MAAM,UAAU,GAAG,wBAAwB,CAAC;QAC1C,WAAW,EAAE,IAAI,CAAC,QAAQ,IAAI,yBAAyB;QACvD,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;IAEH,OAAO;QACL,cAAc,CAAC,IAAY;YACzB,OAAO,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC;gBAC7C,CAAC,CAAC,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC;gBAClC,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/lib/install-timeline.d.ts

@@ -0,0 +1,81 @@
+/**
+ * install-timeline.ts — Install timeline instrumentation (investigation only).
+ *
+ * Purpose: measure WHY a snapshot install is slow, from the inside, without
+ * changing any install behavior. Purely additive: when the opt-in env flag is
+ * unset the whole thing is a no-op with negligible overhead — every `start()`
+ * returns one shared no-op handle and `finalize()` returns immediately.
+ *
+ * Opt-in: SNAPSHOT_INSTALL_TIMELINE ∈ {'1','true'} (case-insensitive).
+ *
+ * Output when enabled:
+ *   (a) console phase-summary table with relative [+Xs] offsets, per-phase
+ *       durations, a `◄ dominant` marker on the largest phase, and per-command /
+ *       per-package rows indented under their phase, then a total line.
+ *   (b) JSONL file at ~/.ist/logs/snapshot-install-timeline/<ISO>.jsonl —
+ *       one line per event + a trailing summary line, for cross-run diffing.
+ *
+ * Security (security-ssot-principle): tokens must NEVER be written. Command
+ * strings and meta are sanitized — IST_SESSION_TOKEN, authToken, _authToken=,
+ * and Bearer values are replaced with `***` before any record/print/write.
+ */
+export type TimelineCategory = 'phase' | 'command' | 'package';
+export interface TimelineEvent {
+    label: string;
+    category: TimelineCategory;
+    /** Offset from timeline t0, in ms (span start). */
+    startOffsetMs: number;
+    /** Measured span duration, in ms (performance.now based). */
+    durationMs: number;
+    /** Wall-clock ISO timestamp of the span start (Date.now based). */
+    wallStartIso: string;
+    /** Label of the enclosing phase span, if any (for indentation/grouping). */
+    parentLabel?: string;
+    meta?: Record<string, unknown>;
+}
+export interface SpanHandle {
+    /** Close the span, recording its duration. Extra meta is merged in. */
+    end(meta?: Record<string, unknown>): void;
+}
+export interface StartOptions {
+    category?: TimelineCategory;
+    meta?: Record<string, unknown>;
+}
+export interface InstallTimelineOptions {
+    /** Force enable/disable. When omitted, decided from env opt-in flag. */
+    enabled?: boolean;
+    /** Env source (default: process.env). */
+    env?: Record<string, string | undefined>;
+    /** Monotonic clock in ms (default: performance.now). Injectable for tests. */
+    now?: () => number;
+    /** Wall clock in ms (default: Date.now). Injectable for tests. */
+    wallNow?: () => number;
+    /** Directory for JSONL logs (default: ~/.ist/logs/snapshot-install-timeline). */
+    logDir?: string;
+    /** Console sink (default: console.log). Injectable for tests. */
+    logger?: (line: string) => void;
+    /** Directory creator (default: mkdirSync -p). Injectable for tests. */
+    mkdir?: (dir: string) => void;
+    /** File writer (default: writeFileSync). Injectable for tests. */
+    writeFile?: (path: string, content: string) => void;
+}
+/** Redact token material from an arbitrary string. */
+export declare function sanitizeString(input: string, env?: Record<string, string | undefined>): string;
+/** Deep-sanitize a meta object: scrub string values and redact suspicious keys. */
+export declare function sanitizeMeta(meta: Record<string, unknown> | undefined, env?: Record<string, string | undefined>): Record<string, unknown> | undefined;
+export interface InstallTimeline {
+    readonly enabled: boolean;
+    start(label: string, opts?: StartOptions): SpanHandle;
+    finalize(): void;
+    /** Read recorded events (for tests / introspection). */
+    getEvents(): TimelineEvent[];
+}
+/**
+ * Decide enablement from the opt-in env flag (unless explicitly overridden).
+ */
+export declare function isTimelineEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * Factory: returns an active timeline when opted-in, else a zero-overhead no-op.
+ */
+export declare function createInstallTimeline(opts?: InstallTimelineOptions): InstallTimeline;
+//# sourceMappingURL=install-timeline.d.ts.map

package/dist/lib/install-timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-timeline.d.ts","sourceRoot":"","sources":["../../src/lib/install-timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;IACvB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,uEAAuE;IACvE,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,kEAAkE;IAClE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAiBD,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAkB9F;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAGrC;AAuBD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACtD,QAAQ,IAAI,IAAI,CAAC;IACjB,wDAAwD;IACxD,SAAS,IAAI,aAAa,EAAE,CAAC;CAC9B;AAyLD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAGhG;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,sBAA2B,GAAG,eAAe,CAGxF"}

package/dist/lib/install-timeline.js

@@ -0,0 +1,243 @@
+/**
+ * install-timeline.ts — Install timeline instrumentation (investigation only).
+ *
+ * Purpose: measure WHY a snapshot install is slow, from the inside, without
+ * changing any install behavior. Purely additive: when the opt-in env flag is
+ * unset the whole thing is a no-op with negligible overhead — every `start()`
+ * returns one shared no-op handle and `finalize()` returns immediately.
+ *
+ * Opt-in: SNAPSHOT_INSTALL_TIMELINE ∈ {'1','true'} (case-insensitive).
+ *
+ * Output when enabled:
+ *   (a) console phase-summary table with relative [+Xs] offsets, per-phase
+ *       durations, a `◄ dominant` marker on the largest phase, and per-command /
+ *       per-package rows indented under their phase, then a total line.
+ *   (b) JSONL file at ~/.ist/logs/snapshot-install-timeline/<ISO>.jsonl —
+ *       one line per event + a trailing summary line, for cross-run diffing.
+ *
+ * Security (security-ssot-principle): tokens must NEVER be written. Command
+ * strings and meta are sanitized — IST_SESSION_TOKEN, authToken, _authToken=,
+ * and Bearer values are replaced with `***` before any record/print/write.
+ */
+import { performance } from 'node:perf_hooks';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+const ENABLE_VALUES = new Set(['1', 'true']);
+/** Shared no-op handle — one allocation, reused for every disabled span. */
+const NOOP_SPAN = { end() { } };
+// ----------------------------------------------------------------------------
+// Sanitization (security-ssot-principle): never emit a real token.
+// ----------------------------------------------------------------------------
+// Keys whose VALUE is credential material and must be redacted wholesale.
+// Deliberately NOT a bare "auth" match: `authType` ('proxy-token'|'anonymous')
+// is a useful, non-secret diagnostic and must survive. `authToken` still matches
+// via "token".
+const SUSPICIOUS_KEY = /(token|secret|password|bearer|credential|apikey)/i;
+/** Redact token material from an arbitrary string. */
+export function sanitizeString(input, env) {
+    let out = input;
+    // key=value / key: value forms for known token-bearing keys.
+    out = out.replace(/(_authToken\s*=\s*)[^\s&'"]+/gi, '$1***');
+    out = out.replace(/(authToken["'\s]*[:=]\s*["']?)[^\s,'"&}]+/gi, '$1***');
+    out = out.replace(/(IST_SESSION_TOKEN["'\s]*[:=]\s*["']?)[^\s,'"&}]+/gi, '$1***');
+    // Bearer <token>
+    out = out.replace(/(Bearer\s+)[A-Za-z0-9._\-+/=]+/gi, '$1***');
+    // Belt-and-suspenders: scrub any literal occurrence of the actual token value
+    // that may have leaked into a command string via env interpolation.
+    const literal = (env ?? {})['IST_SESSION_TOKEN'];
+    if (literal && literal.length >= 8) {
+        out = out.split(literal).join('***');
+    }
+    return out;
+}
+/** Deep-sanitize a meta object: scrub string values and redact suspicious keys. */
+export function sanitizeMeta(meta, env) {
+    if (!meta)
+        return undefined;
+    return sanitizeValue(meta, env);
+}
+function sanitizeValue(value, env) {
+    if (typeof value === 'string')
+        return sanitizeString(value, env);
+    if (Array.isArray(value))
+        return value.map((v) => sanitizeValue(v, env));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (SUSPICIOUS_KEY.test(k) && typeof v === 'string') {
+                out[k] = '***';
+            }
+            else {
+                out[k] = sanitizeValue(v, env);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+class NoopTimeline {
+    enabled = false;
+    start() {
+        return NOOP_SPAN;
+    }
+    finalize() { }
+    getEvents() {
+        return [];
+    }
+}
+class ActiveTimeline {
+    enabled = true;
+    now;
+    wallNow;
+    env;
+    logDir;
+    logger;
+    mkdir;
+    writeFile;
+    t0;
+    wallT0;
+    events = [];
+    /** Stack of currently-open phase labels (for parent association). */
+    phaseStack = [];
+    finalized = false;
+    constructor(opts) {
+        this.now = opts.now ?? (() => performance.now());
+        this.wallNow = opts.wallNow ?? (() => Date.now());
+        this.env = opts.env ?? process.env;
+        this.logDir =
+            opts.logDir ?? join(homedir(), '.ist', 'logs', 'snapshot-install-timeline');
+        this.logger = opts.logger ?? ((line) => console.log(line));
+        this.mkdir = opts.mkdir ?? ((dir) => mkdirSync(dir, { recursive: true }));
+        this.writeFile =
+            opts.writeFile ?? ((path, content) => writeFileSync(path, content));
+        this.t0 = this.now();
+        this.wallT0 = this.wallNow();
+    }
+    start(label, opts = {}) {
+        const category = opts.category ?? 'phase';
+        const startMono = this.now();
+        const startOffsetMs = startMono - this.t0;
+        const wallStartIso = new Date(this.wallT0 + startOffsetMs).toISOString();
+        // Parent = innermost currently-open phase (commands/packages nest under it).
+        const parentLabel = category === 'phase' ? undefined : this.phaseStack[this.phaseStack.length - 1];
+        // Sanitize the label too — callers pass raw command strings as labels
+        // (e.g. runCommand), which may embed token material.
+        const safeLabel = sanitizeString(label, this.env);
+        const event = {
+            label: safeLabel,
+            category,
+            startOffsetMs,
+            durationMs: 0,
+            wallStartIso,
+            parentLabel,
+            meta: sanitizeMeta(opts.meta, this.env),
+        };
+        this.events.push(event);
+        if (category === 'phase') {
+            this.phaseStack.push(label);
+        }
+        let ended = false;
+        return {
+            end: (endMeta) => {
+                if (ended)
+                    return;
+                ended = true;
+                event.durationMs = this.now() - startMono;
+                if (endMeta) {
+                    const clean = sanitizeMeta(endMeta, this.env);
+                    event.meta = { ...(event.meta ?? {}), ...(clean ?? {}) };
+                }
+                if (category === 'phase') {
+                    // Pop this phase if it is on top; tolerate out-of-order ends.
+                    const idx = this.phaseStack.lastIndexOf(label);
+                    if (idx !== -1)
+                        this.phaseStack.splice(idx, 1);
+                }
+            },
+        };
+    }
+    getEvents() {
+        return this.events;
+    }
+    finalize() {
+        if (this.finalized)
+            return;
+        this.finalized = true;
+        const phases = this.events.filter((e) => e.category === 'phase');
+        const totalMs = phases.reduce((sum, p) => sum + p.durationMs, 0);
+        const dominant = phases.reduce((max, p) => (max === null || p.durationMs > max.durationMs ? p : max), null);
+        this.printConsole(phases, dominant, totalMs);
+        this.writeJsonl(dominant, totalMs);
+    }
+    printConsole(phases, dominant, totalMs) {
+        const log = this.logger;
+        log('');
+        log('━━━ Install Timeline (SNAPSHOT_INSTALL_TIMELINE) ━━━');
+        // Top-level = phases in start order, plus any orphan (parentless) non-phase.
+        const orphans = this.events.filter((e) => e.category !== 'phase' && !e.parentLabel);
+        const roots = [...phases, ...orphans].sort((a, b) => a.startOffsetMs - b.startOffsetMs);
+        const labelWidth = Math.max(20, ...this.events.map((e) => e.label.length + (e.category === 'phase' ? 0 : 2)));
+        for (const root of roots) {
+            const offset = `[+${(root.startOffsetMs / 1000).toFixed(1)}s]`;
+            const dur = `${Math.round(root.durationMs)}ms`;
+            const marker = dominant && root === dominant ? '  ◄ dominant' : '';
+            log(`${offset} ${root.label.padEnd(labelWidth)} ${dur.padStart(8)}${marker}`);
+            if (root.category === 'phase') {
+                const children = this.events
+                    .filter((e) => e.parentLabel === root.label)
+                    .sort((a, b) => a.startOffsetMs - b.startOffsetMs);
+                for (const child of children) {
+                    const cdur = `${Math.round(child.durationMs)}ms`;
+                    const tag = `${child.category}: ${child.label}`;
+                    log(`         ${tag.padEnd(labelWidth)} ${cdur.padStart(8)}`);
+                }
+            }
+        }
+        log(`         ${'total'.padEnd(labelWidth)} ${`${(totalMs / 1000).toFixed(1)}s`.padStart(8)}`);
+        log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    }
+    writeJsonl(dominant, totalMs) {
+        const wallStartIso = new Date(this.wallT0).toISOString();
+        const fileName = `${wallStartIso.replace(/[:.]/g, '-')}.jsonl`;
+        const filePath = join(this.logDir, fileName);
+        const lines = [];
+        for (const e of this.events) {
+            lines.push(JSON.stringify({ kind: 'event', ...e }));
+        }
+        lines.push(JSON.stringify({
+            kind: 'summary',
+            wallStartIso,
+            totalMs: Math.round(totalMs),
+            eventCount: this.events.length,
+            phaseCount: this.events.filter((e) => e.category === 'phase').length,
+            dominantPhase: dominant?.label,
+            dominantMs: dominant ? Math.round(dominant.durationMs) : undefined,
+        }));
+        try {
+            this.mkdir(this.logDir);
+            this.writeFile(filePath, lines.join('\n') + '\n');
+            this.logger(`Timeline written: ${filePath}`);
+        }
+        catch (err) {
+            // Investigation-only: never let logging failure affect the install.
+            const msg = err instanceof Error ? err.message : String(err);
+            this.logger(`Timeline: failed to write JSONL (${msg})`);
+        }
+    }
+}
+/**
+ * Decide enablement from the opt-in env flag (unless explicitly overridden).
+ */
+export function isTimelineEnabled(env = process.env) {
+    const raw = env['SNAPSHOT_INSTALL_TIMELINE'];
+    return raw !== undefined && ENABLE_VALUES.has(raw.trim().toLowerCase());
+}
+/**
+ * Factory: returns an active timeline when opted-in, else a zero-overhead no-op.
+ */
+export function createInstallTimeline(opts = {}) {
+    const enabled = opts.enabled ?? isTimelineEnabled(opts.env ?? process.env);
+    return enabled ? new ActiveTimeline(opts) : new NoopTimeline();
+}
+//# sourceMappingURL=install-timeline.js.map

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

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

package/dist/lib/preflight-adapter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Snapshot ↔ install-preflight adapter (thin).
+ *
+ * Maps a snapshot.json into the registry-agnostic preflight engine's inputs and
+ * runs the gate. The engine (@microwiseai/install-preflight) knows nothing about
+ * snapshots; all snapshot-specific knowledge lives here:
+ *
+ *   • install groups (npm-proxy / glpkg / skit) + legacy packages/skits → channels
+ *     + package requests, all probed ANONYMOUSLY (reproduces a first-time
+ *     end-user with no token).
+ *   • transitive closure discovery: uses the publisher's token to expand npm
+ *     deps via the proxy, then hands the discovered nodes back to the engine to
+ *     probe anonymously — so a private transitive dep (401 for end-users) is
+ *     caught even though the publisher can see it.
+ *   • [B] the snapshot's OWN version must be stable when promoted to `latest`.
+ *
+ * See architecture/decisions — this is the blocking preflight gate wired into
+ * `snapshot publish` and the `snapshot preflight` command.
+ */
+import { formatReport, createNpmPackumentResolver, type PreflightInput, type PreflightReport, type Resolver } from '@microwiseai/install-preflight';
+import type { Snapshot } from './types.js';
+export interface SnapshotPreflightOptions {
+    /** Attempt transitive-closure discovery (needs a token). Default: true. */
+    includeTransitive?: boolean;
+    /** dist-tag this publish targets (default 'latest'). */
+    distTag?: string;
+    /** Verbose progress logging via the provided sink. */
+    log?: (msg: string) => void;
+    /** Override the engine's network resolver (tests / custom lanes). */
+    resolver?: Resolver;
+}
+export interface SnapshotPreflightResult {
+    report: PreflightReport;
+    /** Non-fatal warnings (e.g. transitive discovery skipped). Surfaced, never silent. */
+    warnings: string[];
+}
+/**
+ * Build the full engine input for a snapshot: anonymous channels + direct pins
+ * (+ discovered transitive closure). Exposed for testing/other callers.
+ */
+export declare function buildSnapshotPreflightInput(snapshot: Snapshot, options?: SnapshotPreflightOptions): Promise<{
+    input: PreflightInput;
+    warnings: string[];
+}>;
+/**
+ * Run the blocking preflight gate for a snapshot. Combines:
+ *   [A] anonymous resolvability of the whole closure (engine), and
+ *   [B] the snapshot's own version must be stable when promoted to `latest`.
+ */
+export declare function runSnapshotPreflight(snapshot: Snapshot, options?: SnapshotPreflightOptions): Promise<SnapshotPreflightResult>;
+export { formatReport, createNpmPackumentResolver };
+//# sourceMappingURL=preflight-adapter.d.ts.map

package/dist/lib/preflight-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight-adapter.d.ts","sourceRoot":"","sources":["../../src/lib/preflight-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEL,YAAY,EACZ,0BAA0B,EAE1B,KAAK,cAAc,EACnB,KAAK,eAAe,EAIpB,KAAK,QAAQ,EACd,MAAM,gCAAgC,CAAC;AAIxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAK3C,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,eAAe,CAAC;IACxB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA2KD;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAqBxD;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CAsBlC;AAED,OAAO,EAAE,YAAY,EAAE,0BAA0B,EAAE,CAAC"}