@intx/tool-packaging 0.2.2

package/dist/package-json-extract.d.ts

@@ -0,0 +1,56 @@
+import { PackageJSON } from "@intx/types/package-json";
+/**
+ * Outcome of extracting the top-level `package.json` entry from an
+ * npm-style tarball.
+ *
+ * `kind: "ok"` carries a value already validated against `PackageJSON`;
+ * `kind: "shape-invalid"` distinguishes "JSON parsed cleanly but did
+ * not match the expected schema" from "the JSON itself was malformed"
+ * (`kind: "json-error"`). Callers that ship their own domain error type
+ * can map the rejected outcomes onto whatever shape they raise.
+ */
+export type ExtractPackageJSONOutcome = {
+    kind: "ok";
+    parsed: PackageJSON;
+    raw: unknown;
+} | {
+    kind: "missing-entry";
+} | {
+    kind: "multiple-entries";
+    paths: string[];
+} | {
+    kind: "parse-error";
+    message: string;
+} | {
+    kind: "json-error";
+    message: string;
+} | {
+    kind: "shape-invalid";
+    message: string;
+    raw: unknown;
+};
+/**
+ * Stream the tarball bytes through a tar parser, drain only the top-
+ * level `package.json` member, JSON.parse the collected bytes, run them
+ * through `PackageJSON`, and return a discriminated outcome. The bytes
+ * argument may be any Uint8Array (tarball or gzipped tarball —
+ * `tar.Parser` auto-detects gzip on the input stream).
+ *
+ * The tar entry is matched by its tail (`<segment>/package.json` with
+ * exactly two segments) rather than the literal `package/package.json`
+ * path because the sidecar's tarball extractor uses `strip:1` and
+ * therefore accepts any first segment. Matching by tail here keeps the
+ * hub's validation aligned with the sidecar's runtime contract — a
+ * tarball whose top-level directory is not literally `package/` will
+ * load identically in both places.
+ *
+ * On a tar parser failure the upstream readable is destroyed so a
+ * malformed archive does not leave a half-drained source buffered in
+ * the parser's internal state.
+ *
+ * The raw parsed JSON is surfaced alongside the validated descriptor on
+ * success so callers that need fields outside `PackageJSON`'s minimum
+ * schema (the resolver's `readDependencyFields` consumes `dependencies`,
+ * `optionalDependencies`, etc.) can read them without re-extracting.
+ */
+export declare function extractTarballPackageJSON(bytes: Uint8Array): Promise<ExtractPackageJSONOutcome>;

package/dist/package-json-extract.js

