@wardby/cli 0.2.1 → 0.3.0

package/dist/coding/registry/allowlist.js

@@ -0,0 +1,28 @@
+/**
+ * The per-agent package allowlist and policy model: parsing raw allowlist
+ * strings (via each ecosystem's adapter) into `AllowlistEntry` values, and
+ * matching a normalized package name against them.
+ */
+import { z } from "zod";
+export const DEFAULT_MIN_RELEASE_AGE_DAYS = 3;
+const PolicySchema = z
+    .object({ minReleaseAgeDays: z.number().int().min(0).max(30).default(DEFAULT_MIN_RELEASE_AGE_DAYS) })
+    .strict();
+export function resolvePolicy(value) {
+    return PolicySchema.parse(value ?? {});
+}
+export function parseAllowlist(allowlist, adapters) {
+    const parsed = new Map();
+    for (const [ecosystem, entries] of Object.entries(allowlist)) {
+        const adapter = adapters.get(ecosystem);
+        if (!adapter)
+            throw new Error(`unknown package ecosystem "${ecosystem}"`);
+        parsed.set(ecosystem, entries.map((entry) => adapter.parseAllowlistEntry(entry)));
+    }
+    return parsed;
+}
+export function matchRoot(entries, normalizedName) {
+    return entries.find((entry) => entry.wildcard
+        ? normalizedName.startsWith(entry.name) && normalizedName.length > entry.name.length
+        : entry.name === normalizedName);
+}

package/dist/coding/registry/json-scan.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A streaming scan for one top-level member of a JSON object document,
+ * without ever holding the document: only the wanted member's value text is
+ * kept (bounded), and every other value, however large, is skipped as it
+ * streams past. Used to read an npm packument's `time` (per-version publish
+ * times), which comes after `versions` and can follow tens of MB of it.
+ *
+ * It is a tokenizer, not a validator: it tracks strings, escapes and
+ * nesting depth, which is all that locating a top-level member needs. The
+ * captured value is then parsed with JSON.parse, so a malformed value
+ * throws there. A document that is not an object, or that ends before the
+ * member closes, yields null.
+ */
+export declare class JsonMemberTooLarge extends Error {
+}
+export declare class TopLevelMemberScanner {
+    private readonly wanted;
+    private readonly maxValueLength;
+    private depth;
+    private inString;
+    private escape;
+    /** At depth 1, the next string is a key. */
+    private expectKey;
+    private collectingKey;
+    private key;
+    private lastKey;
+    /** After `"<wanted>":`, waiting for the value's first character. */
+    private pending;
+    private capturing;
+    private captured;
+    private capturedLength;
+    private finished;
+    private result;
+    private started;
+    constructor(wanted: string, maxValueLength: number);
+    /** True once the member was captured (or proven absent or not an
+     *  object), so the caller may stop reading. */
+    get done(): boolean;
+    /** The member's value, parsed; undefined while scanning or when absent. */
+    get value(): unknown;
+    /** Feeds the next decoded text. Throws JsonMemberTooLarge when the
+     *  member's value exceeds its bound. */
+    push(text: string): void;
+    private appendKey;
+    private capture;
+    private finish;
+}
+/** Reads `stream` (UTF-8 JSON) until the top-level member `wanted` has
+ *  been captured, then cancels the rest. Returns its parsed value, or
+ *  undefined when the document has no such object-valued member. At most
+ *  `maxBytes` of the stream are read; more throws JsonMemberTooLarge. */
+export declare function scanTopLevelMember(stream: ReadableStream<Uint8Array>, wanted: string, limits: {
+    maxBytes: number;
+    maxValueLength: number;
+}): Promise<unknown>;

package/dist/coding/registry/json-scan.js

