@microwiseai/snapshot 0.5.0 → 0.5.2

package/dist/lib/preflight-adapter.js

@@ -0,0 +1,224 @@
+/**
+ * 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 { preflight, formatReport, createNpmPackumentResolver, checkStableRelease, } from '@microwiseai/install-preflight';
+import { REGISTRY_PROXY_URL, GITLAB_GROUP_ID, getLicenseKey, getProxyAuthToken } from './config.js';
+import { resolveDepsFromLicenseAPI, isDistkitClosureEnabled } from './transitive-resolver.js';
+/** Installer groups whose members resolve as npm-style packages through the proxy. */
+const NPM_LIKE_GROUPS = new Set(['npm-proxy', 'glpkg', 'gitlab-install', 'skit']);
+/** Extract the `@scope` prefix of a package name, or null. */
+function scopeOf(name) {
+    return name.startsWith('@') && name.includes('/') ? name.split('/')[0] : null;
+}
+/** True for names that legacy `packages`/`skits` maps treat as skits. */
+function isSkitName(name) {
+    return name.endsWith('-kit') || name.endsWith('kit');
+}
+/**
+ * Build one anonymous channel per installer lane actually used by the snapshot.
+ * All lanes hit the same registry-proxy packument endpoint (`GET /{name}`),
+ * differing only by id/scope for reporting.
+ */
+function buildChannels(scopes) {
+    const base = {
+        registryUrl: REGISTRY_PROXY_URL,
+        auth: { kind: 'anonymous' },
+        strategy: 'npm-packument',
+        scopes,
+        groupId: GITLAB_GROUP_ID,
+    };
+    return [
+        { id: 'npm-proxy', ...base },
+        { id: 'glpkg', ...base },
+        { id: 'skit', ...base },
+    ];
+}
+/** Collect the DIRECT pins declared by a snapshot into engine requests. */
+function collectDirectRequests(snapshot) {
+    const requests = [];
+    const push = (channel, name, range) => {
+        requests.push({ name, range, channel });
+    };
+    // New installer-based structure.
+    if (snapshot.install) {
+        for (const [installer, pkgs] of Object.entries(snapshot.install)) {
+            const channel = installer === 'gitlab-install' ? 'glpkg' : installer;
+            for (const [name, version] of Object.entries(pkgs)) {
+                push(channel === 'npm-proxy' || channel === 'glpkg' || channel === 'skit' ? channel : 'npm-proxy', name, version);
+            }
+        }
+    }
+    // Legacy maps.
+    if (snapshot.packages) {
+        for (const [name, version] of Object.entries(snapshot.packages)) {
+            push(isSkitName(name) ? 'skit' : 'npm-proxy', name, version);
+        }
+    }
+    if (snapshot.skits) {
+        for (const [name, version] of Object.entries(snapshot.skits)) {
+            push('skit', name, version);
+        }
+    }
+    return requests;
+}
+/** Scopes declared by the snapshot's registry block (fallback to pins' scopes). */
+function collectScopes(snapshot, requests) {
+    const scopes = new Set();
+    if (snapshot.registry) {
+        for (const scope of Object.keys(snapshot.registry))
+            scopes.add(scope);
+    }
+    if (scopes.size === 0) {
+        for (const r of requests) {
+            const s = scopeOf(r.name);
+            if (s)
+                scopes.add(s);
+        }
+    }
+    return Array.from(scopes);
+}
+/**
+ * Discover transitive npm deps via the proxy (token-authenticated), returning
+ * extra requests to probe ANONYMOUSLY. Failure is non-fatal: it returns a
+ * warning so coverage gaps are surfaced, never silently dropped.
+ */
+async function discoverTransitive(direct, scopes) {
+    const token = getLicenseKey() || getProxyAuthToken();
+    if (!token) {
+        return {
+            requests: [],
+            warning: 'Transitive-closure discovery skipped: no token available (login for full coverage). ' +
+                'Only directly-declared pins were checked.',
+        };
+    }
+    // Expand npm/glpkg-lane pins within tracked scopes.
+    const npmDirect = direct.filter((r) => (r.channel === 'npm-proxy' || r.channel === 'glpkg') && scopes.some((s) => r.name.startsWith(s)));
+    if (npmDirect.length === 0 || scopes.length === 0)
+        return { requests: [] };
+    // ── §5-step6 CUTOVER SWITCH (behind SNAPSHOT_DISTKIT_CLOSURE) ──────────────
+    // flag ON: resolve the transitive closure CLIENT-SIDE via distkit walkClosure
+    // (subsumes /resolve-deps — §3d). PREFLIGHT probes the PRIVATE lane (a private
+    // transitive dep that 401s anonymously is the risk this gate exists for; public
+    // deps are npmjs-anonymous-trivial). §1.4 fail-loud: a resolver error propagates
+    // (NOT swallowed into a warning) — a partial closure would be a wrong gate.
+    // The full public-inclusive closure/lock is produced separately by
+    // resolveSnapshotToLock; it is not what the anonymous-probe gate needs.
+    if (isDistkitClosureEnabled()) {
+        // DYNAMIC import: the distkit bridge is loaded ONLY on the flag-ON path, so
+        // flag-OFF (default) has NO load-time dependency on distkit — 100% reversible
+        // and shippable even while distkit is unpublished/unlinked.
+        const { resolveTransitiveClosureFromPins } = await import('./distkit-closure-bridge.js');
+        const closure = await resolveTransitiveClosureFromPins(npmDirect.map((r) => ({ name: r.name, version: r.range })), scopes);
+        const directNames = new Set(direct.map((r) => `${r.channel}:${r.name}`));
+        const requests = [];
+        for (const node of closure) {
+            if (!scopes.some((s) => node.name.startsWith(s)))
+                continue; // private lane only (preflight)
+            if (directNames.has(`npm-proxy:${node.name}`) || directNames.has(`glpkg:${node.name}`))
+                continue;
+            requests.push({
+                name: node.name,
+                range: node.version,
+                channel: 'npm-proxy',
+                requestedBy: node.requestedBy.join(', ') || '(transitive closure)',
+            });
+        }
+        return { requests };
+    }
+    // flag OFF (default): legacy /resolve-deps path — COMPLETELY UNCHANGED.
+    try {
+        const resolved = await resolveDepsFromLicenseAPI({
+            packages: npmDirect.map((r) => `${r.name}@${r.range}`),
+            groupId: GITLAB_GROUP_ID,
+            scopes,
+            includePeer: true,
+        });
+        const directNames = new Set(direct.map((r) => `${r.channel}:${r.name}`));
+        const requests = [];
+        for (const [name, version] of Object.entries(resolved.dependencies)) {
+            if (directNames.has(`npm-proxy:${name}`) || directNames.has(`glpkg:${name}`))
+                continue;
+            requests.push({
+                name,
+                range: version,
+                channel: 'npm-proxy',
+                requestedBy: '(transitive closure)',
+            });
+        }
+        for (const [name, version] of Object.entries(resolved.peerDependencies ?? {})) {
+            if (requests.some((r) => r.name === name) || directNames.has(`npm-proxy:${name}`))
+                continue;
+            requests.push({ name, range: version, channel: 'npm-proxy', requestedBy: '(peer dependency)' });
+        }
+        return { requests };
+    }
+    catch (err) {
+        return {
+            requests: [],
+            warning: `Transitive-closure discovery failed (${err instanceof Error ? err.message : String(err)}). ` +
+                'Only directly-declared pins were checked — transitive private/unpublished deps may be missed.',
+        };
+    }
+}
+/**
+ * Build the full engine input for a snapshot: anonymous channels + direct pins
+ * (+ discovered transitive closure). Exposed for testing/other callers.
+ */
+export async function buildSnapshotPreflightInput(snapshot, options = {}) {
+    const { includeTransitive = true, distTag = 'latest' } = options;
+    const warnings = [];
+    const direct = collectDirectRequests(snapshot);
+    const scopes = collectScopes(snapshot, direct);
+    let packages = direct;
+    if (includeTransitive) {
+        const { requests, warning } = await discoverTransitive(direct, scopes);
+        if (warning)
+            warnings.push(warning);
+        packages = [...direct, ...requests];
+    }
+    const input = {
+        channels: buildChannels(scopes),
+        packages,
+        policy: { distTag, requireStableForTags: ['latest'], forbidPrereleaseDefaultResolve: true },
+        resolver: options.resolver,
+    };
+    return { input, warnings };
+}
+/**
+ * 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 async function runSnapshotPreflight(snapshot, options = {}) {
+    const distTag = options.distTag ?? 'latest';
+    const { input, warnings } = await buildSnapshotPreflightInput(snapshot, options);
+    options.log?.(`Preflight: probing ${input.packages.length} package(s) anonymously across ${input.channels.length} channel(s)...`);
+    const report = await preflight(input);
+    // [B] (b1): the snapshot itself must be a stable release when → latest.
+    const selfFinding = snapshot.version
+        ? checkStableRelease(snapshot.version, { package: snapshot.name, channel: 'snapshot', requested: snapshot.version }, { distTag, requireStableForTags: ['latest'] })
+        : null;
+    if (selfFinding) {
+        report.findings.unshift(selfFinding);
+        report.ok = false;
+    }
+    return { report, warnings };
+}
+export { formatReport, createNpmPackumentResolver };
+//# sourceMappingURL=preflight-adapter.js.map

package/dist/lib/preflight-adapter.js.map

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

package/dist/lib/transitive-resolver.d.ts

@@ -43,6 +43,49 @@ export interface LicenseApiResolveDepsResponse {
     dependencies: Record<string, string>;
     peerDependencies?: Record<string, string>;
 }
+/** distkit-schema `Ecosystem` (opened union). Mirror. */
+export type Ecosystem = 'npm' | 'pypi' | (string & {});
+/** distkit-schema `Installer` (opened union). Mirror. */
+export type Installer = 'npm' | 'glpkg' | 'skit' | 'pip' | (string & {});
+/** distkit-schema `InstallTarget` (closed union). Mirror. */
+export type InstallTarget = 'cli-global' | 'project-local';
+/** distkit-schema `AccessTier` (closed union). Mirror. */
+export type AccessTier = 'public' | 'authenticated' | 'licensed' | 'restricted';
+/**
+ * The `package.json`-shaped manifest the distkit npm adapter's
+ * `parseDependencies` consumes (`adapters/npm.ts` `PackumentVersion`). Only the
+ * four dependency maps are meaningful to the adapter; everything else is ignored.
+ * This is what a ClosureRoot in the `'npm'` lane carries as its `manifest`.
+ */
+export interface NpmPackageJsonManifest {
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+}
+/**
+ * Mirror of distkit `ClosureRoot` (closure.ts:57): one already-pinned entry
+ * package whose `manifest` declares the first level of dependencies distkit's
+ * walker will expand transitively. `manifest` is `unknown` in the contract (the
+ * adapter knows its own shape); for the npm lane we populate it with an
+ * {@link NpmPackageJsonManifest}.
+ */
+export interface ClosureRoot {
+    /** package name, e.g. "@microwiseai/foo". */
+    name: string;
+    /** exact version of the root (already pinned). */
+    version: string;
+    /** ecosystem of the root; omitted ⇒ the matching adapter's ecosystem (C4). */
+    ecosystem?: Ecosystem;
+    /** the root's manifest, fed to `EcosystemAdapter.parseDependencies`. */
+    manifest: unknown;
+    /** installer to record for produced entries (else the adapter's default). */
+    installer?: Installer;
+    /** intended install location for produced entries. */
+    installTarget?: InstallTarget;
+    /** observed access tier for produced entries (authority = license-mgr). */
+    accessTier?: AccessTier;
+}
 export interface ResolveOptions {
     /** proxy를 통해 transitive deps 해석 */
     resolveTransitive?: boolean;
@@ -82,6 +125,84 @@ export interface ResolveDepsFromLicenseOptions {
  * // result.peerDependencies: { "typescript": "^5.0.0" }
  */
 export declare function resolveDepsFromLicenseAPI(options: ResolveDepsFromLicenseOptions): Promise<LicenseApiResolveDepsResponse>;
+/**
+ * Feature-flag gate for the new distkit closure path (§1.2 wiring target).
+ *
+ * OFF by default. Defined now so the future §1.2 caller has a single, documented
+ * switch; the collector itself is a pure additive export that no live path calls,
+ * so flipping this on has NO effect until §1.2 wires `walkClosure` behind it.
+ *
+ * Env: `SNAPSHOT_DISTKIT_CLOSURE=1` (or `true`).
+ */
+export declare const SNAPSHOT_DISTKIT_CLOSURE_FLAG: "SNAPSHOT_DISTKIT_CLOSURE";
+/** True iff the distkit closure path is enabled via {@link SNAPSHOT_DISTKIT_CLOSURE_FLAG}. */
+export declare function isDistkitClosureEnabled(): boolean;
+/** Options for {@link collectNpmClosureRoots}. */
+export interface CollectClosureRootsOptions {
+    /**
+     * Restrict roots to npm packages whose name starts with one of these scopes.
+     * Omitted ⇒ ALL declared npm packages become roots (recommended: distkit's
+     * walker expands each into its own transitive closure).
+     */
+    scopes?: string[];
+    /** `installTarget` hint stamped on every produced root. Default `'cli-global'`. */
+    installTarget?: InstallTarget;
+}
+/** Result of {@link collectNpmClosureRoots}. */
+export interface NpmClosureRootsResult {
+    /** one {@link ClosureRoot} per directly-declared npm entry package (ecosystem `'npm'`). */
+    roots: ClosureRoot[];
+    /** domain-walk + manifest-fetch failures (fail-soft at this pre-wiring stage). */
+    errors: Array<{
+        name: string;
+        error: string;
+    }>;
+    /** scope → groupId map collected from the snapshot `registry` fields (§1.3 routing feed). */
+    scopeGroups: Record<string, string>;
+}
+/**
+ * Phase-2b §1.1 collector: walk the snapshot/skit domain graph and emit the npm
+ * lane as `ClosureRoot[]` for distkit's `walkClosure`.
+ *
+ * Reuses `traverseSnapshot` (the unchanged domain-graph walk: `extends`, `skits`,
+ * `install`, `packages`, `registry`, and skit.json `dependencies.{npm,skit,cli}`)
+ * to discover the directly-declared npm packages, then fetches each one's
+ * `package.json`-shaped manifest and maps it to a {@link ClosureRoot}:
+ *
+ *   { name, version, ecosystem: 'npm', manifest, installTarget }
+ *
+ * NOTE (pre-wiring, fail-soft): a package whose manifest cannot be fetched is
+ * still emitted (with an empty `{}` manifest) and an error is recorded — so a
+ * parity fixture surfaces the gap. Authoritative fail-loud + range→exact version
+ * resolution move in with distkit's adapter at §1.2 / §1.4.
+ *
+ * This function is on NO live install path — it is the §1.1 deliverable only.
+ */
+export declare function collectNpmClosureRoots(snapshotName: string, options?: CollectClosureRootsOptions): Promise<NpmClosureRootsResult>;
+/**
+ * Build `ClosureRoot[]` from an explicit list of npm pins (name + exact version),
+ * fetching each pin's `package.json`-shaped manifest from the registry-proxy
+ * packument. Extracted from {@link collectNpmClosureRoots} (behaviour-identical)
+ * so the §5-step6 install-resolution switch can build roots from the pins the
+ * preflight adapter already computed (WITHOUT re-walking the snapshot graph —
+ * important during `snapshot publish`, where the snapshot is LOCAL/unpublished).
+ *
+ * Deterministic (sorted by name). A pin whose manifest cannot be fetched is still
+ * emitted (empty `{}` manifest) AND recorded in `errors` — the caller decides
+ * fail-soft (collector §1.1) vs fail-loud (install path §1.4).
+ */
+export declare function buildNpmClosureRoots(pins: ReadonlyArray<{
+    name: string;
+    version: string;
+}>, options?: {
+    installTarget?: InstallTarget;
+}): Promise<{
+    roots: ClosureRoot[];
+    errors: Array<{
+        name: string;
+        error: string;
+    }>;
+}>;
 /**
  * 캐시 클리어
  */

package/dist/lib/transitive-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transitive-resolver.d.ts","sourceRoot":"","sources":["../../src/lib/transitive-resolver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE;QACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9B,GAAG,CAAC,EAAE,KAAK,CAAC;YACV,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,MAAM,CAAC;SACjB,CAAC,CAAC;KACJ,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,YAAY,CAAC;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,0BAA0B;IACzC,uCAAuC;IACvC,GAAG,EAAE,eAAe,EAAE,CAAC;IACvB,sBAAsB;IACtB,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,kBAAkB;IAClB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAYD;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAmWD,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,0BAA0B,CAAC,CAqDrC;AAMD,MAAM,WAAW,6BAA6B;IAC5C,iEAAiE;IACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,6BAA6B,CAAC,CAiGxC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}
+{"version":3,"file":"transitive-resolver.d.ts","sourceRoot":"","sources":["../../src/lib/transitive-resolver.ts"],"names":[],"mappings":"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"}

package/dist/lib/transitive-resolver.js

@@ -427,10 +427,200 @@ export async function resolveDepsFromLicenseAPI(options) {
         throw new Error(`[resolveDepsFromLicenseAPI] Network error: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+// ============================================================
+// Phase-2b §1.1 — ClosureRoot[] collector (distkit npm lane)
+// ============================================================
+//
+// NEW PATH — behind a flag, called by NOBODY on the live install path yet.
+//
+// Scope (SSOT §1.1, §5 step 3): KEEP snapshot's snapshot/skit domain-graph walk
+// (`traverseSnapshot`/`traverseSkit`) exactly as-is; only change the OUTPUT
+// SHAPE. This collector reuses that walk (via a fresh TraversalContext, same as
+// `resolveAllDependencies`) to discover the directly-declared npm entry packages,
+// then emits one {@link ClosureRoot} per package for distkit's `walkClosure`.
+//
+// Explicitly OUT OF SCOPE here (later phases / sign-off gate):
+//   • §1.2 wiring distkit `walkClosure` / lock emit / cutover.
+//   • porting a cycle guard or first-writer dedup into this path — distkit's
+//     walker OWNS transitive cycle-safety + multi-parent dedup (§1.1 note). The
+//     `visited*` Sets used inside `traverseSnapshot`/`traverseSkit` are the
+//     snapshot DOMAIN-graph guard (extends/skit recursion) and stay on the
+//     legacy path only; they are NOT re-implemented for the npm closure here.
+//   • skit / glpkg lanes (§4 Phase-2c) — this collector is the npm lane only.
+/**
+ * Feature-flag gate for the new distkit closure path (§1.2 wiring target).
+ *
+ * OFF by default. Defined now so the future §1.2 caller has a single, documented
+ * switch; the collector itself is a pure additive export that no live path calls,
+ * so flipping this on has NO effect until §1.2 wires `walkClosure` behind it.
+ *
+ * Env: `SNAPSHOT_DISTKIT_CLOSURE=1` (or `true`).
+ */
+export const SNAPSHOT_DISTKIT_CLOSURE_FLAG = 'SNAPSHOT_DISTKIT_CLOSURE';
+/** True iff the distkit closure path is enabled via {@link SNAPSHOT_DISTKIT_CLOSURE_FLAG}. */
+export function isDistkitClosureEnabled() {
+    const v = process.env[SNAPSHOT_DISTKIT_CLOSURE_FLAG];
+    return v === '1' || v === 'true';
+}
+/**
+ * Cache of fetched npm root manifests (package.json-shaped), keyed `name@version`.
+ * Separate from {@link skitManifestCache} (that reads the packument `skit` field;
+ * this reads the standard npm dependency maps).
+ */
+const npmRootManifestCache = new Map();
+/**
+ * Fetch an npm root's `package.json`-shaped manifest from the registry-proxy
+ * packument (`GET {REGISTRY_PROXY_URL}/{name}` → `{ 'dist-tags', versions }`).
+ *
+ * This is the npm analogue of {@link fetchSkitManifest}: same packument source,
+ * but it reads the standard npm dependency maps
+ * (`dependencies`/`optionalDependencies`/`devDependencies`/`peerDependencies`)
+ * that the distkit npm adapter's `parseDependencies` expects — NOT the `skit`
+ * field. Resolves the `latest` dist-tag; other specs are looked up as exact keys.
+ *
+ * @returns the manifest + the exact version it resolved to, or `null` if the
+ *   package / version is not present (surfaced by the collector as an error;
+ *   authoritative range→exact resolution is distkit's adapter job at §1.2).
+ */
+async function fetchNpmRootManifest(pkgName, version) {
+    const cacheKey = `${pkgName}@${version}`;
+    const cached = npmRootManifestCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const sessionToken = getLicenseKey();
+    const headers = {
+        'Accept': 'application/json',
+    };
+    if (sessionToken) {
+        headers['Authorization'] = `Bearer ${sessionToken}`;
+    }
+    try {
+        const url = `${REGISTRY_PROXY_URL}/${pkgName}`;
+        const response = await fetch(url, { headers });
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        const distTags = data['dist-tags'];
+        const versions = data['versions'];
+        // Resolve the `latest` dist-tag; otherwise treat `version` as an exact key.
+        // (Range specs are NOT resolved here — distkit's adapter owns range→exact at
+        // §1.2; an unresolvable spec yields null and a recorded collector error.)
+        let targetVersion = version;
+        if ((version === 'latest' || version === '') && distTags?.['latest']) {
+            targetVersion = distTags['latest'];
+        }
+        const versionData = versions?.[targetVersion];
+        if (!versionData) {
+            return null;
+        }
+        const manifest = {};
+        const deps = versionData['dependencies'];
+        const optional = versionData['optionalDependencies'];
+        const dev = versionData['devDependencies'];
+        const peer = versionData['peerDependencies'];
+        if (deps)
+            manifest.dependencies = { ...deps };
+        if (optional)
+            manifest.optionalDependencies = { ...optional };
+        if (dev)
+            manifest.devDependencies = { ...dev };
+        if (peer)
+            manifest.peerDependencies = { ...peer };
+        const result = { manifest, resolvedVersion: targetVersion };
+        npmRootManifestCache.set(cacheKey, result);
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Phase-2b §1.1 collector: walk the snapshot/skit domain graph and emit the npm
+ * lane as `ClosureRoot[]` for distkit's `walkClosure`.
+ *
+ * Reuses `traverseSnapshot` (the unchanged domain-graph walk: `extends`, `skits`,
+ * `install`, `packages`, `registry`, and skit.json `dependencies.{npm,skit,cli}`)
+ * to discover the directly-declared npm packages, then fetches each one's
+ * `package.json`-shaped manifest and maps it to a {@link ClosureRoot}:
+ *
+ *   { name, version, ecosystem: 'npm', manifest, installTarget }
+ *
+ * NOTE (pre-wiring, fail-soft): a package whose manifest cannot be fetched is
+ * still emitted (with an empty `{}` manifest) and an error is recorded — so a
+ * parity fixture surfaces the gap. Authoritative fail-loud + range→exact version
+ * resolution move in with distkit's adapter at §1.2 / §1.4.
+ *
+ * This function is on NO live install path — it is the §1.1 deliverable only.
+ */
+export async function collectNpmClosureRoots(snapshotName, options = {}) {
+    const { scopes, installTarget = 'cli-global' } = options;
+    // 1. Reuse the unchanged snapshot/skit domain-graph walk (same ctx shape as
+    //    resolveAllDependencies) to collect the directly-declared npm packages.
+    const ctx = {
+        visitedSnapshots: new Set(),
+        visitedSkits: new Set(),
+        collectedNpm: new Map(),
+        collectedSkit: new Map(),
+        errors: [],
+        scopeGroups: new Map(),
+    };
+    await traverseSnapshot(snapshotName, ctx);
+    // 2. Select npm entry packages → optionally filter by scope.
+    let entries = Array.from(ctx.collectedNpm.values());
+    if (scopes && scopes.length > 0) {
+        entries = entries.filter(p => scopes.some(scope => p.name.startsWith(scope)));
+    }
+    // 3. Fetch each root's package.json-shaped manifest and map → ClosureRoot[].
+    const { roots, errors: rootErrors } = await buildNpmClosureRoots(entries, { installTarget });
+    return {
+        roots,
+        errors: [...ctx.errors, ...rootErrors],
+        scopeGroups: Object.fromEntries(ctx.scopeGroups),
+    };
+}
+/**
+ * Build `ClosureRoot[]` from an explicit list of npm pins (name + exact version),
+ * fetching each pin's `package.json`-shaped manifest from the registry-proxy
+ * packument. Extracted from {@link collectNpmClosureRoots} (behaviour-identical)
+ * so the §5-step6 install-resolution switch can build roots from the pins the
+ * preflight adapter already computed (WITHOUT re-walking the snapshot graph —
+ * important during `snapshot publish`, where the snapshot is LOCAL/unpublished).
+ *
+ * Deterministic (sorted by name). A pin whose manifest cannot be fetched is still
+ * emitted (empty `{}` manifest) AND recorded in `errors` — the caller decides
+ * fail-soft (collector §1.1) vs fail-loud (install path §1.4).
+ */
+export async function buildNpmClosureRoots(pins, options = {}) {
+    const { installTarget = 'cli-global' } = options;
+    const errors = [];
+    const roots = [];
+    for (const pkg of pins) {
+        const fetched = await fetchNpmRootManifest(pkg.name, pkg.version);
+        if (!fetched) {
+            errors.push({
+                name: `${pkg.name}@${pkg.version}`,
+                error: 'Failed to fetch npm root manifest (package/version not in packument, or non-exact spec)',
+            });
+        }
+        roots.push({
+            name: pkg.name,
+            version: fetched?.resolvedVersion ?? pkg.version,
+            ecosystem: 'npm',
+            manifest: fetched?.manifest ?? {},
+            installTarget,
+        });
+    }
+    // Deterministic order (parity-friendly; distkit re-sorts internally anyway).
+    roots.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return { roots, errors };
+}
 /**
  * 캐시 클리어
  */
 export function clearTransitiveCache() {
     skitManifestCache.clear();
+    npmRootManifestCache.clear();
 }
 //# sourceMappingURL=transitive-resolver.js.map