@@ -0,0 +1,125 @@
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference -- npm-team packages ship no types; declarations.d.ts must be visible to downstream typecheckers that import from this package's source.
+/// <reference path="./declarations.d.ts" />
+// Single source of truth for "open an npm-style tarball, find the
+// package/package.json entry, parse it as JSON, hand the parsed value
+// back". Used by the hub-side resolver (`AssetRegistrySource` builds
+// packuments from asset-stored tarballs) and the hub-sessions package
+// (the `package-registry` kind handler validates uploads before the
+// commit is accepted). Both call sites used to ship near-identical
+// streaming parsers; the duplication drifted independently.
+//
+// The helper returns a discriminated outcome rather than throwing so
+// each caller can construct its own domain-shaped error
+// (ManifestInvalidError on the resolver side, ValidatePushResult
+// reason string on the kind-handler side) without losing the
+// failure-class distinction.
+// This module is Node-bound: it streams through node:stream and the tar
+// library, which are not portable to environments without those APIs.
+import { Readable } from "node:stream";
+import { type } from "arktype";
+import { Parser as TarParser } from "tar/parse";
+import { concatBytes } from "@intx/types";
+import { PackageJSON } from "@intx/types/package-json";
+/**
+ * Stream the tarball bytes through a tar parser, drain only the top-
+ * level `package.json` member, JSON.parse the collected bytes, run them
+ * through `PackageJSON`, and return a discriminated outcome. The bytes
+ * argument may be any Uint8Array (tarball or gzipped tarball —
+ * `tar.Parser` auto-detects gzip on the input stream).
+ *
+ * The tar entry is matched by its tail (`<segment>/package.json` with
+ * exactly two segments) rather than the literal `package/package.json`
+ * path because the sidecar's tarball extractor uses `strip:1` and
+ * therefore accepts any first segment. Matching by tail here keeps the
+ * hub's validation aligned with the sidecar's runtime contract — a
+ * tarball whose top-level directory is not literally `package/` will
+ * load identically in both places.
+ *
+ * On a tar parser failure the upstream readable is destroyed so a
+ * malformed archive does not leave a half-drained source buffered in
+ * the parser's internal state.
+ *
+ * The raw parsed JSON is surfaced alongside the validated descriptor on
+ * success so callers that need fields outside `PackageJSON`'s minimum
+ * schema (the resolver's `readDependencyFields` consumes `dependencies`,
+ * `optionalDependencies`, etc.) can read them without re-extracting.
+ */
+export async function extractTarballPackageJSON(bytes) {
+    return new Promise((resolve) => {
+        let resolved = false;
+        let pkgJsonBuf = null;
+        const collectChunks = [];
+        // Capture every top-level `<seg>/package.json` path we see during
+        // the walk so the kind handler can reject ambiguous archives. The
+        // hub's resolver and the sidecar's tarball extractor resolve
+        // collisions differently — the resolver via this helper captures
+        // the first occurrence, while the sidecar's `tar.extract` with
+        // `strip:1` overwrites on every subsequent path with the same
+        // stripped name. A tarball carrying multiple top-level package
+        // directories therefore validates against the first entry on the
+        // hub but loads the last entry on the sidecar; the divergence is
+        // resolved at the validation boundary by refusing the upload.
+        const topLevelPackageJSONPaths = [];
+        const source = Readable.from([bytes]);
+        const finalize = (outcome) => {
+            if (resolved)
+                return;
+            resolved = true;
+            resolve(outcome);
+        };
+        const parser = new TarParser();
+        parser.on("entry", (entry) => {
+            const segments = entry.path.split("/");
+            const isTopLevelPackageJSON = segments.length === 2 && segments[1] === "package.json";
+            if (isTopLevelPackageJSON) {
+                topLevelPackageJSONPaths.push(entry.path);
+            }
+            if (isTopLevelPackageJSON && pkgJsonBuf === null) {
+                entry.on("data", (chunk) => {
+                    collectChunks.push(chunk);
+                });
+                entry.on("end", () => {
+                    pkgJsonBuf = concatBytes(collectChunks);
+                });
+            }
+            else {
+                entry.resume();
+            }
+        });
+        parser.on("error", (err) => {
+            source.destroy();
+            finalize({ kind: "parse-error", message: err.message });
+        });
+        parser.on("end", () => {
+            if (pkgJsonBuf === null) {
+                finalize({ kind: "missing-entry" });
+                return;
+            }
+            if (topLevelPackageJSONPaths.length > 1) {
+                finalize({
+                    kind: "multiple-entries",
+                    paths: topLevelPackageJSONPaths,
+                });
+                return;
+            }
+            let raw;
+            try {
+                raw = JSON.parse(new TextDecoder().decode(pkgJsonBuf));
+            }
+            catch (cause) {
+                finalize({
+                    kind: "json-error",
+                    message: cause instanceof Error ? cause.message : String(cause),
+                });
+                return;
+            }
+            const validated = PackageJSON(raw);
+            if (validated instanceof type.errors) {
+                finalize({ kind: "shape-invalid", message: validated.summary, raw });
+                return;
+            }
+            finalize({ kind: "ok", parsed: validated, raw });
+        });
+        source.pipe(parser);
+    });
+}

package/dist/resolver.d.ts

