@wardby/cli 0.2.0 → 0.3.0

package/dist/coding/registry/pypi.js

@@ -0,0 +1,210 @@
+/**
+ * PyPI registry adapter: parses PyPI allowlist syntax (PEP 503 names, PEP
+ * 440 specifiers), routes proxy requests against the PEP 691 JSON Simple
+ * API plus PEP 658 metadata files, restricts downloads to wheels, and
+ * configures pip for the sandboxed worker to use the proxy as its only
+ * index with binary-only installs.
+ */
+import { clean as pepClean, compare as pepCompare, satisfies as pepSatisfies, validRange } from "@renovatebot/pep440";
+import { unzipSync, strFromU8 } from "fflate";
+import { AllowlistEntryError, RegistryError, } from "./types.js";
+const UPSTREAM = "https://pypi.org/simple/";
+const SIMPLE_JSON = "application/vnd.pypi.simple.v1+json";
+const ENTRY = /^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(.*)$/;
+const WHEEL_METADATA_LIMIT = 64 * 1024 * 1024;
+function uploadTime(file) {
+    const time = file["upload-time"] ? Date.parse(file["upload-time"]) : NaN;
+    return Number.isNaN(time) ? null : new Date(time);
+}
+/** A valid PyPI project name (PEP 508): ASCII letters and digits, with
+ *  `.`, `_` and `-` allowed only between them. */
+const PROJECT_NAME = /^(?:[A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9._-]*[A-Za-z0-9])$/;
+function decoded(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        throw new RegistryError(400, "wardby_bad_request", "malformed percent-encoding in the registry path");
+    }
+}
+function projectName(segment) {
+    const name = decoded(segment);
+    if (!PROJECT_NAME.test(name))
+        throw new RegistryError(400, "wardby_bad_request", "not a valid Python project name");
+    return normalizePypiName(name);
+}
+export function normalizePypiName(name) {
+    return name.toLowerCase().replace(/[-_.]+/g, "-");
+}
+/** Version from a wheel ("name-1.0-py3-none-any.whl") or sdist ("name-1.0.tar.gz") filename. */
+function versionOf(filename) {
+    if (filename.endsWith(".whl"))
+        return filename.split("-")[1] ?? null;
+    const sdist = filename.match(/^.+?-(\d[^-]*)\.(?:tar\.gz|zip)$/);
+    return sdist ? sdist[1] : null;
+}
+export function requiresDist(metadataText) {
+    const names = new Set();
+    for (const line of metadataText.split(/\r?\n/)) {
+        if (!line.startsWith("Requires-Dist:"))
+            continue;
+        const value = line.slice("Requires-Dist:".length).trim();
+        if (/;\s*.*\bextra\s*==/.test(value))
+            continue;
+        const name = value.match(/^([A-Za-z0-9][A-Za-z0-9._-]*)/);
+        if (name)
+            names.add(normalizePypiName(name[1]));
+    }
+    return [...names];
+}
+export const pypiAdapter = {
+    id: "pypi",
+    osvEcosystem: "PyPI",
+    upstreamHosts: ["pypi.org", "files.pythonhosted.org"],
+    collectExclude: [".venv", "venv", "__pycache__"],
+    dependenciesInMetadata: false,
+    parseAllowlistEntry(raw) {
+        const match = raw.trim().match(ENTRY);
+        if (!match)
+            throw new AllowlistEntryError(`"${raw}" is not a valid Python package entry`);
+        const name = normalizePypiName(match[1]);
+        const range = match[2].trim();
+        if (!range)
+            return { name, wildcard: false };
+        if (!validRange(range))
+            throw new AllowlistEntryError(`"${range}" is not a valid PEP 440 specifier`);
+        return { name, wildcard: false, range };
+    },
+    normalizeName: normalizePypiName,
+    satisfies: (version, range) => pepSatisfies(version, range),
+    compareVersions(a, b) {
+        // OSV and PyPI filenames both carry non-canonical spellings ("2.0rc1",
+        // "1.0-post1"); normalize each to PEP 440 before comparing.
+        const left = pepClean(a);
+        const right = pepClean(b);
+        if (!left || !right)
+            throw new Error(`not a PEP 440 version: "${a}" / "${b}"`);
+        return pepCompare(left, right);
+    },
+    route(method, subpath) {
+        if (method !== "GET" && method !== "HEAD")
+            return null;
+        const simple = subpath.match(/^simple\/([^/]+)\/?$/);
+        if (simple)
+            return { kind: "metadata", name: projectName(simple[1]) };
+        const file = subpath.match(/^files\/([^/]+)\/([^/]+)$/);
+        if (!file)
+            return null;
+        const name = projectName(file[1]);
+        const filename = decoded(file[2]);
+        if (filename.endsWith(".metadata")) {
+            return { kind: "file-metadata", name, filename: filename.slice(0, -".metadata".length) };
+        }
+        const version = versionOf(filename);
+        return version ? { kind: "download", name, version, filename } : null;
+    },
+    async fetchMetadata(name, upstream) {
+        const response = await upstream(`${UPSTREAM}${name}/`, { accept: SIMPLE_JSON });
+        if (response.status === 404)
+            throw new RegistryError(404, "wardby_package_not_found", `PyPI has no package "${name}"`);
+        if (!response.ok)
+            throw new RegistryError(502, "wardby_upstream_error", `PyPI returned ${response.status}`);
+        const index = (await response.json());
+        const versions = new Map();
+        for (const file of index.files) {
+            const version = versionOf(file.filename);
+            if (!version || file.yanked)
+                continue;
+            const entry = versions.get(version) ?? { version, dependencies: [], files: [] };
+            entry.files.push({
+                filename: file.filename,
+                version,
+                upstreamUrl: file.url,
+                integrity: file.hashes?.sha256 ? { algorithm: "sha256", hex: file.hashes.sha256 } : null,
+                sizeBytes: file.size ?? null,
+                allowed: file.filename.endsWith(".whl"),
+                publishedAt: uploadTime(file),
+            });
+            versions.set(version, entry);
+        }
+        // Keep only what renderMetadata and resolveFileMetadata read: wheels,
+        // with the PEP 691 file fields pip uses.
+        const raw = {
+            name: index.name,
+            files: index.files
+                .filter((file) => file.filename.endsWith(".whl") && !file.yanked)
+                .map((file) => ({
+                filename: file.filename,
+                url: file.url,
+                ...(file.hashes ? { hashes: file.hashes } : {}),
+                ...(file["upload-time"] ? { "upload-time": file["upload-time"] } : {}),
+                ...(file.size !== undefined ? { size: file.size } : {}),
+                ...(file["core-metadata"] !== undefined ? { "core-metadata": file["core-metadata"] } : {}),
+                ...(file["dist-info-metadata"] !== undefined ? { "dist-info-metadata": file["dist-info-metadata"] } : {}),
+                ...(file["requires-python"] !== undefined ? { "requires-python": file["requires-python"] } : {}),
+            })),
+        };
+        return { name: normalizePypiName(index.name), versions, raw };
+    },
+    renderMetadata(meta, keep, keptFiles, proxyBase) {
+        const index = meta.raw;
+        const files = index.files
+            .filter((file) => file.filename.endsWith(".whl"))
+            .filter((file) => keep.has(versionOf(file.filename) ?? "") && keptFiles.has(file.filename))
+            .map((file) => ({
+            ...file,
+            url: `${proxyBase}files/${encodeURIComponent(meta.name)}/${encodeURIComponent(file.filename)}`,
+        }));
+        return {
+            contentType: SIMPLE_JSON,
+            body: JSON.stringify({ meta: { "api-version": "1.1" }, name: meta.name, files, versions: [...keep] }),
+        };
+    },
+    resolveDownload(route, meta) {
+        return meta.versions.get(route.version)?.files.find((file) => file.filename === route.filename) ?? null;
+    },
+    resolveFileMetadata(route, meta) {
+        const index = meta.raw;
+        const source = index.files.find((file) => file.filename === route.filename);
+        const version = versionOf(route.filename);
+        const declared = source?.["core-metadata"] ?? source?.["dist-info-metadata"];
+        if (!source || !version || !declared || !source.filename.endsWith(".whl"))
+            return null;
+        const sha256 = typeof declared === "object" ? declared.sha256 : undefined;
+        return {
+            filename: `${route.filename}.metadata`,
+            version,
+            upstreamUrl: `${source.url}.metadata`,
+            integrity: sha256 ? { algorithm: "sha256", hex: sha256 } : null,
+            sizeBytes: null,
+            allowed: true,
+            // The metadata file is as old as the wheel it describes.
+            publishedAt: uploadTime(source),
+        };
+    },
+    async dependenciesFromFile(route, body) {
+        if (route.kind === "file-metadata")
+            return requiresDist(new TextDecoder().decode(body));
+        if (!route.filename.endsWith(".whl") || body.byteLength > WHEEL_METADATA_LIMIT)
+            return [];
+        const entries = unzipSync(body, { filter: (file) => /\.dist-info\/METADATA$/.test(file.name) });
+        const metadata = Object.values(entries)[0];
+        return metadata ? requiresDist(strFromU8(metadata)) : [];
+    },
+    workerConfig({ registryUrl, token, cacheDir }) {
+        const index = new URL("simple/", registryUrl);
+        index.username = "wardby";
+        index.password = token;
+        return {
+            env: {
+                PIP_INDEX_URL: index.toString(),
+                PIP_TRUSTED_HOST: index.hostname,
+                PIP_ONLY_BINARY: ":all:",
+                PIP_CACHE_DIR: cacheDir,
+                PIP_DISABLE_PIP_VERSION_CHECK: "1",
+                PIP_NO_INPUT: "1",
+            },
+            files: [],
+        };
+    },
+};