@@ -0,0 +1,191 @@
+/**
+ * A streaming scan for one top-level member of a JSON object document,
+ * without ever holding the document: only the wanted member's value text is
+ * kept (bounded), and every other value, however large, is skipped as it
+ * streams past. Used to read an npm packument's `time` (per-version publish
+ * times), which comes after `versions` and can follow tens of MB of it.
+ *
+ * It is a tokenizer, not a validator: it tracks strings, escapes and
+ * nesting depth, which is all that locating a top-level member needs. The
+ * captured value is then parsed with JSON.parse, so a malformed value
+ * throws there. A document that is not an object, or that ends before the
+ * member closes, yields null.
+ */
+/** Longest top-level key compared; a longer one cannot be the wanted key. */
+const MAX_KEY_LENGTH = 256;
+export class JsonMemberTooLarge extends Error {
+}
+export class TopLevelMemberScanner {
+    wanted;
+    maxValueLength;
+    depth = 0;
+    inString = false;
+    escape = false;
+    /** At depth 1, the next string is a key. */
+    expectKey = false;
+    collectingKey = false;
+    key = "";
+    lastKey;
+    /** After `"<wanted>":`, waiting for the value's first character. */
+    pending = false;
+    capturing = false;
+    captured = [];
+    capturedLength = 0;
+    finished = false;
+    result = undefined;
+    started = false;
+    constructor(wanted, maxValueLength) {
+        this.wanted = wanted;
+        this.maxValueLength = maxValueLength;
+    }
+    /** True once the member was captured (or proven absent or not an
+     *  object), so the caller may stop reading. */
+    get done() {
+        return this.finished;
+    }
+    /** The member's value, parsed; undefined while scanning or when absent. */
+    get value() {
+        return this.result;
+    }
+    /** Feeds the next decoded text. Throws JsonMemberTooLarge when the
+     *  member's value exceeds its bound. */
+    push(text) {
+        if (this.finished)
+            return;
+        let segmentStart = this.capturing ? 0 : -1;
+        const length = text.length;
+        let i = 0;
+        while (i < length) {
+            if (this.inString) {
+                if (this.escape) {
+                    this.escape = false;
+                    if (this.collectingKey)
+                        this.appendKey(text[i]);
+                    i += 1;
+                    continue;
+                }
+                // Skip ahead to the next quote or backslash: the bulk of a
+                // packument is string content, never looked at char by char.
+                const quote = text.indexOf('"', i);
+                const backslash = text.indexOf("\\", i);
+                const stop = quote < 0 ? backslash : backslash < 0 ? quote : Math.min(quote, backslash);
+                if (stop < 0) {
+                    if (this.collectingKey)
+                        this.appendKey(text.slice(i));
+                    break;
+                }
+                if (this.collectingKey)
+                    this.appendKey(text.slice(i, stop));
+                if (stop === backslash) {
+                    this.escape = true;
+                    if (this.collectingKey)
+                        this.appendKey("\\");
+                    i = stop + 1;
+                    continue;
+                }
+                this.inString = false;
+                if (this.collectingKey) {
+                    this.collectingKey = false;
+                    this.lastKey = this.key;
+                }
+                i = stop + 1;
+                continue;
+            }
+            const c = text[i];
+            if (c === " " || c === "\n" || c === "\r" || c === "\t") {
+                i += 1;
+                continue;
+            }
+            if (!this.started) {
+                this.started = true;
+                if (c !== "{")
+                    return this.finish(undefined);
+            }
+            if (this.pending) {
+                this.pending = false;
+                if (c !== "{")
+                    return this.finish(undefined);
+                this.capturing = true;
+                segmentStart = i;
+            }
+            if (c === '"') {
+                this.inString = true;
+                if (this.depth === 1 && this.expectKey) {
+                    this.collectingKey = true;
+                    this.key = "";
+                    this.expectKey = false;
+                }
+            }
+            else if (c === "{" || c === "[") {
+                this.depth += 1;
+                if (this.depth === 1)
+                    this.expectKey = true;
+            }
+            else if (c === "}" || c === "]") {
+                this.depth -= 1;
+                if (this.capturing && this.depth === 1) {
+                    this.capture(text.slice(segmentStart, i + 1));
+                    return this.finish(JSON.parse(this.captured.join("")));
+                }
+                if (this.depth === 0)
+                    return this.finish(undefined);
+            }
+            else if (c === ":") {
+                if (this.depth === 1 && this.lastKey === this.wanted)
+                    this.pending = true;
+            }
+            else if (c === ",") {
+                if (this.depth === 1) {
+                    this.expectKey = true;
+                    this.lastKey = undefined;
+                }
+            }
+            i += 1;
+        }
+        if (this.capturing && segmentStart >= 0)
+            this.capture(text.slice(segmentStart));
+    }
+    appendKey(part) {
+        if (this.key.length <= MAX_KEY_LENGTH)
+            this.key += part.slice(0, MAX_KEY_LENGTH + 1 - this.key.length);
+    }
+    capture(part) {
+        this.capturedLength += part.length;
+        if (this.capturedLength > this.maxValueLength)
+            throw new JsonMemberTooLarge(`"${this.wanted}" is too large`);
+        this.captured.push(part);
+    }
+    finish(value) {
+        this.finished = true;
+        this.result = value;
+        this.captured = [];
+    }
+}
+/** Reads `stream` (UTF-8 JSON) until the top-level member `wanted` has
+ *  been captured, then cancels the rest. Returns its parsed value, or
+ *  undefined when the document has no such object-valued member. At most
+ *  `maxBytes` of the stream are read; more throws JsonMemberTooLarge. */
+export async function scanTopLevelMember(stream, wanted, limits) {
+    const scanner = new TopLevelMemberScanner(wanted, limits.maxValueLength);
+    const decoder = new TextDecoder("utf-8");
+    const reader = stream.getReader();
+    let bytes = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                scanner.push(decoder.decode());
+                return scanner.value;
+            }
+            bytes += value.byteLength;
+            if (bytes > limits.maxBytes)
+                throw new JsonMemberTooLarge(`the document is larger than ${limits.maxBytes} bytes`);
+            scanner.push(decoder.decode(value, { stream: true }));
+            if (scanner.done)
+                return scanner.value;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}

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

