@capybara-hq/plugin-tools 0.0.0-stage → 0.1.0-rc.0

package/dist/marketplace/marketplace.js

@@ -0,0 +1,245 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { isSensitivePermissionKey, PACKAGES_MAX_BYTES_DEFAULT, permissionKeys, permissionSetOfPackage, readExtensionPackage, WARNINGS_KEY_PREFIX, } from "@capybara-hq/kernel";
+import { MARKETPLACE_LIMITS, PLUGIN_MANIFEST_FILE, parseMarketplaceManifest, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
+import { discoverPlugins } from "../discover.js";
+import { integrityOf } from "../integrity.js";
+import { packPlugin } from "../pack/pack.js";
+export { MARKETPLACE_FILE } from "./file.js";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** The marketplace summary of a plugin: its plugin.json description, cut to the summary limit. */
+function summaryOf(description) {
+    const max = MARKETPLACE_LIMITS.summaryChars;
+    return description.length <= max ? description : `${description.slice(0, max - 1)}…`;
+}
+/** The permission summary of a packed plugin, as the kernel computes it at import (display only). */
+async function permissionsOf(bytes, hasExtension) {
+    if (!hasExtension)
+        return { keys: [], sensitive: [] };
+    const ext = await readExtensionPackage(bytes, {
+        maxBytes: PACKAGES_MAX_BYTES_DEFAULT,
+        hostSdkVersion: SDK_VERSION,
+    });
+    const keys = permissionKeys(permissionSetOfPackage(ext))
+        .filter((k) => !k.startsWith(WARNINGS_KEY_PREFIX))
+        .sort();
+    return { keys, sensitive: keys.filter(isSensitivePermissionKey) };
+}
+/** An entry's version: `version`, else its npm source's. */
+const versionOf = (e) => e.version ?? ("npm" in e.source ? e.source.npm.version : undefined);
+/**
+ * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing every
+ * published version of its public plugins (package ecosystem spec §5.2; one entry per
+ * `(name, version)`, Decision 7 of phase A3b). Each public plugin (not `"private": true`) is packed
+ * reproducibly with {@link packPlugin}; when the file has no entry for its name and version, an
+ * entry `{ name, version, summary, homepage?, permissions, source: { npm: { package, version,
+ * integrity } } }` is added (`integrity` the pack's sha512, which the release then publishes
+ * byte for byte; `permissions` display only). A version already listed is not packed or compared:
+ * once published, its bytes are the release gate's business (`release --marketplace`), so a later
+ * source or toolchain change at the same version is not a finding. With `base`, published entries
+ * must be unchanged and first in order, and entries added since must match the tree's packs.
+ * Entries of versions no longer in the tree are kept, so a pinned commit lists what it pins and
+ * older versions stay importable. The file is written formatted as Biome formats it
+ * ({@link formatMarketplaceJson}).
+ * With `write`, the new entries are appended in plugin order (nothing is written when there is any
+ * other finding).
+ */
+export async function syncMarketplace(opts) {
+    const findings = [];
+    const at = (rule, message) => findings.push({ file: opts.file, line: 1, rule, message });
+    if (!existsSync(opts.file)) {
+        at("marketplace-invalid", `${opts.file} does not exist: create it with schemaVersion, name, owner and "plugins": []`);
+        return { added: [], findings };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(opts.file, "utf8"));
+    }
+    catch (e) {
+        at("marketplace-invalid", `not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        return { added: [], findings };
+    }
+    const parsed = parseMarketplaceManifest(raw);
+    if ("errors" in parsed) {
+        at("marketplace-invalid", parsed.errors.join("; "));
+        return { added: [], findings };
+    }
+    const rawEntries = isObj(raw) && Array.isArray(raw.plugins) ? raw.plugins : [];
+    /** `name@version` of the entries added since `opts.base` (all of them without a base). */
+    let addedSinceBase;
+    if (opts.base !== undefined) {
+        const baseEntries = entriesAt(opts.root, opts.file, opts.base);
+        findings.push(...appendOnly(baseEntries, rawEntries, opts.file));
+        addedSinceBase = new Set(rawEntries.slice(baseEntries.length).map((e) => keyOfRaw(e)));
+    }
+    const added = [];
+    const out = await mkdtemp(join(tmpdir(), "capybara-marketplace-"));
+    try {
+        for (const dir of discoverPlugins(opts.root, opts.plugins)) {
+            const pkgFile = join(dir, "package.json");
+            const manifestFile = join(dir, PLUGIN_MANIFEST_FILE);
+            if (!existsSync(pkgFile) || !existsSync(manifestFile))
+                continue;
+            const pkg = JSON.parse(await readFile(pkgFile, "utf8"));
+            if (pkg.private === true)
+                continue;
+            const source = JSON.parse(await readFile(manifestFile, "utf8"));
+            const name = String(source.name);
+            const version = String(pkg.version);
+            const listed = parsed.plugins.filter((e) => e.name === name && versionOf(e) === version);
+            // A version already listed is published (or about to be): its bytes are the release gate's
+            // business, so a later source or toolchain change at the same version is not a finding here.
+            // Only an entry added since the base is compared with the tree's pack.
+            const toCompare = listed.filter((e) => addedSinceBase?.has(`${e.name}@${versionOf(e)}`));
+            if (listed.length > 0 && toCompare.length === 0)
+                continue;
+            const r = await packPlugin(dir, out);
+            const bytes = new Uint8Array(await readFile(r.file));
+            const npm = {
+                package: String(pkg.name),
+                version: r.manifest.version,
+                integrity: integrityOf(bytes),
+            };
+            for (const e of toCompare) {
+                const src = "npm" in e.source ? e.source.npm : undefined;
+                if (src?.package !== npm.package || src.integrity !== npm.integrity) {
+                    const was = src === undefined
+                        ? `a ${Object.keys(e.source)[0]} source`
+                        : `npm ${src.package} with integrity ${src.integrity}`;
+                    at("marketplace-integrity", `${name}@${npm.version} is added as ${was}, but ${dir} packs npm ${npm.package} ` +
+                        `with integrity ${npm.integrity}: run capybara-plugin marketplace --write`);
+                }
+            }
+            if (listed.length > 0)
+                continue;
+            added.push({
+                name: r.manifest.name,
+                version: npm.version,
+                summary: { en: summaryOf(r.manifest.description) },
+                ...(r.manifest.homepage !== undefined && { homepage: r.manifest.homepage }),
+                permissions: await permissionsOf(bytes, r.manifest.extension !== undefined),
+                source: { npm },
+            });
+        }
+    }
+    finally {
+        await rm(out, { recursive: true, force: true });
+    }
+    if (!opts.write) {
+        for (const e of added) {
+            at("marketplace-missing", `${e.name}@${e.version} is not listed: run capybara-plugin marketplace --write`);
+        }
+        return { added, findings };
+    }
+    if (findings.length > 0 || added.length === 0)
+        return { added, findings };
+    const next = isObj(raw) ? { ...raw } : {};
+    next.plugins = [...(Array.isArray(next.plugins) ? next.plugins : []), ...added];
+    const check = parseMarketplaceManifest(next);
+    if ("errors" in check) {
+        at("marketplace-invalid", `the new entries do not parse: ${check.errors.join("; ")}`);
+        return { added, findings };
+    }
+    await writeFile(opts.file, formatMarketplaceJson(next));
+    return { added, findings };
+}
+/** `name@version` of a raw entry (`?` for what is missing). */
+function keyOfRaw(e) {
+    if (!isObj(e))
+        return "?@?";
+    const npm = isObj(e.source) && isObj(e.source.npm) ? e.source.npm : {};
+    return `${String(e.name ?? "?")}@${String(e.version ?? npm.version ?? "?")}`;
+}
+/** JSON with object keys sorted (deep equality of entries regardless of key order). */
+function canonical(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonical).join(",")}]`;
+    if (isObj(v)) {
+        return `{${Object.keys(v)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(v);
+}
+/** The raw `plugins` of the marketplace file at git revision `base` (`[]` when it has no file). */
+function entriesAt(root, file, base) {
+    let text;
+    try {
+        text = execFileSync("git", ["show", `${base}:./${relative(root, file).split("\\").join("/")}`], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (e) {
+        const stderr = String(e.stderr ?? "");
+        if (/does not exist|exists on disk, but not in/.test(stderr))
+            return [];
+        throw new Error(`cannot read ${file} at ${base}: ${stderr.trim() || String(e)}`);
+    }
+    const raw = JSON.parse(text);
+    return isObj(raw) && Array.isArray(raw.plugins) ? raw.plugins : [];
+}
+/**
+ * `marketplace-append-only`: the base's entries are published, so the current list must start with
+ * exactly them, in the same order (an entry is never edited, removed or moved; new ones go last).
+ */
+function appendOnly(base, current, file) {
+    const out = [];
+    base.forEach((b, i) => {
+        const c = current[i];
+        if (c !== undefined && canonical(c) === canonical(b))
+            return;
+        const key = keyOfRaw(b);
+        const moved = current.some((x) => canonical(x) === canonical(b));
+        out.push({
+            file,
+            line: 1,
+            rule: "marketplace-append-only",
+            message: `${key} is published at the base and ${moved ? "moved" : c !== undefined && keyOfRaw(c) === key ? "was edited" : "went away"}: published entries never change and new ones are appended at the end`,
+        });
+    });
+    return out;
+}
+const INDENT = "  ";
+/** The formatter's line width (Biome, as the Capybara repositories configure it). */
+const LINE_WIDTH = 100;
+const isScalar = (v) => v === null || typeof v !== "object";
+/**
+ * `marketplace.json` as Biome formats it with a 2-space indent and a 100-column line width: a
+ * non-empty object puts each member on its own line; an array of scalars stays on one line when
+ * it fits (the trailing comma counted), otherwise one item per line; empty ones are `[]` / `{}`.
+ */
+export function formatMarketplaceJson(value) {
+    const render = (v, depth, lead, tail) => {
+        const pad = INDENT.repeat(depth + 1);
+        const close = INDENT.repeat(depth);
+        if (Array.isArray(v)) {
+            if (v.length === 0)
+                return "[]";
+            if (v.every(isScalar)) {
+                const flat = `[${v.map((x) => JSON.stringify(x)).join(", ")}]`;
+                if (lead + flat.length + tail <= LINE_WIDTH)
+                    return flat;
+            }
+            const items = v.map((x, i) => `${pad}${render(x, depth + 1, pad.length, i < v.length - 1 ? 1 : 0)}`);
+            return `[\n${items.join(",\n")}\n${close}]`;
+        }
+        if (isObj(v)) {
+            const keys = Object.keys(v);
+            if (keys.length === 0)
+                return "{}";
+            const items = keys.map((k, i) => {
+                const head = `${pad}${JSON.stringify(k)}: `;
+                return `${head}${render(v[k], depth + 1, head.length, i < keys.length - 1 ? 1 : 0)}`;
+            });
+            return `{\n${items.join(",\n")}\n${close}}`;
+        }
+        return JSON.stringify(v);
+    };
+    return `${render(value, 0, 0, 0)}\n`;
+}

package/dist/pack/bootstrap.d.ts

@@ -0,0 +1,25 @@
+import { type NpmFetchOptions } from "./npm.js";
+/** One package {@link packBootstrap} wrote. */
+export interface BootstrapPack {
+    name: string;
+    version: string;
+    file: string;
+    integrity: string;
+}
+/**
+ * Produces the bootstrap directory the image bakes (package ecosystem spec §7): every entry of the
+ * bootstrap manifest (`packages/kernel/bootstrap.json`) as `<outDir>/<name>-<version>.tgz`. A
+ * `source: "workspace"` entry is packed from `<repoRoot>/<path>` with {@link packPlugin}
+ * (byte-reproducible) and must equal the entry: the plugin name, the version and the pinned sha512,
+ * otherwise this throws naming the plugin and writes nothing for it (the image build fails rather
+ * than baking a package `capybara bootstrap` would refuse). A `source: "npm"` entry is downloaded
+ * from `opts.registry` (default the public npm registry, the kernel's `packages.npmRegistry`
+ * default; `opts.token` goes to the registry origin only) and written only when its bytes match
+ * the pinned sha512 and its package.json names the entry's package and version; a tampered,
+ * mislabelled or oversized (`bootstrap.too_large`) tarball or an unpublished package or version
+ * throws naming the plugin. So npm entries need the network at
+ * build time only: init installs from the baked directory and never downloads.
+ */
+export declare function packBootstrap(manifestFile: string, repoRoot: string, outDir: string, opts?: {
+    registry?: string;
+} & NpmFetchOptions): Promise<BootstrapPack[]>;

package/dist/pack/bootstrap.js

@@ -0,0 +1,70 @@
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bootstrapFileName, parseBootstrapManifest } from "@capybara-hq/plugin-sdk";
+import { integrityOf } from "../integrity.js";
+import { DEFAULT_NPM_REGISTRY, downloadPinnedNpmPackage } from "./npm.js";
+import { packPlugin } from "./pack.js";
+/**
+ * Produces the bootstrap directory the image bakes (package ecosystem spec §7): every entry of the
+ * bootstrap manifest (`packages/kernel/bootstrap.json`) as `<outDir>/<name>-<version>.tgz`. A
+ * `source: "workspace"` entry is packed from `<repoRoot>/<path>` with {@link packPlugin}
+ * (byte-reproducible) and must equal the entry: the plugin name, the version and the pinned sha512,
+ * otherwise this throws naming the plugin and writes nothing for it (the image build fails rather
+ * than baking a package `capybara bootstrap` would refuse). A `source: "npm"` entry is downloaded
+ * from `opts.registry` (default the public npm registry, the kernel's `packages.npmRegistry`
+ * default; `opts.token` goes to the registry origin only) and written only when its bytes match
+ * the pinned sha512 and its package.json names the entry's package and version; a tampered,
+ * mislabelled or oversized (`bootstrap.too_large`) tarball or an unpublished package or version
+ * throws naming the plugin. So npm entries need the network at
+ * build time only: init installs from the baked directory and never downloads.
+ */
+export async function packBootstrap(manifestFile, repoRoot, outDir, opts = {}) {
+    const parsed = parseBootstrapManifest(JSON.parse(await readFile(manifestFile, "utf8")));
+    if ("errors" in parsed) {
+        throw new Error(`invalid bootstrap manifest ${manifestFile}: ${parsed.errors.join("; ")}`);
+    }
+    await mkdir(outDir, { recursive: true });
+    const staging = await mkdtemp(join(tmpdir(), "pack-bootstrap-"));
+    const out = [];
+    try {
+        for (const e of parsed.plugins) {
+            if (e.source === "npm") {
+                let bytes;
+                try {
+                    bytes = await downloadPinnedNpmPackage(e, opts.registry ?? DEFAULT_NPM_REGISTRY, {
+                        ...(opts.token !== undefined && { token: opts.token }),
+                        ...(opts.maxBytes !== undefined && { maxBytes: opts.maxBytes }),
+                    });
+                }
+                catch (err) {
+                    throw new Error(`${e.name}: ${err instanceof Error ? err.message : String(err)}`, {
+                        cause: err,
+                    });
+                }
+                const file = join(outDir, bootstrapFileName(e));
+                await writeFile(file, bytes);
+                out.push({ name: e.name, version: e.version, file, integrity: e.integrity });
+                continue;
+            }
+            const r = await packPlugin(join(repoRoot, e.path), staging);
+            const integrity = integrityOf(new Uint8Array(await readFile(r.file)));
+            const problems = [
+                r.manifest.name !== e.name && `${e.path} packs the plugin "${r.manifest.name}"`,
+                r.manifest.version !== e.version &&
+                    `version is ${e.version} but ${e.path} packs ${r.manifest.version}`,
+                integrity !== e.integrity && `integrity is ${e.integrity} but ${e.path} packs ${integrity}`,
+            ].filter((p) => typeof p === "string");
+            if (problems.length > 0) {
+                throw new Error(`${e.name}: ${problems.join("; ")}; the bootstrap manifest is stale (pnpm check:bootstrap --write)`);
+            }
+            const file = join(outDir, bootstrapFileName(e));
+            await copyFile(r.file, file);
+            out.push({ name: e.name, version: e.version, file, integrity });
+        }
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+    return out;
+}

package/dist/pack/cli.d.ts

@@ -0,0 +1,20 @@
+export declare const PACK_USAGE: string;
+/**
+ * `capybara-plugin pack`: packs plugin directories into plugin tgz files.
+ *
+ * - `<dir>...`: the plugin directories to pack;
+ * - `--all <root>`: also every plugin of the repository at `<root>` (`<root>/plugins/*`, or `<root>`
+ *   itself when it is a plugin);
+ * - `--bootstrap <manifest>`: the bootstrap directory an image bakes: every entry of the bootstrap
+ *   manifest as `<name>-<version>.tgz`, checked against its pins (workspace entries' `path` is
+ *   relative to `--root`, default the current directory; npm entries are downloaded from
+ *   `--registry`, default `CAPYBARA_PACKAGES__NPM_REGISTRY` (the kernel's `packages.npmRegistry`)
+ *   or else the public npm registry, and must match their pinned sha512; `--npm-token`, default
+ *   `CAPYBARA_PACKAGES__NPM_TOKEN` (the kernel's `packages.npmToken`), is sent as a Bearer token to
+ *   the registry origin only);
+ * - `--out <dir>`: output directory, default `artifacts/plugins` (`artifacts/bootstrap` with
+ *   `--bootstrap`) under the current directory. The last `--out` wins.
+ *
+ * Relative paths resolve against `cwd` (the current directory). Returns the exit code.
+ */
+export declare function packCommand(args: string[], cwd: string): Promise<number>;

package/dist/pack/cli.js

@@ -0,0 +1,109 @@
+import { relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { discoverPlugins } from "../discover.js";
+import { packBootstrap } from "./bootstrap.js";
+import { DEFAULT_NPM_REGISTRY } from "./npm.js";
+import { packPlugin } from "./pack.js";
+export const PACK_USAGE = "capybara-plugin pack [<dir>...] [--all <root>] [--out <dir>]\n" +
+    "       capybara-plugin pack --bootstrap <manifest> [--root <dir>] [--out <dir>] [--registry <url>]\n" +
+    "                                [--npm-token <token>]";
+/**
+ * `capybara-plugin pack`: packs plugin directories into plugin tgz files.
+ *
+ * - `<dir>...`: the plugin directories to pack;
+ * - `--all <root>`: also every plugin of the repository at `<root>` (`<root>/plugins/*`, or `<root>`
+ *   itself when it is a plugin);
+ * - `--bootstrap <manifest>`: the bootstrap directory an image bakes: every entry of the bootstrap
+ *   manifest as `<name>-<version>.tgz`, checked against its pins (workspace entries' `path` is
+ *   relative to `--root`, default the current directory; npm entries are downloaded from
+ *   `--registry`, default `CAPYBARA_PACKAGES__NPM_REGISTRY` (the kernel's `packages.npmRegistry`)
+ *   or else the public npm registry, and must match their pinned sha512; `--npm-token`, default
+ *   `CAPYBARA_PACKAGES__NPM_TOKEN` (the kernel's `packages.npmToken`), is sent as a Bearer token to
+ *   the registry origin only);
+ * - `--out <dir>`: output directory, default `artifacts/plugins` (`artifacts/bootstrap` with
+ *   `--bootstrap`) under the current directory. The last `--out` wins.
+ *
+ * Relative paths resolve against `cwd` (the current directory). Returns the exit code.
+ */
+export async function packCommand(args, cwd) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", short: "h", default: false },
+            all: { type: "string" },
+            out: { type: "string" },
+            bootstrap: { type: "string" },
+            root: { type: "string" },
+            registry: { type: "string" },
+            "npm-token": { type: "string" },
+        },
+    });
+    if (values.help) {
+        console.log(`usage: ${PACK_USAGE}`);
+        return 0;
+    }
+    const outOf = (fallback) => resolve(cwd, values.out ?? fallback);
+    const shown = (p) => {
+        const rel = relative(cwd, p);
+        return rel === "" ? "." : rel.startsWith("..") ? p : rel;
+    };
+    if (values.bootstrap !== undefined) {
+        if (values.all !== undefined || positionals.length > 0) {
+            return usage("--bootstrap takes no plugin directory");
+        }
+        try {
+            const root = values.root === undefined ? cwd : resolve(cwd, values.root);
+            const manifest = resolve(cwd, values.bootstrap);
+            const registry = values.registry ?? (process.env.CAPYBARA_PACKAGES__NPM_REGISTRY || DEFAULT_NPM_REGISTRY);
+            const token = values["npm-token"] ?? process.env.CAPYBARA_PACKAGES__NPM_TOKEN;
+            for (const p of await packBootstrap(manifest, root, outOf("artifacts/bootstrap"), {
+                registry,
+                ...(token !== undefined && token !== "" && { token }),
+            })) {
+                console.log(`${shown(p.file)}  ${p.integrity}`);
+            }
+            return 0;
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
+            return 1;
+        }
+    }
+    const plugins = positionals.map((d) => resolve(cwd, d));
+    if (values.all !== undefined) {
+        const root = resolve(cwd, values.all);
+        const found = discoverPlugins(root);
+        if (found.length === 0) {
+            console.error(`${shown(root)}: no plugin found (no plugins/* and no .capybara-plugin/)`);
+            return 1;
+        }
+        plugins.push(...found.filter((d) => !plugins.includes(d)));
+    }
+    if (plugins.length === 0)
+        return usage("no plugin directory given");
+    const out = outOf("artifacts/plugins");
+    let failed = 0;
+    for (const dir of plugins) {
+        try {
+            const r = await packPlugin(dir, out);
+            console.log(`${shown(r.file)}  sha256=${r.sha256}`);
+            for (const d of r.dropped) {
+                console.warn(`${shown(dir)}: warning: "files" entry "${d}" is not in the package`);
+            }
+        }
+        catch (e) {
+            failed++;
+            console.error(`${shown(dir)}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (failed > 0) {
+        console.error(`\n${failed} plugin(s) failed to pack`);
+        return 1;
+    }
+    return 0;
+}
+function usage(msg) {
+    console.error(`${msg}\nusage: ${PACK_USAGE}`);
+    return 2;
+}

package/dist/pack/index.d.ts

@@ -0,0 +1,4 @@
+export { type BootstrapPack, packBootstrap } from "./bootstrap.js";
+export { PACK_USAGE, packCommand } from "./cli.js";
+export { assertNpmTarballLabel, DEFAULT_NPM_REGISTRY, downloadPinnedNpmPackage, fetchNpmTarball, NPM_TARBALL_MAX_BYTES, type NpmFetchOptions, NpmPackageError, type NpmPackageErrorKind, } from "./npm.js";
+export { METADATA_FIELDS, NOTICES_FILE, type PackResult, packPlugin, STAGING_PREFIX, } from "./pack.js";

package/dist/pack/index.js

@@ -0,0 +1,4 @@
+export { packBootstrap } from "./bootstrap.js";
+export { PACK_USAGE, packCommand } from "./cli.js";
+export { assertNpmTarballLabel, DEFAULT_NPM_REGISTRY, downloadPinnedNpmPackage, fetchNpmTarball, NPM_TARBALL_MAX_BYTES, NpmPackageError, } from "./npm.js";
+export { METADATA_FIELDS, NOTICES_FILE, packPlugin, STAGING_PREFIX, } from "./pack.js";

package/dist/pack/npm.d.ts

@@ -0,0 +1,66 @@
+/** The npm registry the kernel uses by default (`packages.npmRegistry`). */
+export declare const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+/**
+ * The largest tarball downloaded: the kernel's `packages.maxBytes` default
+ * (`PACKAGES_MAX_BYTES_DEFAULT`, 50 MiB; this subpath does not import the kernel, a test keeps the
+ * two equal). A bigger plugin could not be installed by a kernel with the default limit anyway.
+ */
+export declare const NPM_TARBALL_MAX_BYTES = 52428800;
+/** Why {@link fetchNpmTarball} or {@link downloadPinnedNpmPackage} failed. */
+export type NpmPackageErrorKind = 
+/** The package or that version is not on the registry. */
+"unpublished"
+/** The registry's metadata or bytes do not match the pinned sha512. */
+ | "integrity"
+/** Network error, HTTP status, or a packument that cannot be read. */
+ | "fetch"
+/** The tarball is larger than the cap ({@link NPM_TARBALL_MAX_BYTES}): `bootstrap.too_large`. */
+ | "too_large"
+/** The tarball's `package/package.json` names another package or version than was asked for. */
+ | "mislabelled";
+/** Options of {@link fetchNpmTarball} and {@link downloadPinnedNpmPackage}. */
+export interface NpmFetchOptions {
+    /**
+     * Bearer token for a private registry (`CAPYBARA_PACKAGES__NPM_TOKEN`, the kernel's
+     * `packages.npmToken`): sent only to the registry's origin, never to a tarball URL elsewhere.
+     */
+    token?: string;
+    /** Tarball size cap in bytes; default {@link NPM_TARBALL_MAX_BYTES}. */
+    maxBytes?: number;
+}
+/** A pinned npm package could not be fetched or does not match its pin. English message. */
+export declare class NpmPackageError extends Error {
+    readonly kind: NpmPackageErrorKind;
+    constructor(kind: NpmPackageErrorKind, message: string);
+}
+/**
+ * `<pkg>@<version>` from an npm registry: its tarball bytes and the packument's `dist.integrity`
+ * (whatever the registry claims; callers compare it with their pin). The packument is asked for in
+ * npm's abbreviated form; `opts.token` goes to the registry origin only; the tarball is read up to
+ * `opts.maxBytes`. Throws {@link NpmPackageError}: `unpublished` (404 or no such version),
+ * `too_large`, `fetch` (anything else). The bytes are not judged here: see
+ * {@link downloadPinnedNpmPackage} and {@link assertNpmTarballLabel}.
+ */
+export declare function fetchNpmTarball(pkg: string, version: string, registry?: string, opts?: NpmFetchOptions): Promise<{
+    bytes: Uint8Array;
+    distIntegrity: string | undefined;
+    tarball: string;
+}>;
+/**
+ * Downloads `<pkg>@<version>` and checks its bytes against the pinned sha512 `integrity`; returns the
+ * bytes only when they match (a tampered tarball, or a registry serving other bytes than the pin,
+ * throws {@link NpmPackageError} `integrity`), then checks its label
+ * ({@link assertNpmTarballLabel}). The registry's own `dist.integrity` plays no part: only the
+ * bytes are judged.
+ */
+export declare function downloadPinnedNpmPackage(pin: {
+    npm: string;
+    version: string;
+    integrity: string;
+}, registry?: string, opts?: NpmFetchOptions): Promise<Uint8Array>;
+/**
+ * The tarball's `package/package.json` must name `pkg` at `version` (a pin taken from another
+ * package's tarball, or a registry serving one under the wrong name); throws
+ * {@link NpmPackageError} `mislabelled` otherwise (`fetch` when the bytes are no tgz).
+ */
+export declare function assertNpmTarballLabel(bytes: Uint8Array, pkg: string, version: string): Promise<void>;