package/dist/coding/registry/report.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The one summary of a run's RegistryFetch rows, shared by get_run and the
+ * coding executor's PR-body report so both deduplicate identically: served
+ * packages collapse on ecosystem + name + version (a retried download is one
+ * package), refusals on ecosystem + name + reason.
+ */
+export interface RegistryFetchRow {
+    ecosystem: string;
+    name: string;
+    version: string | null;
+    outcome: string;
+    reason: string | null;
+    sizeBytes: number | null;
+    /** `-/plan` for a refusal a lockfile plan recorded (see PLAN_FETCH_FILENAME). */
+    filename?: string | null;
+}
+/** The `filename` a lockfile plan records its refusals under. */
+export declare const PLAN_REFUSAL_FILENAME = "-/plan";
+/** Distinct refusals lockfile plans recorded (ecosystem + name + version +
+ *  reason), however often the lockfile was planned. */
+export declare function countPlanRefusals(rows: readonly RegistryFetchRow[]): number;
+export interface RegistryPackageSummary {
+    ecosystem: string;
+    name: string;
+    version: string;
+    /** Bytes served (RegistryFetch.sizeBytes); null when not recorded. */
+    size: number | null;
+}
+export interface RegistryRefusalSummary {
+    ecosystem: string;
+    name: string;
+    reason: string;
+}
+export declare function summarizeRegistryFetches(rows: readonly RegistryFetchRow[]): {
+    packages: RegistryPackageSummary[];
+    packageRefusals: RegistryRefusalSummary[];
+};