@@ -0,0 +1,6 @@
+/** Normalises every recognised lockfile under `workspace`; returns the
+ *  workspace-relative paths it rewrote, sorted. */
+export declare function normalizeRegistryLockfiles(input: {
+    workspace: string;
+    proxyBaseUrl: string;
+}): Promise<string[]>;

package/dist/coding/registry/lockfiles.js

@@ -0,0 +1,89 @@
+/**
+ * Rewrites the proxy download URLs a package manager records in lockfiles
+ * back to public ones, for every adapter with a `lockfiles` hook. The driver
+ * runs this on the workspace before it is collected, so a committed lockfile
+ * never points at the sandbox-only proxy host.
+ *
+ * Best effort by design: a file that cannot be read or written safely is
+ * skipped, never a reason to fail the run. The walk never follows symlinks
+ * and skips the folders collection excludes by name (dependency and cache
+ * folders), which are never sent back anyway.
+ */
+import { constants } from "node:fs";
+import { open, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { BUILTIN_COLLECT_EXCLUDE_NAMES } from "../collect-exclude.js";
+import { REGISTRY_ADAPTERS } from "./adapters.js";
+import { registryUrlFor } from "./worker-config.js";
+const MAX_LOCKFILE_BYTES = 64 * 1024 * 1024;
+const MAX_DEPTH = 32;
+const SKIPPED_DIRECTORIES = new Set([...BUILTIN_COLLECT_EXCLUDE_NAMES, ".git"]);
+/** Rewrites one file in place through a single descriptor (no symlinks, no
+ *  path re-resolution between the checks and the write). Returns whether it
+ *  changed; any failure leaves the file as it was found or skips it. */
+async function normalizeFile(path, normalize) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDWR | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    }
+    catch {
+        return false;
+    }
+    try {
+        const metadata = await file.stat();
+        if (!metadata.isFile() || metadata.size > MAX_LOCKFILE_BYTES)
+            return false;
+        const before = (await file.readFile()).toString("utf8");
+        const after = normalize(before);
+        if (after === before)
+            return false;
+        await file.truncate(0);
+        await file.write(after, 0, "utf8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Normalises every recognised lockfile under `workspace`; returns the
+ *  workspace-relative paths it rewrote, sorted. */
+export async function normalizeRegistryLockfiles(input) {
+    const byName = new Map();
+    for (const adapter of REGISTRY_ADAPTERS.values()) {
+        const lockfiles = adapter.lockfiles;
+        if (!lockfiles)
+            continue;
+        const registryUrl = registryUrlFor(input.proxyBaseUrl, adapter.id);
+        for (const name of lockfiles.names)
+            byName.set(name, (content) => lockfiles.normalize(content, registryUrl));
+    }
+    const rewritten = [];
+    const walk = async (relative, depth) => {
+        let entries;
+        try {
+            entries = await readdir(join(input.workspace, relative), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = relative ? `${relative}/${entry.name}` : entry.name;
+            // Dirent types come from lstat semantics: a symlink is neither a directory nor a file here.
+            if (entry.isDirectory()) {
+                if (depth < MAX_DEPTH && !SKIPPED_DIRECTORIES.has(entry.name))
+                    await walk(path, depth + 1);
+            }
+            else if (entry.isFile()) {
+                const normalize = byName.get(entry.name);
+                if (normalize && (await normalizeFile(join(input.workspace, path), normalize)))
+                    rewritten.push(path);
+            }
+        }
+    };
+    if (byName.size > 0)
+        await walk("", 0);
+    return rewritten.sort();
+}

package/dist/coding/registry/npm-lockfile.d.ts

@@ -0,0 +1,9 @@
+/** Same shape as the adapter's allowlist name check (scoped names are lower case). */
+export declare const PACKAGE_NAME: RegExp;
+/** `https://registry.npmjs.org/@scope/pkg/-/pkg-1.0.0.tgz` */
+export declare function publicNpmTarballUrl(name: string, version: string): string;
+export declare function normalizeNpmLockfile(content: string, registryUrl: string): string;
+export declare const npmLockfiles: {
+    readonly names: readonly ["package-lock.json", "npm-shrinkwrap.json"];
+    readonly normalize: typeof normalizeNpmLockfile;
+};

package/dist/coding/registry/npm-lockfile.js

@@ -0,0 +1,73 @@
+/**
+ * npm lockfile normaliser. The npm adapter serves metadata whose tarball
+ * links point at the proxy, so `npm install` in the worker records those
+ * proxy URLs as `resolved` in package-lock.json / npm-shrinkwrap.json. They
+ * only resolve inside the sandbox, so before the workspace is collected every
+ * `resolved` value under the proxy's npm route is rewritten to the canonical
+ * public registry URL for the same package and version. `integrity` is left
+ * as is: it covers the same tarball bytes. Only the matched values change;
+ * the rest of the file stays byte-for-byte identical (no JSON round trip).
+ *
+ * Kept free of imports from npm.ts, which imports this module.
+ */
+import semver from "semver";
+const PUBLIC_REGISTRY = "https://registry.npmjs.org/";
+/** Same shape as the adapter's allowlist name check (scoped names are lower case). */
+export const PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*|[A-Za-z0-9-~][A-Za-z0-9-._~]*)$/;
+/** A `"resolved": "<value>"` pair whose value has no JSON escapes. */
+const RESOLVED = /("resolved"\s*:\s*")([^"\\]*)(")/g;
+function decode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null;
+    }
+}
+function unscoped(name) {
+    return name.slice(name.indexOf("/") + 1);
+}
+/** The package and version a path under the proxy's npm base downloads:
+ *  `-/tarball/<encoded name>/<version>` (the proxy's own route) or the
+ *  standard `<name>/-/<unscoped>-<version>.tgz`, with the scope separator
+ *  literal or percent-encoded. Null for anything else. */
+function parseProxyPath(path) {
+    let name;
+    let version;
+    const own = path.match(/^-\/tarball\/([^/]+)\/([^/]+)$/);
+    if (own) {
+        name = decode(own[1]);
+        version = decode(own[2]);
+    }
+    else {
+        const standard = path.match(/^(.+)\/-\/([^/]+)\.tgz$/);
+        if (!standard)
+            return null;
+        name = decode(standard[1]);
+        const file = decode(standard[2]);
+        if (!name || !file)
+            return null;
+        const prefix = `${unscoped(name)}-`;
+        version = file.startsWith(prefix) ? file.slice(prefix.length) : null;
+    }
+    if (!name || !version || !PACKAGE_NAME.test(name) || semver.valid(version) !== version)
+        return null;
+    return { name, version };
+}
+/** `https://registry.npmjs.org/@scope/pkg/-/pkg-1.0.0.tgz` */
+export function publicNpmTarballUrl(name, version) {
+    return `${PUBLIC_REGISTRY}${name}/-/${unscoped(name)}-${version}.tgz`;
+}
+export function normalizeNpmLockfile(content, registryUrl) {
+    const base = registryUrl.endsWith("/") ? registryUrl : `${registryUrl}/`;
+    return content.replace(RESOLVED, (match, open, url, close) => {
+        if (!url.startsWith(base))
+            return match;
+        const target = parseProxyPath(url.slice(base.length));
+        return target ? `${open}${publicNpmTarballUrl(target.name, target.version)}${close}` : match;
+    });
+}
+export const npmLockfiles = {
+    names: ["package-lock.json", "npm-shrinkwrap.json"],
+    normalize: normalizeNpmLockfile,
+};