@@ -0,0 +1,241 @@
+import { type ToolPackageManifest, type ToolPackagePin, type ToolPackageSource } from "@intx/types/tool-packages";
+/**
+ * One HTTP registry. `url` is the actual endpoint; `auth.token` and
+ * `auth.basic` mirror the npm-registry-fetch options for bearer /
+ * basic auth.
+ *
+ * The registry's identifier (the string `scopeRouting` entries and
+ * manifest `registry` references point at) is the slot it occupies
+ * in the registry map: in the hub-side resolver, the key of the
+ * `ReadonlyMap<string, RegistrySource>` passed to
+ * `createClosureResolver`; in the sidecar-side loader, the key of
+ * the `ReadonlyMap<string, RegistryConfig>` on `LoaderConfig`.
+ * Keeping the name on the map slot rather than on the value
+ * eliminates the (until-now uninforced) "the map key must equal the
+ * config's name" invariant.
+ *
+ * The default-registry decision is owned by `defaultRegistry` on
+ * `ClosureResolverConfig`, not by a per-registry flag; only one
+ * entry can be the default and centralizing the choice keeps that
+ * invariant in the config object.
+ */
+export interface RegistryConfig {
+    readonly url: string;
+    readonly auth?: {
+        readonly token?: string;
+        readonly basic?: {
+            readonly user: string;
+            readonly pass: string;
+        };
+    };
+}
+/** Route packages in a given scope (e.g. `@intx`) to a named registry. */
+export interface ScopeRoute {
+    readonly scope: string;
+    readonly registry: string;
+}
+/**
+ * One version manifest as it appears inside a packument. Fields are
+ * non-readonly to match the npm-pick-manifest declaration; consumers
+ * should treat values as immutable in practice.
+ */
+export interface PackumentVersion {
+    name: string;
+    version: string;
+    dist: {
+        tarball: string;
+        integrity?: string;
+    };
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    peerDependenciesMeta?: Record<string, {
+        optional?: boolean;
+    }>;
+    os?: string[];
+    cpu?: string[];
+}
+/**
+ * The packument document a registry serves for one package. Shape
+ * matches what `npm-pick-manifest` accepts.
+ */
+export interface Packument {
+    name: string;
+    "dist-tags"?: Record<string, string>;
+    versions: Record<string, PackumentVersion>;
+}
+/**
+ * Test seam for HTTP packument fetches. The default `HttpRegistrySource`
+ * wraps `npm-registry-fetch`; tests inject a function that returns a
+ * static packument for a given `(name, registry)` pair.
+ */
+export type PackumentFetcher = (packageName: string, registry: RegistryConfig) => Promise<Packument>;
+/**
+ * The shape returned by `RegistrySource.materializeRefForEntry`. The
+ * walker copies these fields onto the `ToolPackageManifestEntry` it
+ * emits, alongside `name`, `version`, `integrity`, and the platform
+ * filter metadata it derives from the picked packument version.
+ */
+export interface MaterializedRef {
+    readonly source: ToolPackageSource;
+    /** Set for HTTP-sourced entries so the sidecar can fetch without
+     * re-resolving against the registry; asset-sourced entries omit it. */
+    readonly tarballUrl?: string;
+}
+/**
+ * A pluggable source of npm-style packuments and per-version source
+ * tags. The walker treats every named registry as one of these,
+ * regardless of whether bytes live behind an HTTP registry or inside a
+ * `package-registry` asset.
+ *
+ * `name` is the identifier the source was registered under in the
+ * resolver's registry map. Diagnostics that need to print a
+ * registry's name read it from here; the impls are the source of
+ * truth and the interface guarantees it is always available.
+ */
+export interface RegistrySource {
+    readonly name: string;
+    fetchPackument(name: string): Promise<Packument>;
+    materializeRefForEntry(name: string, version: string, picked: PackumentVersion): MaterializedRef;
+}
+/**
+ * Configuration for `createClosureResolver`.
+ *
+ * `registries` is keyed by the same name the agent's pin set
+ * references via the `registry` field in `ToolPackagePin`-derived
+ * entries (today indirectly via scope routing; built-ins reach this
+ * map by the registry name the session service resolved them from).
+ *
+ * `defaultRegistry` names the entry in `registries` consulted for any
+ * package whose scope does not match a `scopeRouting` entry. The map
+ * must contain this key.
+ */
+export interface ClosureResolverConfig {
+    readonly registries: ReadonlyMap<string, RegistrySource>;
+    readonly defaultRegistry: string;
+    readonly scopeRouting?: readonly ScopeRoute[];
+}
+export interface ClosureResolver {
+    resolveClosure(pins: readonly ToolPackagePin[]): Promise<ToolPackageManifest>;
+}
+/**
+ * One unsatisfied peer-dependency declaration discovered while
+ * resolving a closure.
+ */
+export interface PeerDependencyViolation {
+    readonly dependent: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly peer: {
+        readonly name: string;
+        readonly range: string;
+    };
+    readonly satisfiedBy: {
+        readonly version: string;
+    } | null;
+}
+/**
+ * Thrown by `resolveClosure` when the resolved closure does not satisfy
+ * one or more peer-dependency declarations, by the closure walker for
+ * duplicate-name pins, and by the hub-side session-launch path when a
+ * direct package-registry attachment overlaps a resolver-driven pin
+ * for the same asset. The deploy-assembly path maps every shape to
+ * the same `manifest.invalid` deploy-apply error category before the
+ * deploy ships.
+ *
+ * The category is intentionally broad: peer-dep violations and
+ * duplicate-name pins are structurally distinct defects but both
+ * indicate a closure the operator cannot ship without changing the
+ * pin set. Adding a per-shape category would expand the wire
+ * taxonomy for no operator-facing gain; readers parsing
+ * deploy-apply errors should look at the message for the structural
+ * distinction.
+ */
+export declare class ManifestInvalidError extends Error {
+    /**
+     * Populated only when the constructor was invoked with the
+     * structured peer-dependency form. String-constructed instances
+     * (duplicate-name pins, direct-vs-resolver-asset conflicts) carry
+     * an empty array — readers that need the structural distinction
+     * should consult `message` rather than treating `violations.length
+     * === 0` as a signal.
+     */
+    readonly violations: readonly PeerDependencyViolation[];
+    constructor(violationsOrMessage: readonly PeerDependencyViolation[] | string);
+}
+/**
+ * HTTP-backed registry source. Wraps `npm-registry-fetch` for packument
+ * lookups and emits registry-shaped manifest entries.
+ */
+export declare class HttpRegistrySource implements RegistrySource {
+    #private;
+    readonly name: string;
+    constructor(args: {
+        /** Registry identifier. Becomes the map slot key in the
+         * resolver's registries map. */
+        readonly name: string;
+        readonly config: RegistryConfig;
+        /** Test seam: when omitted, the default `npm-registry-fetch`
+         * wrapper is used. Production callers omit it. */
+        readonly fetchPackument?: PackumentFetcher;
+    });
+    fetchPackument(name: string): Promise<Packument>;
+    materializeRefForEntry(_name: string, _version: string, picked: PackumentVersion): MaterializedRef;
+}
+/**
+ * Asset-backed registry source. Reads tarballs from a
+ * `package-registry` asset via the asset service's in-process read
+ * API, extracts each tarball's `package.json`, and synthesizes a
+ * packument keyed by package name with one version entry per tarball.
+ *
+ * Caller passes bound `readBlob`/`listBlobs` methods so the resolver
+ * does not import the asset service directly; the session service
+ * adapts `AssetService.readAssetBlob` / `AssetService.listAssetBlobs`
+ * to these signatures at construction.
+ *
+ * The packument is cached in-instance for the lifetime of the source,
+ * so one resolution pass touches each tarball at most once even when
+ * a name is asked for multiple times.
+ */
+export declare class AssetRegistrySource implements RegistrySource {
+    #private;
+    readonly name: string;
+    constructor(args: {
+        readonly name: string;
+        readonly assetId: string;
+        readonly readBlob: (path: string) => Promise<Uint8Array>;
+        readonly listBlobs: (dir: string) => Promise<string[]>;
+    });
+    fetchPackument(name: string): Promise<Packument>;
+    /**
+     * Resolve a `(name, version)` pair to its asset-relative tarball
+     * path. Must be called after `fetchPackument` has populated the
+     * internal index for that package — the walker calls them in that
+     * order, so the ordering is implicit at the call site. Non-walker
+     * callers must call `fetchPackument` first or accept the structured
+     * error this method throws when the index lookup misses.
+     */
+    materializeRefForEntry(name: string, version: string, _picked: PackumentVersion): MaterializedRef;
+}
+export declare function createClosureResolver(config: ClosureResolverConfig): ClosureResolver;
+/**
+ * Parse and canonicalize a `name@range` spec into a pin. Throws on
+ * unparseable specs or invalid version ranges. Callers that already
+ * have a `ToolPackagePin` do not need this helper.
+ *
+ * A bare `*` is accepted because npm semantics treat it as the
+ * any-version range; the resolver then picks whatever the registry
+ * advertises as latest at deploy-assembly time. Operators who care
+ * about reproducibility of tool-package closures should pin to a
+ * concrete range (`^1.2.3`) — `*` lets the closure shift under the
+ * agent without any change to the pin set.
+ *
+ * NOTE: `*` is special-cased in two places — here and inside the
+ * `ToolPackagePinArray` narrow at `@intx/types/tool-packages`. The
+ * sites live in separate packages by design (resolver vs. wire-type
+ * validation) and cannot import each other; any new magic-range
+ * additions need to be made at both call sites to keep the
+ * REST-boundary validator and the resolver in agreement.
+ */
+export declare function parsePin(spec: string): ToolPackagePin;