package/dist/coding/registry/report.js

@@ -0,0 +1,31 @@
+/** The `filename` a lockfile plan records its refusals under. */
+export const PLAN_REFUSAL_FILENAME = "-/plan";
+/** Distinct refusals lockfile plans recorded (ecosystem + name + version +
+ *  reason), however often the lockfile was planned. */
+export function countPlanRefusals(rows) {
+    const keys = new Set();
+    for (const row of rows) {
+        if (row.outcome !== "refused" || row.filename !== PLAN_REFUSAL_FILENAME)
+            continue;
+        keys.add(`${row.ecosystem}\0${row.name}\0${row.version ?? ""}\0${row.reason ?? ""}`);
+    }
+    return keys.size;
+}
+export function summarizeRegistryFetches(rows) {
+    const packages = new Map();
+    const refusals = new Map();
+    for (const row of rows) {
+        if (row.outcome === "served" && row.version) {
+            const key = `${row.ecosystem}\0${row.name}\0${row.version}`;
+            if (!packages.has(key))
+                packages.set(key, { ecosystem: row.ecosystem, name: row.name, version: row.version, size: row.sizeBytes });
+        }
+        else if (row.outcome === "refused") {
+            const reason = row.reason ?? "refused";
+            const key = `${row.ecosystem}\0${row.name}\0${reason}`;
+            if (!refusals.has(key))
+                refusals.set(key, { ecosystem: row.ecosystem, name: row.name, reason });
+        }
+    }
+    return { packages: [...packages.values()], packageRefusals: [...refusals.values()] };
+}