package/dist/coding/registry/npm-plan.d.ts

@@ -0,0 +1,29 @@
+import { type DeclaredDependency, type LockfilePlanSupport, type ParsedLockfile, type UpstreamFetch, type VersionFact } from "./types.js";
+/** The registry dependencies a manifest's dependency map declares: each
+ *  one's install folder (`key`), the registry package it installs (an
+ *  alias `"string-width-cjs": "npm:string-width@^4"` installs its target,
+ *  under the alias's own range) and its range. A spec that isn't fetched
+ *  from the registry at all (`file:`, `link:`, a path, `git`/`git+…`, an
+ *  `http(s):` tarball, `github:`/`user/repo` shorthands, `workspace:`)
+ *  contributes nothing: every such spec contains a `:` or a `/`, which no
+ *  semver range or dist-tag does. */
+export declare function registryDependencyEdges(deps: unknown): DeclaredDependency[];
+/** Every registry dependency a manifest declares, in npm's install order
+ *  (dependencies, optionalDependencies, peerDependencies), once per
+ *  install folder: npm lists an optional dependency under `dependencies`
+ *  too, and the first declaration of a folder is the one npm uses. */
+export declare function declaredDependencies(manifest: Record<string, unknown>, fields: readonly string[]): DeclaredDependency[];
+export declare function parseNpmLockfile(body: string, options: {
+    maxEntries: number;
+    proxyRegistryUrl: string;
+}): ParsedLockfile;
+export declare function fetchNpmVersionFact(name: string, version: string, upstream: UpstreamFetch, signal?: AbortSignal): Promise<VersionFact | null>;
+export declare function fetchNpmPublishTimes(name: string, versions: readonly string[], upstream: UpstreamFetch, options: {
+    maxBytes: number;
+    signal: AbortSignal;
+}): Promise<Map<string, Date>>;
+/** Whether a locked version satisfies a declared range: `*` and dist-tags
+ *  accept any version (as npm's own dep-valid does), otherwise strict semver,
+ *  the same match the graph walk uses. */
+export declare function npmEdgeSatisfies(version: string, range: string): boolean;
+export declare const npmLockfilePlan: LockfilePlanSupport;