@peers-app/peers-sdk 0.26.5 → 0.27.0

package/dist/observable.js

@@ -5,10 +5,19 @@ exports.computed = computed;
 exports.isSubscribable = isSubscribable;
 exports.unwrapObservable = unwrapObservable;
 exports.linkObservables = linkObservables;
-const lodash_1 = require("lodash");
-const utils_1 = require("./utils");
-const _ = require("lodash");
+/**
+ * Observables: a value you call to read (`obs()`) or write (`obs(value)`), with subscribers
+ * notified on each change. Persistent variables and computed values build on them.
+ *
+ * This module has no dependency beyond peer ids, so isolated package bundles can use it.
+ */
+const peer_id_1 = require("./peer-id");
 const runningComputes = {};
+/**
+ * Create an observable, starting at `initialValue`.
+ *
+ * @param initialValue - The starting value.
+ */
 function observable(initialValue) {
     let value = initialValue;
     const subscribers = [];
@@ -46,12 +55,18 @@ function observable(initialValue) {
     obs.subscriberCount = () => subscribers.length;
     return obs;
 }
+/**
+ * An observable derived from other observables: `read` runs again when any observable it read
+ * changes. Pass `{ read, write }` to make it writable.
+ *
+ * @param fn - The read function, or read and write functions.
+ */
 function computed(fn) {
-    const read = _.isFunction(fn) ? fn : fn.read;
-    const write = _.isFunction(fn) ? undefined : fn.write;
+    const read = typeof fn === "function" ? fn : fn.read;
+    const write = typeof fn === "function" ? undefined : fn.write;
     // compute dependencies and initial value;
     const dependencies = [];
-    const runId = (0, utils_1.newid)();
+    const runId = (0, peer_id_1.newid)();
     runningComputes[runId] = dependencies;
     const _obs = observable(read());
     delete runningComputes[runId];
@@ -84,18 +99,21 @@ function computed(fn) {
         }
     };
     // subscribe to dependencies
-    (0, lodash_1.uniq)(dependencies).forEach((dep) => {
+    [...new Set(dependencies)].forEach((dep) => {
         dep.subscribe(onDepChange);
     });
     Object.assign(obs, _obs);
     return obs;
 }
+/** True when `obj` is an observable. */
 function isSubscribable(obj) {
     return obj && typeof obj === "function" && obj.subscribe && obj.notifySubscribers;
 }
+/** The observable's current value, or `obj` itself when it isn't an observable. */
 function unwrapObservable(obj) {
     return isSubscribable(obj) ? obj() : obj;
 }
+/** Keep two observables equal: a change to either is written to the other. */
 function linkObservables(obs1, obs2) {
     const sub1 = obs1.subscribe((value) => {
         if (value !== obs2()) {

package/dist/package-build/build-package.d.ts

@@ -0,0 +1,60 @@
+import { type IIsolatedPackageManifest } from "../package-loader/isolated-artifact";
+/** Where the package is and where its build goes. */
+export interface IPackageBuildOptions {
+    /** The package's root, holding its `package.json`. Defaults to the current directory. */
+    root?: string;
+    /** The declaration module, relative to `root`. Defaults to `src/package.ts`. */
+    entry?: string;
+    /** The output directory, relative to `root`. Defaults to `dist`. */
+    outDir?: string;
+}
+/** What {@link buildPackage} wrote. */
+export interface IPackageBuildResult {
+    manifest: IIsolatedPackageManifest;
+    manifestPath: string;
+    artifactPath: string;
+    /** Size of the bundled provider source, in characters. */
+    providerChars: number;
+}
+/** A running package watcher. Dispose it to stop watching and release esbuild. */
+export interface IPackageWatcher {
+    dispose(): Promise<void>;
+}
+/**
+ * Bundle a TypeScript or JavaScript module for Node, the way the build loads `src/package.ts`,
+ * and return its exports. Its installed imports resolve from the package at `root`.
+ *
+ * @param root - The package root, whose esbuild compiles the module.
+ * @param entry - The module's path.
+ */
+export declare function loadPackageModule(root: string, entry: string): Promise<unknown>;
+/**
+ * The generate-manifest step: write `dist/manifest.json` from the package's declarations.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ */
+export declare function generatePackageManifest(buildOptions?: IPackageBuildOptions): Promise<{
+    manifest: IIsolatedPackageManifest;
+    manifestPath: string;
+}>;
+/**
+ * Build the package's manifest from its declarations, validated, without writing it or checking
+ * it against `frozen-contracts.json` (`peers-package contract freeze` does that itself).
+ *
+ * @param buildOptions - Package root and declaration entry.
+ */
+export declare function packageManifest(buildOptions?: IPackageBuildOptions): Promise<IIsolatedPackageManifest>;
+/**
+ * Generate the manifest, bundle the provider for the sandbox, and write `dist/package.bundle.js`.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ */
+export declare function buildPackage(buildOptions?: IPackageBuildOptions): Promise<IPackageBuildResult>;
+/**
+ * Build once, then rebuild whenever a source file changes. Resolves once watching starts.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ * @param onBuild - Called after each build, with its result or error.
+ * @returns A handle that stops watching when disposed.
+ */
+export declare function watchPackage(buildOptions?: IPackageBuildOptions, onBuild?: (result: IPackageBuildResult | Error) => void): Promise<IPackageWatcher>;

package/dist/package-build/build-package.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPackageModule = loadPackageModule;
+exports.generatePackageManifest = generatePackageManifest;
+exports.packageManifest = packageManifest;
+exports.buildPackage = buildPackage;
+exports.watchPackage = watchPackage;
+/**
+ * `peers-package`: build an isolated package from its declarations (Node only).
+ *
+ * `manifest` is the generate-manifest step: it loads `src/package.ts` in Node and writes the
+ * manifest, plain JSON in Peers IR, to `dist/manifest.json`. `build` also bundles the same
+ * `src/package.ts` for the sandbox and writes `dist/package.bundle.js`, the artifact the
+ * Runtime installs. esbuild comes from the package's own dependencies.
+ */
+const promises_1 = require("node:fs/promises");
+const node_module_1 = require("node:module");
+const path = require("node:path");
+const manifest_1 = require("../define/manifest");
+const isolated_artifact_1 = require("../package-loader/isolated-artifact");
+const freeze_contracts_1 = require("./freeze-contracts");
+/** Source text SES rejects before running it, with what to tell the author. */
+const SES_REJECTED_PATTERNS = [
+    { pattern: /(?:<!--|-->)/, what: "an HTML comment token (<!-- or -->)" },
+    {
+        pattern: /(^|[^.]|\.\.\.)\bimport(\s*(?:\(|\/[/*]))/,
+        what: "import( or import followed by a comment",
+    },
+    { pattern: /(^|[^.])\beval(\s*\()/, what: "a direct eval(...) call" },
+];
+const NODE_BUILTINS = [...node_module_1.builtinModules, ...node_module_1.builtinModules.map((name) => `node:${name}`)];
+function resolveOptions(options) {
+    const root = path.resolve(options.root ?? process.cwd());
+    const packageRequire = (0, node_module_1.createRequire)(path.join(root, "package.json"));
+    let esbuild;
+    try {
+        esbuild = packageRequire("esbuild");
+    }
+    catch {
+        throw new Error(`peers-package needs esbuild in ${root}. Install it: npm install --save-dev esbuild`);
+    }
+    return {
+        root,
+        entry: path.resolve(root, options.entry ?? "src/package.ts"),
+        outDir: path.resolve(root, options.outDir ?? "dist"),
+        esbuild,
+        require: packageRequire,
+    };
+}
+/** Node compilation used to load the declaration without bundling its installed libraries. */
+function definitionBuildOptions(entry, outfile) {
+    return {
+        entryPoints: [entry],
+        outfile,
+        bundle: true,
+        platform: "node",
+        format: "cjs",
+        target: "node20",
+        packages: "external",
+        logLevel: "silent",
+    };
+}
+/** Bundle the declaration module for Node and load its default export. */
+async function loadDefinition(options) {
+    const loaded = (await loadModule(options, options.entry));
+    const definition = loaded.default;
+    if (definition?.kind !== "package") {
+        throw new Error(`${path.relative(options.root, options.entry)} must export default definePackage(...)`);
+    }
+    return definition;
+}
+/**
+ * Bundle a TypeScript or JavaScript module for Node, the way the build loads `src/package.ts`,
+ * and return its exports. Its installed imports resolve from the package at `root`.
+ *
+ * @param root - The package root, whose esbuild compiles the module.
+ * @param entry - The module's path.
+ */
+async function loadPackageModule(root, entry) {
+    const options = resolveOptions({ root });
+    return loadModule(options, path.resolve(entry));
+}
+/** Bundle one module for Node and load it, then forget it and its installed imports. */
+async function loadModule(options, entry) {
+    // External imports must resolve from the package, even when --out-dir is elsewhere, so the
+    // compiled declaration goes under the package's node_modules/.cache: git and npm ignore it,
+    // so a build killed before cleanup (Ctrl-C while watching) leaves nothing in the source tree.
+    // Use a unique directory so concurrent builds cannot overwrite or remove each other's code.
+    const cacheDir = path.join(options.root, "node_modules", ".cache", "peers-package");
+    await (0, promises_1.mkdir)(cacheDir, { recursive: true });
+    const temporaryDir = await (0, promises_1.mkdtemp)(path.join(cacheDir, "definition-"));
+    const outfile = path.join(temporaryDir, "definition.cjs");
+    const definitionRequire = (0, node_module_1.createRequire)(outfile);
+    let cacheKey;
+    let previousModules;
+    try {
+        await options.esbuild.build(definitionBuildOptions(entry, outfile));
+        cacheKey = definitionRequire.resolve(outfile);
+        previousModules = new Set(Object.keys(definitionRequire.cache));
+        return definitionRequire(outfile);
+    }
+    finally {
+        const previous = previousModules;
+        if (previous) {
+            // The entry is bundled, but its installed dependencies are external. A watch rebuild
+            // must reload those too, including dependencies loaded before an evaluation failed.
+            const cache = definitionRequire.cache;
+            const pending = Object.keys(cache).filter((key) => !previous.has(key));
+            if (cacheKey)
+                pending.push(cacheKey);
+            const seen = new Set();
+            while (pending.length) {
+                const key = pending.pop();
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                for (const child of cache[key]?.children ?? [])
+                    pending.push(child.id);
+                delete cache[key];
+            }
+        }
+        await (0, promises_1.rm)(temporaryDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Check a manifest without changing it: validation fills in defaults on what it's given. Strict,
+ * so a field key this SDK doesn't know (a typo in hand-written IR) fails the build.
+ */
+function validateManifest(manifest, providerSource = "void 0;") {
+    (0, isolated_artifact_1.validateIsolatedPackageArtifact)({ manifest: structuredClone(manifest), providerSource }, { strict: true });
+}
+/** The package's manifest from its declarations, validated. */
+async function validManifest(options) {
+    // frozen-contracts.json gives the shapes of older versions a contract also implements.
+    const manifest = (0, manifest_1.buildPackageManifest)(await loadDefinition(options), {
+        frozen: await (0, freeze_contracts_1.readFrozenContracts)(options.root),
+    });
+    validateManifest(manifest);
+    return manifest;
+}
+/** The package's manifest, validated and checked against the contracts it froze. */
+async function checkedManifest(options) {
+    const manifest = await validManifest(options);
+    await (0, freeze_contracts_1.assertFrozenContracts)(options.root, manifest);
+    return manifest;
+}
+async function writeManifest(options) {
+    return saveManifest(options, await checkedManifest(options));
+}
+async function saveManifest(options, manifest) {
+    const manifestPath = path.join(options.outDir, "manifest.json");
+    await (0, promises_1.mkdir)(options.outDir, { recursive: true });
+    await (0, promises_1.writeFile)(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return { manifest, manifestPath };
+}
+/** esbuild options for the provider bundle: the declaration plus `servePackage`. */
+function providerBuildOptions(options, manifest, plugins = []) {
+    const sandbox = manifest.executionMode !== "privileged";
+    const sdkRoot = path.dirname(options.require.resolve("@peers-app/peers-sdk/package.json"));
+    const zodPath = (0, node_module_1.createRequire)(path.join(sdkRoot, "package.json")).resolve("zod");
+    const singleZod = {
+        name: "peers-package-single-zod",
+        setup(build) {
+            // One zod for the package and the SDK, so schemas from both mix.
+            build.onResolve({ filter: /^zod$/ }, () => ({ path: zodPath }));
+        },
+    };
+    return {
+        stdin: {
+            contents: [
+                `import definition from ${JSON.stringify(options.entry)};`,
+                `import { servePackage } from "@peers-app/peers-sdk/define";`,
+                "servePackage(definition);",
+            ].join("\n"),
+            resolveDir: options.root,
+            sourcefile: "peers-package-provider.js",
+            loader: "js",
+        },
+        bundle: true,
+        write: false,
+        format: "iife",
+        target: "es2022",
+        // The sandbox is a worker with web globals and no Node builtins. A privileged provider runs
+        // in Node with `require`.
+        platform: sandbox ? "browser" : "node",
+        // Leave Node builtins to libraries' own guarded `require`s; the sandbox has none.
+        external: sandbox ? NODE_BUILTINS : [],
+        define: { "process.env.NODE_ENV": '"production"' },
+        // Also strips comments: SES rejects some text even inside a comment.
+        minifyWhitespace: true,
+        legalComments: "none",
+        logLevel: "silent",
+        plugins: [singleZod, ...plugins],
+    };
+}
+function assertSesCompatible(source, manifest) {
+    if (manifest.executionMode === "privileged") {
+        return;
+    }
+    for (const { pattern, what } of SES_REJECTED_PATTERNS) {
+        const match = pattern.exec(source);
+        if (match) {
+            const at = match.index + match[0].length;
+            const snippet = source.slice(Math.max(0, at - 60), at + 20).replace(/\s+/g, " ");
+            throw new Error(`The provider bundle contains ${what}, which the sandbox rejects even inside a string. Near: …${snippet}…`);
+        }
+    }
+}
+async function writeArtifact(options, manifest, providerSource) {
+    assertSesCompatible(providerSource, manifest);
+    validateManifest(manifest, providerSource);
+    const artifactPath = path.join(options.outDir, "package.bundle.js");
+    await (0, promises_1.mkdir)(options.outDir, { recursive: true });
+    await (0, promises_1.writeFile)(artifactPath, `${isolated_artifact_1.ISOLATED_PACKAGE_MAGIC}\n${JSON.stringify({ manifest, providerSource })}\n`, "utf8");
+    return artifactPath;
+}
+/**
+ * The generate-manifest step: write `dist/manifest.json` from the package's declarations.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ */
+async function generatePackageManifest(buildOptions = {}) {
+    return writeManifest(resolveOptions(buildOptions));
+}
+/**
+ * Build the package's manifest from its declarations, validated, without writing it or checking
+ * it against `frozen-contracts.json` (`peers-package contract freeze` does that itself).
+ *
+ * @param buildOptions - Package root and declaration entry.
+ */
+async function packageManifest(buildOptions = {}) {
+    return validManifest(resolveOptions(buildOptions));
+}
+/**
+ * Generate the manifest, bundle the provider for the sandbox, and write `dist/package.bundle.js`.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ */
+async function buildPackage(buildOptions = {}) {
+    const options = resolveOptions(buildOptions);
+    const manifest = await checkedManifest(options);
+    const output = await options.esbuild.build(providerBuildOptions(options, manifest));
+    const providerSource = output.outputFiles?.[0]?.text ?? "";
+    const artifactPath = await writeArtifact(options, manifest, providerSource);
+    const { manifestPath } = await saveManifest(options, manifest);
+    return { manifest, manifestPath, artifactPath, providerChars: providerSource.length };
+}
+/**
+ * Build once, then rebuild whenever a source file changes. Resolves once watching starts.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ * @param onBuild - Called after each build, with its result or error.
+ * @returns A handle that stops watching when disposed.
+ */
+async function watchPackage(buildOptions = {}, onBuild = () => undefined) {
+    const options = resolveOptions(buildOptions);
+    const manifest = await validManifest(options);
+    let mode = manifest.executionMode ?? "sandbox";
+    let disposed = false;
+    let restart = Promise.resolve();
+    let context;
+    const rebuild = {
+        name: "peers-package-write",
+        setup(build) {
+            build.onEnd(async () => {
+                if (disposed)
+                    return;
+                try {
+                    // Recreate the provider's options from the current declaration on every rebuild:
+                    // executionMode can change which platform and dependency exports must be bundled.
+                    const latest = await buildPackage(buildOptions);
+                    onBuild(latest);
+                    const nextMode = latest.manifest.executionMode ?? "sandbox";
+                    if (nextMode !== mode) {
+                        mode = nextMode;
+                        // Dispose after this onEnd returns: awaiting disposal here would deadlock it.
+                        // Recreate the watch graph too, so browser/node conditional dependencies are watched.
+                        restart = restart
+                            .then(async () => {
+                            await context.dispose();
+                            if (disposed)
+                                return;
+                            context = await options.esbuild.context(providerBuildOptions(options, latest.manifest, [rebuild]));
+                            await context.watch();
+                        })
+                            .catch((error) => {
+                            onBuild(error instanceof Error ? error : new Error(String(error)));
+                        });
+                    }
+                }
+                catch (error) {
+                    onBuild(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        },
+    };
+    context = await options.esbuild.context(providerBuildOptions(options, manifest, [rebuild]));
+    try {
+        await context.watch();
+        return {
+            async dispose() {
+                disposed = true;
+                await restart;
+                await context.dispose();
+            },
+        };
+    }
+    catch (error) {
+        await context.dispose();
+        throw error;
+    }
+}

package/dist/package-build/build-package.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/package-build/build-package.test.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const path = require("node:path");
+const node_vm_1 = require("node:vm");
+const isolated_artifact_1 = require("../package-loader/isolated-artifact");
+const peer_id_1 = require("../peer-id");
+const build_package_1 = require("./build-package");
+const sdkRoot = path.resolve(__dirname, "../..");
+const packageId = (0, peer_id_1.newid)();
+const contractId = (0, peer_id_1.newid)();
+let root;
+let watcher;
+function declaration(mode = "sandbox", version = "1.0.0", bad = false) {
+    return `
+    import { defineContract, definePackage, defineTool, z } from "@peers-app/peers-sdk/define";
+    import { side } from "platform-probe";
+    // <!-- Comments that SES rejects must be stripped from the provider.
+    export default definePackage((pkg) => {
+      pkg.packageId = ${JSON.stringify(packageId)};
+      pkg.version = ${JSON.stringify(version)};
+      pkg.executionMode = ${JSON.stringify(mode)};
+      pkg.provides(defineContract({
+        contractId: ${JSON.stringify(contractId)}, version: 1, name: "Probe",
+        tools: [defineTool({
+          name: "probe", usageDescription: "Probe the bundler platform.", accessLevel: 0,
+          inputSchema: z.object({}), outputSchema: z.object({ side: z.string() }),
+          handler: () => ({ side: ${bad ? '"<!--"' : "side"} }),
+        })],
+      }));
+    });
+  `;
+}
+beforeEach(async () => {
+    root = await (0, promises_1.mkdtemp)(path.join((0, node_os_1.tmpdir)(), "peers-package-test-"));
+    await (0, promises_1.mkdir)(path.join(root, "src"));
+    await (0, promises_1.mkdir)(path.join(root, "node_modules/@peers-app"), { recursive: true });
+    await (0, promises_1.symlink)(sdkRoot, path.join(root, "node_modules/@peers-app/peers-sdk"), "dir");
+    await (0, promises_1.symlink)(path.dirname(require.resolve("esbuild/package.json")), path.join(root, "node_modules/esbuild"), "dir");
+    const probe = path.join(root, "node_modules/platform-probe");
+    await (0, promises_1.mkdir)(probe);
+    await (0, promises_1.writeFile)(path.join(root, "package.json"), '{"name":"build-probe","version":"1.0.0"}');
+    await (0, promises_1.writeFile)(path.join(probe, "package.json"), JSON.stringify({
+        name: "platform-probe",
+        exports: { browser: "./browser.js", default: "./node.js" },
+    }));
+    await (0, promises_1.writeFile)(path.join(probe, "browser.js"), 'exports.side = "browser";');
+    await (0, promises_1.writeFile)(path.join(probe, "node.js"), 'exports.side = "node";');
+    await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration());
+});
+afterEach(async () => {
+    await watcher?.dispose();
+    watcher = undefined;
+    await (0, promises_1.rm)(root, { recursive: true, force: true });
+});
+async function probeArtifact() {
+    const artifact = (0, isolated_artifact_1.parseIsolatedPackageArtifact)(await (0, promises_1.readFile)(path.join(root, "dist/package.bundle.js"), "utf8"));
+    const handlers = [];
+    const sandbox = {
+        registerContractTool: (_id, _version, _name, handler) => handlers.push(handler),
+        registerHandler: () => undefined,
+        onWorkerStart: () => undefined,
+    };
+    try {
+        (0, node_vm_1.runInNewContext)(artifact.providerSource, { ...sandbox, self: { crypto: node_crypto_1.webcrypto }, require });
+    }
+    catch (error) {
+        throw new Error(String(error));
+    }
+    return { artifact, result: await handlers[0]({}, {}) };
+}
+test("the CLI generates a validated manifest with custom paths and no provider artifact", async () => {
+    (0, node_child_process_1.execFileSync)(process.execPath, [
+        path.join(sdkRoot, "bin/peers-package.js"),
+        "manifest",
+        "--root",
+        root,
+        "--out-dir",
+        "generated",
+    ], { encoding: "utf8" });
+    const manifest = JSON.parse(await (0, promises_1.readFile)(path.join(root, "generated/manifest.json"), "utf8"));
+    expect(manifest).toMatchObject({ packageId, guestApi: 3, version: "1.0.0" });
+    await expect((0, promises_1.readFile)(path.join(root, "generated/package.bundle.js"))).rejects.toThrow();
+    await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration("sandbox", ""));
+    await expect((0, build_package_1.generatePackageManifest)({ root })).rejects.toThrow(/version/);
+});
+test.each([
+    "sandbox",
+    "privileged",
+])("builds %s with its platform's dependency exports", async (mode) => {
+    await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration(mode));
+    const built = await (0, build_package_1.buildPackage)({ root });
+    const { artifact, result } = await probeArtifact();
+    expect(result).toEqual({ side: mode === "sandbox" ? "browser" : "node" });
+    expect(artifact.providerSource).not.toContain("<!--");
+    const raw = JSON.parse((await (0, promises_1.readFile)(built.artifactPath, "utf8")).split("\n")[1]);
+    expect(raw.manifest).toEqual(JSON.parse(await (0, promises_1.readFile)(built.manifestPath, "utf8")));
+});
+test("manifest and provider builds resolve dependencies with an output directory outside the package", async () => {
+    const outDir = await (0, promises_1.mkdtemp)(path.join((0, node_os_1.tmpdir)(), "peers-package-output-test-"));
+    try {
+        const generated = await (0, build_package_1.generatePackageManifest)({ root, outDir });
+        expect(generated.manifest.packageId).toBe(packageId);
+        expect(generated.manifestPath).toBe(path.join(outDir, "manifest.json"));
+        const built = await (0, build_package_1.buildPackage)({ root, outDir });
+        const raw = JSON.parse((await (0, promises_1.readFile)(built.artifactPath, "utf8")).split("\n")[1]);
+        expect(raw.manifest).toEqual(JSON.parse(await (0, promises_1.readFile)(built.manifestPath, "utf8")));
+    }
+    finally {
+        await (0, promises_1.rm)(outDir, { recursive: true, force: true });
+    }
+});
+test("an interrupted build leaves no scratch files in the package's source tree", async () => {
+    // Killed mid-evaluation, as Ctrl-C during a watch rebuild would: no cleanup code runs.
+    await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), `process.kill(process.pid, "SIGKILL");\n${declaration()}`);
+    expect(() => (0, node_child_process_1.execFileSync)(process.execPath, [path.join(sdkRoot, "bin/peers-package.js"), "manifest", "--root", root], { stdio: "pipe" })).toThrow();
+    expect((await (0, promises_1.readdir)(root)).sort()).toEqual(["node_modules", "package.json", "src"]);
+});
+test("a failed provider build preserves both previously successful outputs", async () => {
+    const first = await (0, build_package_1.buildPackage)({ root });
+    const before = await Promise.all([(0, promises_1.readFile)(first.manifestPath), (0, promises_1.readFile)(first.artifactPath)]);
+    jest.resetModules();
+    await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration("sandbox", "2.0.0", true));
+    await expect((0, build_package_1.buildPackage)({ root })).rejects.toThrow(/HTML comment token/);
+    expect(await Promise.all([(0, promises_1.readFile)(first.manifestPath), (0, promises_1.readFile)(first.artifactPath)])).toEqual(before);
+});
+test("repeated builds reload external declaration dependencies, including after an evaluation failure", async () => {
+    const source = declaration().replace('pkg.version = "1.0.0";', "pkg.version = side;");
+    await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), source);
+    const stdout = (0, node_child_process_1.execFileSync)(process.execPath, [
+        "-e",
+        `
+        const { writeFile } = require("node:fs/promises");
+        const { buildPackage } = require(${JSON.stringify(path.join(sdkRoot, "dist/package-build/build-package.js"))});
+        const root = ${JSON.stringify(root)};
+        const dependency = ${JSON.stringify(path.join(root, "node_modules/platform-probe/node.js"))};
+        (async () => {
+          const versions = [];
+          await writeFile(dependency, 'exports.side = "1.0.0";');
+          versions.push((await buildPackage({ root })).manifest.version);
+          await writeFile(dependency, 'exports.side = "";');
+          try { await buildPackage({ root }); throw new Error("Invalid declaration accepted"); }
+          catch (error) { if (!error.message.includes("must set version")) throw error; }
+          await writeFile(dependency, 'exports.side = "2.0.0";');
+          versions.push((await buildPackage({ root })).manifest.version);
+          process.stdout.write(JSON.stringify(versions));
+        })().catch((error) => { console.error(error); process.exitCode = 1; });
+      `,
+    ], { encoding: "utf8", timeout: 10_000 });
+    expect(JSON.parse(stdout)).toEqual(["1.0.0", "2.0.0"]);
+});
+test("watch rebuilds use the current execution mode and recover after invalid declarations", async () => {
+    const queued = [];
+    let deliver;
+    const next = () => new Promise((resolve, reject) => {
+        const pending = queued.shift();
+        if (pending)
+            return resolve(pending);
+        const timeout = setTimeout(() => reject(new Error("No watch build completed")), 10_000);
+        deliver = (value) => {
+            clearTimeout(timeout);
+            deliver = undefined;
+            resolve(value);
+        };
+    });
+    watcher = await (0, build_package_1.watchPackage)({ root }, (value) => {
+        if (deliver)
+            deliver(value);
+        else
+            queued.push(value);
+    });
+    const until = async (matches) => {
+        let value = await next();
+        while (!matches(value))
+            value = await next();
+        return value;
+    };
+    expect(await next()).not.toBeInstanceOf(Error);
+    for (const mode of ["privileged", "sandbox"]) {
+        // Jest's require cache is separate from the native cache invalidated by loadDefinition.
+        jest.resetModules();
+        await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration(mode));
+        expect(await until((value) => !(value instanceof Error) && value.manifest.executionMode === mode)).toMatchObject({ manifest: { executionMode: mode } });
+        expect((await probeArtifact()).result).toEqual({
+            side: mode === "sandbox" ? "browser" : "node",
+        });
+    }
+    // After changing modes, watch the active conditional dependency as well as src/package.ts.
+    await (0, promises_1.writeFile)(path.join(root, "node_modules/platform-probe/browser.js"), 'exports.side = "browser-v2";');
+    let side;
+    do {
+        expect(await next()).not.toBeInstanceOf(Error);
+        side = (await probeArtifact()).result.side;
+    } while (side !== "browser-v2");
+    jest.resetModules();
+    await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration("sandbox", ""));
+    expect(await until((value) => value instanceof Error)).toBeInstanceOf(Error);
+    jest.resetModules();
+    await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration("sandbox", "2.0.0"));
+    expect(await until((value) => !(value instanceof Error) && value.manifest.version === "2.0.0")).toMatchObject({ manifest: { version: "2.0.0" } });
+}, 30_000);

package/dist/package-build/cli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Run the `peers-package` command.
+ *
+ * @param argv - Arguments after the command name, such as `["build", "--watch"]`.
+ * @returns The exit code, or never resolves while watching.
+ */
+export declare function main(argv: string[]): Promise<number>;