package/dist/coding/registry/token.d.ts

@@ -0,0 +1,4 @@
+/** A one-way, registry-only token for npm and pip. The proxy stores its hash and
+ *  accepts it only on /registry/ routes, so package tools never hold the model
+ *  capability. */
+export declare function deriveRegistryToken(capability: string): string;

package/dist/coding/registry/token.js

@@ -0,0 +1,7 @@
+import { createHash } from "node:crypto";
+/** A one-way, registry-only token for npm and pip. The proxy stores its hash and
+ *  accepts it only on /registry/ routes, so package tools never hold the model
+ *  capability. */
+export function deriveRegistryToken(capability) {
+    return `rrg_${createHash("sha256").update("wardby-registry\0").update(capability).digest("base64url")}`;
+}

package/dist/coding/registry/types.d.ts

@@ -0,0 +1,286 @@
+/**
+ * Shared types for the coding package registry: the adapter contract each
+ * ecosystem (npm, PyPI, later Composer/RubyGems/Go) implements, and the
+ * allowlist entry shape adapters parse into. Everything security-relevant
+ * (allowance checks, version filtering, streaming, recording) lives in the
+ * registry core, never in an adapter, so a new adapter cannot weaken a
+ * safeguard by omission.
+ */
+/**
+ * "npm", "pypi", later "composer", "rubygems", "go". Used as the allowlist
+ * key, the route segment (/registry/<id>/), and RegistryFetch.ecosystem.
+ */
+export type EcosystemId = string;
+export interface AllowlistEntry {
+    /** Normalized name, or a scope prefix when `wildcard` is true ("@heroui/"). */
+    name: string;
+    wildcard: boolean;
+    /** Optional version range in this ecosystem's syntax. */
+    range?: string;
+}
+export declare class AllowlistEntryError extends Error {
+}
+export declare class RegistryError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface Integrity {
+    algorithm: "sha512" | "sha384" | "sha256" | "sha1";
+    /** Hex-encoded digest. */
+    hex: string;
+}
+export interface FileRef {
+    filename: string;
+    version: string;
+    upstreamUrl: string;
+    /** Null when the ecosystem publishes no checksum (common for Composer archives). */
+    integrity: Integrity | null;
+    sizeBytes: number | null;
+    /** False for files the ecosystem's safeguards exclude, e.g. PyPI sdists. */
+    allowed: boolean;
+    /** When this file was published; null means unknown and is treated as too
+     *  new. The minimum release age applies per file: a PyPI release can gain
+     *  a new wheel long after its first upload. For npm every version has one
+     *  immutable tarball, so this is the version's publish time. */
+    publishedAt: Date | null;
+}
+/** One declared dependency edge: the package it installs and the range
+ *  it asks for, in the ecosystem's syntax. `"*"` means any version (also
+ *  used for a spec that is not a range, such as a dist-tag). */
+export interface DependencySpec {
+    name: string;
+    range: string;
+}
+export interface VersionInfo {
+    version: string;
+    /** Dependency names (normalized). Empty when discovered from files instead. */
+    dependencies: readonly string[];
+    /** The same dependencies with their declared ranges, for the range-aware
+     *  graph walk. Adapters with `dependenciesInMetadata` set should fill it;
+     *  when omitted, each name counts as `"*"`. */
+    dependencySpecs?: readonly DependencySpec[];
+    files: readonly FileRef[];
+}
+export interface PackageMetadata {
+    name: string;
+    /** Keyed by version string. */
+    versions: ReadonlyMap<string, VersionInfo>;
+    /** Adapter-private data renderMetadata (and resolveFileMetadata) read:
+     *  never the upstream document itself, only what those need of it.
+     *  `undefined` when the adapter supports metadata without render data
+     *  (`fetchMetadata` without `render`) and it was fetched that way. */
+    raw?: unknown;
+    /** Approximate bytes this object retains, for the metadata cache's byte
+     *  budget. The core estimates it when an adapter leaves it out. */
+    approxBytes?: number;
+}
+export interface FetchMetadataOptions {
+    /** Also keep what renderMetadata needs. Without it, an adapter may omit
+     *  `raw` (npm does), since the graph walk, the version filter and
+     *  downloads read only `versions`. */
+    render?: boolean;
+}
+export interface MetadataRoute {
+    kind: "metadata";
+    name: string;
+}
+export interface DownloadRoute {
+    kind: "download";
+    name: string;
+    version: string;
+    filename: string;
+}
+/** PEP 658 metadata file for one wheel. */
+export interface FileMetadataRoute {
+    kind: "file-metadata";
+    name: string;
+    filename: string;
+}
+export type RegistryRoute = MetadataRoute | DownloadRoute | FileMetadataRoute;
+export interface RenderedDocument {
+    contentType: string;
+    body: string;
+}
+/** The pinned upstream client: HTTPS only, adapter's upstreamHosts only,
+ *  no redirects, no private addresses. `acceptEncoding: "gzip"` asks for a
+ *  compressed body, which the caller then decompresses itself (the pinned
+ *  client never does). */
+export type UpstreamFetch = (url: string, init?: {
+    method?: "GET" | "POST";
+    body?: string;
+    accept?: string;
+    acceptEncoding?: "gzip";
+    signal?: AbortSignal;
+}) => Promise<Response>;
+/** One declared dependency as a lockfile or registry manifest writes it:
+ *  the folder it installs into (`key`, an alias's own name), the registry
+ *  package it installs (`name`, the alias target) and the range it asks
+ *  for (`"*"` for a dist-tag or empty spec). */
+export interface DeclaredDependency {
+    key: string;
+    name: string;
+    range: string;
+}
+/** One installed package a lockfile claims, where it installs it. None of
+ *  it is trusted: the plan verifies every registry entry against the
+ *  registry itself. */
+export interface LockfileEntry {
+    /** Where the lockfile installs it (npm: `node_modules/a/node_modules/b`). Unique. */
+    path: string;
+    /** The registry package (an alias's target), as the lockfile claims it. */
+    name: string;
+    version: string;
+    /** The lockfile's integrity string, or null when it records none. */
+    integrity: string | null;
+    /** `registry`: fetched from the registry (verified, then approved or
+     *  refused). `bundled`: shipped inside its parent's own tarball, never
+     *  fetched, so neither. `unsupported`: fetched from somewhere other than
+     *  the registry (git, a URL, a path) or unreadable; always refused. */
+    kind: "registry" | "bundled" | "unsupported";
+    /** Why an `unsupported` entry is refused. */
+    unsupportedReason?: string;
+}
+/** A parsed lockfile: its entries, the projects whose declared
+ *  dependencies are where reachability starts (the root, workspaces), and
+ *  the client's own rule for which entry a declared dependency uses. */
+export interface ParsedLockfile {
+    entries: readonly LockfileEntry[];
+    projects: readonly {
+        path: string;
+        dependencies: readonly DeclaredDependency[];
+    }[];
+    /** The entry that `key`, declared by the package at `fromPath`, resolves
+     *  to (npm: the nearest ancestor `node_modules/<key>`), or undefined
+     *  (not installed, or a local project). */
+    resolve(fromPath: string, key: string): LockfileEntry | undefined;
+}
+/** Immutable facts about one published version, read from the registry
+ *  itself (never from a lockfile): stored once, reused forever. */
+export interface VersionFact {
+    name: string;
+    version: string;
+    /** Null only while being assembled: a fact is stored only with a publish time. */
+    publishedAt: Date | null;
+    /** The registry's integrity string (npm: `dist.integrity`, an SRI). */
+    integrity: string;
+    downloadUrl: string;
+    /** Every registry dependency the version declares (npm: dependencies,
+     *  optionalDependencies and peerDependencies, aliases resolved). */
+    dependencies: readonly DeclaredDependency[];
+}
+/** An ecosystem's lockfile verification hooks (`POST /-/plan`): parsing and
+ *  registry reads only. Every decision (integrity, edges, reachability,
+ *  release age, advisories) is the registry core's. */
+export interface LockfilePlanSupport {
+    /** Parse a lockfile. Throws a RegistryError for one it cannot verify
+     *  (unsupported version: 400 `wardby_lockfile_unsupported`; invalid:
+     *  400 `wardby_bad_request`; more than `maxEntries` entries: 413
+     *  `wardby_lockfile_too_large`). `proxyRegistryUrl` is the proxy's own
+     *  route for this ecosystem, which a lockfile written through it records
+     *  as the download source. */
+    parse(body: string, options: {
+        maxEntries: number;
+        proxyRegistryUrl: string;
+    }): ParsedLockfile;
+    /** The registry's own record of one version, without its publish time;
+     *  null when the registry has no such version. */
+    fetchVersionFact(name: string, version: string, upstream: UpstreamFetch, signal?: AbortSignal): Promise<VersionFact | null>;
+    /** Publish times of `versions` of one package, read by streaming the
+     *  package's full document without ever holding it. A version the
+     *  registry has no time for is absent from the result. */
+    fetchPublishTimes(name: string, versions: readonly string[], upstream: UpstreamFetch, options: {
+        maxBytes: number;
+        signal: AbortSignal;
+    }): Promise<Map<string, Date>>;
+    /** Whether a dependency declared as `range` accepts `version`, as the
+     *  client itself decides it when it reuses a locked version. */
+    edgeSatisfies(version: string, range: string): boolean;
+}
+export interface WorkerConfigInput {
+    /** e.g. "http://wardby-proxy:8787/registry/npm/" */
+    registryUrl: string;
+    /** The derived registry-only token (`rrg_…`), never the run capability.
+     *  Written only under cacheDir, never elsewhere. */
+    token: string;
+    /** e.g. "/workspace/.cache/npm"; always inside a collection-excluded folder. */
+    cacheDir: string;
+}
+export interface WorkerConfig {
+    env: Readonly<Record<string, string>>;
+    /** Files the driver writes before the agent starts; paths must be under cacheDir. */
+    files: readonly {
+        path: string;
+        content: string;
+        mode: number;
+    }[];
+}
+export interface RegistryAdapter {
+    readonly id: EcosystemId;
+    /** OSV ecosystem name, e.g. "npm", "PyPI", "Packagist", "RubyGems", "Go". */
+    readonly osvEcosystem: string;
+    /** Upstream hosts this adapter may reach; added to the pinned-fetch allowlist. */
+    readonly upstreamHosts: readonly string[];
+    /** Extra folder names skipped at collection, e.g. "vendor" for Composer. */
+    readonly collectExclude: readonly string[];
+    /** Whether fetchMetadata's VersionInfo.dependencies is complete (npm's
+     *  packuments carry every version's dependencies). When true, the core
+     *  may resolve a run's approved dependency graph from metadata alone,
+     *  on demand, before refusing a name (a lockfile install requests
+     *  tarballs without first requesting each parent's metadata). False for
+     *  ecosystems whose indexes omit dependencies (PyPI), where such a walk
+     *  would only make upstream calls and find nothing. */
+    readonly dependenciesInMetadata: boolean;
+    /** Lockfile names this ecosystem's client writes, and a rewrite of the proxy download URLs it records in one back to
+     *  public URLs, applied before the workspace is collected (lockfiles.ts). Omitted when the client records none. */
+    readonly lockfiles?: {
+        names: readonly string[];
+        normalize(content: string, registryUrl: string): string;
+    };
+    /** Lockfile verification (`POST /registry/<id>/-/plan`); omitted when the
+     *  ecosystem has none. */
+    readonly lockfilePlan?: LockfilePlanSupport;
+    /** Parse one allowlist entry in this ecosystem's syntax. Throws an
+     *  AllowlistEntryError with a user-facing message if it is invalid. */
+    parseAllowlistEntry(raw: string): AllowlistEntry;
+    /** Canonical name used for every comparison (npm: the name exactly as
+     *  written, since npm names are case-sensitive; PyPI: PEP 503
+     *  normalization). */
+    normalizeName(name: string): string;
+    /** Whether `version` satisfies `range` in this ecosystem's syntax
+     *  (npm semver ranges, PEP 440 specifiers). */
+    satisfies(version: string, range: string): boolean;
+    /** Total order over this ecosystem's version strings (semver for npm,
+     *  PEP 440 for PyPI, normalizing non-canonical spellings first), used to
+     *  evaluate OSV advisory ranges. Throws on a version it cannot parse; the
+     *  audit treats that as affected (fail closed). */
+    compareVersions(a: string, b: string): number;
+    /** Classify a request under /registry/<id>/, or null for 404. Throws a
+     *  400 `wardby_bad_request` RegistryError for a malformed path (bad
+     *  percent-encoding or an invalid package name); the core records it. */
+    route(method: string, subpath: string, headers: Headers): RegistryRoute | null;
+    /** Fetch and parse upstream metadata for one package, keeping only the
+     *  fields the proxy reads: nothing returned may reference the parsed
+     *  upstream document, which can be tens of MB. */
+    fetchMetadata(name: string, upstream: UpstreamFetch, options?: FetchMetadataOptions): Promise<PackageMetadata>;
+    /** Build the client-facing metadata document containing only `keep`
+     *  versions and, of their files, only the filenames in `keptFiles` (the
+     *  core's per-file release-age filter), with every download link
+     *  rewritten to a proxy route. */
+    renderMetadata(meta: PackageMetadata, keep: ReadonlySet<string>, keptFiles: ReadonlySet<string>, proxyBase: string): RenderedDocument;
+    /** Map a download route to a file in metadata the proxy fetched itself.
+     *  Returns null if the route names no known file. */
+    resolveDownload(route: DownloadRoute, meta: PackageMetadata): FileRef | null;
+    /** For ecosystems whose indexes omit dependencies (PyPI): dependency
+     *  names read from a served file or its metadata file. Omitted when
+     *  VersionInfo.dependencies is already complete (npm). */
+    dependenciesFromFile?(route: DownloadRoute | FileMetadataRoute, body: Uint8Array): Promise<string[]>;
+    /** Map a file-metadata route (PEP 658) to the file it describes, from
+     *  metadata the proxy fetched itself. Returns null if the route names no
+     *  known file. */
+    resolveFileMetadata?(route: FileMetadataRoute, meta: PackageMetadata): FileRef | null;
+    /** Environment variables and files the driver writes so the package
+     *  manager uses the proxy, authenticates, keeps caches under cacheDir,
+     *  and disables install-time code where the client allows it. */
+    workerConfig(input: WorkerConfigInput): WorkerConfig;
+}

