@intx/tool-packaging 0.2.2

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { type ClosureResolver, type ClosureResolverConfig, type MaterializedRef, type Packument, type PackumentFetcher, type PackumentVersion, type PeerDependencyViolation, type RegistryConfig, type RegistrySource, type ScopeRoute, AssetRegistrySource, HttpRegistrySource, ManifestInvalidError, createClosureResolver, parsePin, } from "./resolver.js";
+export { type TarballCache, type TarballCacheConfig, TarballIntegrityMismatchError, createTarballCache, } from "./cache.js";
+export { type HostPlatform, type LoadManifestArgs, type LoadedDirectorFactory, type LoadedToolFactory, type LoadedToolPackage, type LoaderConfig, type TarballFetcher, type ToolLoader, ToolLoaderError, createToolLoader, } from "./loader.js";
+export { type ApplyAtomicArgs, type ApplyAtomicFailure, type ApplyAtomicResult, type ApplyAtomicSuccess, applyAtomic, } from "./atomic-apply.js";
+export { type ExtractPackageJSONOutcome, extractTarballPackageJSON, } from "./package-json-extract.js";

package/dist/index.js

@@ -0,0 +1,30 @@
+// @intx/tool-packaging — the single API boundary the rest of the tree
+// uses to flow tool packages through the system.
+//
+// Owns every npm-team dependency (`npm-registry-fetch`,
+// `npm-package-arg`, `npm-pick-manifest`, `semver`, `tar`, `ssri`). No
+// other package in this monorepo imports those directly — consumers
+// reach for `@intx/tool-packaging`'s clean surface instead. If the
+// underlying npm tooling ever needs to be swapped or vendored, this
+// package is the only boundary that has to change.
+//
+// Two surface areas:
+//
+//   - Hub-side (deploy assembly):
+//       createClosureResolver({ registries, scopeRouting? })
+//         → resolveClosure(pins) → ToolPackageManifest
+//
+//   - Sidecar-side (deploy apply):
+//       createTarballCache({ rootDir, maxBytes }) — content-addressable
+//       store keyed by SRI integrity.
+//       createToolLoader({ cache, registries, host, … }) — fetches,
+//       extracts, and dynamic-imports each pinned package.
+//       applyAtomic({ manifest, loader, … }) — per-deploy-id apply
+//       protocol that stages each deploy into its own never-renamed
+//       directory and maps every loader failure category onto an
+//       `ApplyAtomicFailure` the caller surfaces as a rejected apply.
+export { AssetRegistrySource, HttpRegistrySource, ManifestInvalidError, createClosureResolver, parsePin, } from "./resolver.js";
+export { TarballIntegrityMismatchError, createTarballCache, } from "./cache.js";
+export { ToolLoaderError, createToolLoader, } from "./loader.js";
+export { applyAtomic, } from "./atomic-apply.js";
+export { extractTarballPackageJSON, } from "./package-json-extract.js";

package/dist/loader.d.ts