package/dist/coding/registry/types.js

@@ -0,0 +1,19 @@
+/**
+ * Shared types for the coding package registry: the adapter contract each
+ * ecosystem (npm, PyPI, later Composer/RubyGems/Go) implements, and the
+ * allowlist entry shape adapters parse into. Everything security-relevant
+ * (allowance checks, version filtering, streaming, recording) lives in the
+ * registry core, never in an adapter, so a new adapter cannot weaken a
+ * safeguard by omission.
+ */
+export class AllowlistEntryError extends Error {
+}
+export class RegistryError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}

package/dist/coding/registry/worker-config.d.ts

@@ -0,0 +1,14 @@
+/** The URL the worker's package manager is pointed at for one ecosystem. */
+export declare function registryUrlFor(proxyBaseUrl: string, ecosystem: string): string;
+export declare function registryWorkerSetup(input: {
+    proxyBaseUrl: string;
+    capability: string;
+    cacheRoot: string;
+}): {
+    env: Record<string, string>;
+    files: {
+        path: string;
+        content: string;
+        mode: number;
+    }[];
+};

package/dist/coding/registry/worker-config.js

@@ -0,0 +1,31 @@
+/**
+ * Builds the full worker environment/file setup for every registry adapter
+ * at once, from the run's derived registry-only token -- never the run
+ * capability itself. The driver calls this once per coding run and applies
+ * the result before the agent starts.
+ */
+import { REGISTRY_ADAPTERS } from "./adapters.js";
+import { deriveRegistryToken } from "./token.js";
+/** The URL the worker's package manager is pointed at for one ecosystem. */
+export function registryUrlFor(proxyBaseUrl, ecosystem) {
+    return `${proxyBaseUrl.replace(/\/$/, "")}/registry/${ecosystem}/`;
+}
+export function registryWorkerSetup(input) {
+    const token = deriveRegistryToken(input.capability);
+    const env = {};
+    const files = [];
+    for (const adapter of REGISTRY_ADAPTERS.values()) {
+        const config = adapter.workerConfig({
+            registryUrl: registryUrlFor(input.proxyBaseUrl, adapter.id),
+            token,
+            cacheDir: `${input.cacheRoot}/${adapter.id}`,
+        });
+        Object.assign(env, config.env);
+        for (const file of config.files) {
+            if (!file.path.startsWith(`${input.cacheRoot}/`))
+                throw new Error("registry_worker_file_outside_cache");
+            files.push(file);
+        }
+    }
+    return { env, files };
+}

package/dist/coding/services/builtins.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The services wardby ships in its catalog. Migration
+ * 20260927050000_coding_run_services seeds exactly these rows
+ * (builtins.database.test.ts holds the two together); a later release changes
+ * them with a new migration and a change here.
+ *
+ * Each image is the official Docker Hub image pinned by its multi-architecture
+ * index digest, resolved with
+ * `docker buildx imagetools inspect docker.io/library/<name>:<tag>`.
+ *
+ * A sidecar runs as the run pod's non-root uid with a read-only root
+ * filesystem, so each entry names every directory its image writes to: the
+ * data directory and, for the databases, the socket directory and /tmp (the
+ * official entrypoints write an nss_wrapper passwd file there for an arbitrary
+ * uid). Postgres keeps PGDATA one level below its volume so the entrypoint can
+ * create it owned by that uid. Readiness probes TCP on 127.0.0.1, not the Unix
+ * socket: both database entrypoints first run a temporary socket-only server to
+ * initialize, and only the final server listens on TCP. Variables use
+ * 127.0.0.1 rather than localhost so no client tries the IPv6 loopback first.
+ */
+import type { CodingServiceDefinition } from "./catalog.js";
+export declare const BUILTIN_CODING_SERVICES: readonly CodingServiceDefinition[];