@@ -0,0 +1,189 @@
+import type { AnnotatedDirectorFactory, AnnotatedPluginFactory, AnnotatedToolFactory, BaseEnv } from "@intx/agent";
+import type { DeployApplyErrorCategory } from "@intx/types/sidecar";
+import type { ToolPackageManifest, ToolPackageManifestEntry } from "@intx/types/tool-packages";
+import type { TarballCache } from "./cache.js";
+import type { RegistryConfig } from "./resolver.js";
+/**
+ * Loaded factory shape. We re-export `AnnotatedToolFactory<BaseEnv>` so
+ * callers receive the canonical agent type without re-deriving it; the
+ * loader still performs the structural check at import time so a
+ * package emitting something that does not satisfy this shape is
+ * rejected with `package.entry.invalid`.
+ */
+export type LoadedToolFactory = AnnotatedToolFactory<BaseEnv>;
+/**
+ * Loaded director factory shape. Same erased-Config storage as the
+ * registry uses: the loader walks `interchange.directors` and surfaces
+ * every export the structural check accepts. Downstream consumers feed
+ * these into `createDirectorRegistry` alongside the built-in defaults.
+ */
+export type LoadedDirectorFactory = AnnotatedDirectorFactory<unknown, BaseEnv>;
+/** One pinned package after materialization and entry-module import. */
+export interface LoadedToolPackage {
+    readonly name: string;
+    readonly version: string;
+    readonly factories: readonly LoadedToolFactory[];
+    /**
+     * Plugin factories the package's `interchange.tools` module exported
+     * (via `definePlugin`). Plugins are instantiated by the loader before
+     * tool factories are run; their results are passed via `env.plugins`
+     * to the tool factories that read them.
+     */
+    readonly plugins: readonly AnnotatedPluginFactory[];
+    /**
+     * Director factories the package's `interchange.directors` module
+     * exported (via `defineDirector`). The capability walk resolves
+     * `DirectorRef.id` against these at deploy time; the agent runtime
+     * resolves them again at instantiation. Empty when the package's
+     * `package.json` omits the `interchange.directors` field — the
+     * walker treats absence as a no-op so a tools-only package stays
+     * valid.
+     */
+    readonly directors: readonly LoadedDirectorFactory[];
+}
+export interface HostPlatform {
+    readonly os: string;
+    readonly cpu: string;
+}
+export interface LoaderConfig {
+    readonly cache: TarballCache;
+    /**
+     * Registry identifier → registry config. The key is the same
+     * `registry` identifier manifest entries point at and the resolver
+     * keyed its own registries map under. The loader resolves each
+     * `kind: "registry"` entry by looking up this map.
+     */
+    readonly registries: ReadonlyMap<string, RegistryConfig>;
+    readonly host: HostPlatform;
+    /**
+     * Hard cap on the byte length of a tarball fetched from an HTTP
+     * registry. The default fetcher honors both the upstream
+     * `Content-Length` header (rejecting up front when the header value
+     * exceeds the cap) and the realized body byte count (aborting the
+     * read once the running total crosses the cap). Asset-sourced
+     * tarballs do not go through this path; their containment is the
+     * substrate's upload-time cap on the hub side.
+     *
+     * The default mirrors the hub's `HUB_MAX_TARBALL_BYTES` cap so a
+     * tarball legitimately accepted by the hub-side upload route is
+     * also legitimately fetchable from a registry mirror seeded from
+     * that hub. An operator pointing the sidecar at a third-party
+     * registry whose curated tarballs run larger should raise the cap
+     * explicitly rather than relying on the runtime to grow.
+     */
+    readonly maxRegistryTarballBytes?: number;
+    /**
+     * Deadline in milliseconds for a single HTTP-registry tarball fetch,
+     * spanning the request and the streamed body read. A stalled registry
+     * cannot block the fetch -- and the deploy's tool materialization
+     * awaiting it -- past this bound. Defaults to
+     * `DEFAULT_REGISTRY_FETCH_TIMEOUT_MS`. Asset-sourced tarballs read from
+     * the local filesystem and are not subject to it.
+     */
+    readonly registryFetchTimeoutMs?: number;
+    /**
+     * Test seam for tarball fetching. Production omits this and the
+     * loader uses npm-registry-fetch + filesystem reads.
+     */
+    readonly fetchTarball?: TarballFetcher;
+    /**
+     * Test seam for dynamic import. Production omits this and the loader
+     * uses the native dynamic-import expression. The argument is the URL
+     * the loader hands to `import()`: a `file://` URL with an
+     * `integrity=<sri>` query string the loader appends to bust Node's
+     * ESM module cache across applies that swap bytes under the same
+     * `(name, version)` pair.
+     */
+    readonly importModule?: (importUrl: string) => Promise<unknown>;
+}
+/**
+ * Default cap on a single HTTP-registry tarball fetch. Matches the
+ * hub's `DEFAULT_HUB_MAX_TARBALL_BYTES` so a tarball the hub accepted
+ * on upload is one the sidecar can also fetch back when a registry
+ * mirror replays it.
+ */
+export declare const DEFAULT_MAX_REGISTRY_TARBALL_BYTES: number;
+/**
+ * Default deadline for a single HTTP-registry tarball fetch, covering
+ * both the request and the streamed body read. `readResponseWithLimit`
+ * consumes the body through a manual reader loop, so the byte cap bounds
+ * size but nothing bounds time: a registry that accepts the connection
+ * and then stalls mid-stream would block the fetch -- and the deploy's
+ * tool materialization awaiting it -- indefinitely.
+ * The deadline is generous so a legitimately large tarball on a slow
+ * link still completes within it. Callers that need a different bound
+ * pass `registryFetchTimeoutMs` to `createToolLoader`.
+ */
+export declare const DEFAULT_REGISTRY_FETCH_TIMEOUT_MS: number;
+export type TarballFetcher = (entry: ToolPackageManifestEntry, ctx: {
+    registries: ReadonlyMap<string, RegistryConfig>;
+    assetRoot: string;
+    assetMounts: ReadonlyMap<string, string>;
+}) => Promise<Uint8Array>;
+export interface LoadManifestArgs {
+    readonly manifest: ToolPackageManifest;
+    readonly instanceScratchDir: string;
+    /**
+     * Filesystem root that `assetMounts` paths are joined against. Mount
+     * paths from the deploy pack are workspace-relative; the loader
+     * resolves them against `assetRoot` to get the absolute tarball
+     * location for `kind: "asset"` entries.
+     */
+    readonly assetRoot: string;
+    /**
+     * Maps a `source.assetId` from a manifest entry to a
+     * workspace-relative mount path. The session service emits this map
+     * into the deploy pack as `deploy/asset-mounts.json`; the sidecar
+     * threads it through to here. Empty map is valid when no entry
+     * sources from an asset.
+     */
+    readonly assetMounts: ReadonlyMap<string, string>;
+}
+export interface ToolLoader {
+    loadManifest(args: LoadManifestArgs): Promise<LoadedToolPackage[]>;
+}
+export declare class ToolLoaderError extends Error {
+    readonly category: DeployApplyErrorCategory;
+    readonly package: {
+        readonly name: string;
+        readonly version: string;
+    } | undefined;
+    constructor(opts: {
+        category: DeployApplyErrorCategory;
+        message: string;
+        package?: {
+            name: string;
+            version: string;
+        };
+    });
+}
+export declare function createToolLoader(config: LoaderConfig): ToolLoader;
+export declare function buildRegistryFetchOpts(registry: RegistryConfig): Record<string, unknown>;
+/**
+ * Read an HTTP-registry tarball response into a Uint8Array while enforcing
+ * `maxBytes`. Two guards:
+ *
+ *   1. If the upstream sent a `Content-Length` header, parse it (digit-
+ *      only, per RFC 9110 §8.6) and reject up front when the declared
+ *      length exceeds the cap. A header that fails the digit shape is
+ *      also rejected so a header like `1e9` cannot read as 1e9 against
+ *      `Number()` while a digit-only cap check would pass.
+ *   2. Stream the body chunk-by-chunk, tallying byte length, and abort
+ *      the read when the running total crosses the cap. This catches
+ *      the missing-or-lying header case.
+ *
+ * An optional `signal` adds a time guard: when it aborts (the caller's
+ * fetch deadline), the in-flight read is cancelled and the call rejects,
+ * so a registry that streams the body slowly or stalls mid-stream cannot
+ * outlast the deadline while staying under the byte cap.
+ *
+ * All rejections surface as `registry.fetch.failed` so the apply layer
+ * routes them the same as any other registry-side fetch defect.
+ *
+ * Exported for direct unit testing.
+ */
+export declare function readResponseWithLimit(res: Response, maxBytes: number, ctx: {
+    readonly registry: string;
+    readonly name: string;
+    readonly version: string;
+}, signal?: AbortSignal): Promise<Uint8Array>;