@peers-app/peers-sdk 0.26.6 → 0.27.1

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>;

package/dist/package-build/cli.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const node_fs_1 = require("node:fs");
+const path = require("node:path");
+const build_package_1 = require("./build-package");
+const contract_add_1 = require("./contract-add");
+const freeze_contracts_1 = require("./freeze-contracts");
+const USAGE = `Usage: peers-package <command> [options]
+
+Commands:
+  manifest              Write dist/manifest.json from the package's declarations (src/package.ts).
+  build                 Write the manifest and dist/package.bundle.js, the artifact the Runtime
+                        installs.
+  contract add <source> Write src/contracts/<name>.v<version>.ts, a declaration of a contract this
+                        package implements or calls, generated from <source>: a declaration module
+                        and its export (path/to/file.ts#Name), a provider's manifest.json or
+                        package.bundle.js, or the JSON getContractDefinition returned.
+  contract freeze       Before releasing a version as stable: record the contract versions it
+                        provides in frozen-contracts.json, whose shapes can't change again. A
+                        build fails if it changes one.
+
+Options:
+  --watch            Rebuild on every change (build only).
+  --root <dir>       Package root. Defaults to the current directory.
+  --entry <file>     Declaration module. Defaults to src/package.ts.
+  --out-dir <dir>    Output directory. Defaults to dist (src/contracts for contract add).
+  --contract <id@v>  The contract to read, when a manifest provides several (contract add).
+  --name <Name>      The declaration's export name (contract add).
+  --check            Write nothing; fail if the declaration is missing or out of date
+                     (contract add), or if a frozen contract changed (contract freeze).
+  --bundle <file>    Read the contracts from a built bundle instead of src/package.ts: an
+                     isolated package.bundle.js, or a host-backed package's CommonJS bundle
+                     (contract freeze).
+`;
+function readOptions(args) {
+    const options = { watch: false };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const value = () => {
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith("--")) {
+                throw new Error(`${arg} needs a value`);
+            }
+            index += 1;
+            return next;
+        };
+        if (arg === "--watch")
+            options.watch = true;
+        else if (arg === "--root")
+            options.root = value();
+        else if (arg === "--entry")
+            options.entry = value();
+        else if (arg === "--out-dir")
+            options.outDir = value();
+        else
+            throw new Error(`Unknown option ${arg}`);
+    }
+    return options;
+}
+function summarize(result) {
+    const { manifest } = result;
+    const tools = manifest.provides.reduce((count, contract) => count + contract.tools.length, 0);
+    return `${manifest.provides.length} contract(s), ${tools} tool(s), ${manifest.tables?.length ?? 0} table(s)`;
+}
+function relative(file) {
+    return path.relative(process.cwd(), file) || file;
+}
+/**
+ * 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.
+ */
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === "contract") {
+        return contractCommand(rest);
+    }
+    if (command !== "manifest" && command !== "build") {
+        process.stdout.write(USAGE);
+        return command === undefined || command === "--help" ? 0 : 1;
+    }
+    const { watch, ...options } = readOptions(rest);
+    if (command === "manifest") {
+        if (watch) {
+            throw new Error("--watch applies to build");
+        }
+        const result = await (0, build_package_1.generatePackageManifest)(options);
+        console.log(`Manifest: ${summarize(result)} -> ${relative(result.manifestPath)}`);
+        return 0;
+    }
+    if (watch) {
+        await (0, build_package_1.watchPackage)(options, (result) => {
+            if (result instanceof Error) {
+                console.error(`Build failed: ${result.message}`);
+                return;
+            }
+            console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; provider ${Math.round(result.providerChars / 1024)} KB)`);
+        });
+        console.log("Watching for changes");
+        return new Promise(() => undefined);
+    }
+    const result = await (0, build_package_1.buildPackage)(options);
+    console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; provider ${Math.round(result.providerChars / 1024)} KB)`);
+    return 0;
+}
+/** `peers-package contract add <source> [options]` or `peers-package contract freeze [options]`. */
+async function contractCommand(args) {
+    const [subcommand, source, ...rest] = args;
+    if (subcommand === "freeze")
+        return freezeCommand(args.slice(1));
+    if (subcommand !== "add" || source === undefined || source.startsWith("--")) {
+        process.stdout.write(USAGE);
+        return 1;
+    }
+    const options = { source };
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        const value = () => {
+            const next = rest[index + 1];
+            if (next === undefined || next.startsWith("--")) {
+                throw new Error(`${arg} needs a value`);
+            }
+            index += 1;
+            return next;
+        };
+        if (arg === "--check")
+            options.check = true;
+        else if (arg === "--root")
+            options.root = value();
+        else if (arg === "--out-dir")
+            options.outDir = value();
+        else if (arg === "--contract")
+            options.contract = value();
+        else if (arg === "--name")
+            options.name = value();
+        else
+            throw new Error(`Unknown option ${arg}`);
+    }
+    const result = await (0, contract_add_1.addContract)(options);
+    const file = relative(result.path);
+    if (options.check) {
+        if (!result.changed)
+            return 0;
+        const regenerate = ["peers-package", "contract", "add", source];
+        for (const [flag, value] of [
+            ["--root", options.root],
+            ["--out-dir", options.outDir],
+            ["--contract", options.contract],
+            ["--name", options.name],
+        ]) {
+            if (value !== undefined)
+                regenerate.push(flag, value);
+        }
+        const command = regenerate
+            .map((arg) => (/^[\w./:@#=-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, "'\\''")}'`))
+            .join(" ");
+        console.error(`${file} is missing or out of date. Run: ${command}`);
+        return 1;
+    }
+    console.log(`${result.changed ? "Wrote" : "Unchanged:"} ${file} (${result.exportName})`);
+    return 0;
+}
+/** `peers-package contract freeze [--check] [--bundle <file>] [--root <dir>] [--entry <file>]`. */
+async function freezeCommand(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const value = () => {
+            const next = args[index + 1];
+            if (next === undefined || next.startsWith("--")) {
+                throw new Error(`${arg} needs a value`);
+            }
+            index += 1;
+            return next;
+        };
+        if (arg === "--check")
+            options.check = true;
+        else if (arg === "--bundle")
+            options.bundle = value();
+        else if (arg === "--root")
+            options.root = value();
+        else if (arg === "--entry")
+            options.entry = value();
+        else
+            throw new Error(`Unknown option ${arg}`);
+    }
+    const result = await (0, freeze_contracts_1.freezePackageContracts)(options);
+    const file = relative(result.path);
+    for (const contract of result.check.notProvided) {
+        console.log(`Note: ${contract.name} (${contract.contractId}@${contract.version}), frozen by ${contract.frozenBy}, is no longer provided.`);
+    }
+    if (result.check.changed.length > 0) {
+        console.error(`A frozen contract changed (${file}):`);
+        for (const { contract, changes } of result.check.changed) {
+            console.error(`  ${contract.name} (${contract.contractId}@${contract.version}), frozen by ${contract.frozenBy}: ${changes.join("; ")}`);
+        }
+        console.error("Declare a new version of the contract instead.");
+        return 1;
+    }
+    if (options.check) {
+        // A package without the file has frozen nothing yet: the check passes but guards nothing.
+        console.log((0, node_fs_1.existsSync)(result.path)
+            ? `Frozen contracts unchanged (${file}).`
+            : `No ${file}: nothing is frozen yet. Run \`peers-package contract freeze\` before a stable release.`);
+        return 0;
+    }
+    if (!result.written) {
+        console.log(`Nothing new to freeze (${file}).`);
+        return 0;
+    }
+    for (const contract of result.added) {
+        console.log(`Froze ${contract.name} (${contract.contractId}@${contract.version}) as of ${contract.frozenBy}.`);
+    }
+    console.log(`Wrote ${file}. Commit it with the release.`);
+    return 0;
+}

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

@@ -0,0 +1,35 @@
+/** What {@link addContract} takes. */
+export interface IContractAddOptions {
+    /**
+     * Where the contract comes from: a declaration module and its export
+     * (`../voice-hub/src/contracts/voice-skill.ts#VoiceSkill`), a provider's `manifest.json` or
+     * `package.bundle.js`, or the JSON `getContractDefinition` returned.
+     */
+    source: string;
+    /** `contractId@version`, for a manifest that provides more than one contract. */
+    contract?: string;
+    /** Package root. Defaults to the current directory. */
+    root?: string;
+    /** Where the file goes, relative to the root. Defaults to `src/contracts`. */
+    outDir?: string;
+    /** The declaration's export name, instead of the one made from the contract's name. */
+    name?: string;
+    /** Write nothing; report whether the file is missing or out of date. */
+    check?: boolean;
+}
+/** What {@link addContract} did. */
+export interface IContractAddResult {
+    /** The declaration file's path. */
+    path: string;
+    /** Its export name. */
+    exportName: string;
+    /** The file was (or, with `check`, would be) written or changed. */
+    changed: boolean;
+}
+/**
+ * Write (or check) a generated declaration for a contract this package implements or calls:
+ * `src/contracts/<name>.v<version>.ts`, formatted with the package's Biome when it has one.
+ *
+ * @param options - The source, and where the file goes.
+ */
+export declare function addContract(options: IContractAddOptions): Promise<IContractAddResult>;

package/dist/package-build/contract-add.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addContract = addContract;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const path = require("node:path");
+const declare_contract_1 = require("../define/declare-contract");
+const define_package_1 = require("../define/define-package");
+const manifest_1 = require("../define/manifest");
+const isolated_artifact_1 = require("../package-loader/isolated-artifact");
+const build_package_1 = require("./build-package");
+const contract_source_1 = require("./contract-source");
+/**
+ * Write (or check) a generated declaration for a contract this package implements or calls:
+ * `src/contracts/<name>.v<version>.ts`, formatted with the package's Biome when it has one.
+ *
+ * @param options - The source, and where the file goes.
+ */
+async function addContract(options) {
+    const root = path.resolve(options.root ?? process.cwd());
+    const contract = await readContractSource(root, options);
+    const generated = (0, contract_source_1.generateContractDeclaration)(contract, {
+        from: sourceLabel(root, options.source),
+        ...(options.name ? { exportName: options.name } : {}),
+    });
+    const target = path.join(path.resolve(root, options.outDir ?? "src/contracts"), generated.fileName);
+    const source = formatSource(root, target, generated.source);
+    const current = (0, node_fs_1.existsSync)(target) ? await (0, promises_1.readFile)(target, "utf8") : undefined;
+    const changed = current !== source;
+    if (changed && !options.check) {
+        await (0, promises_1.mkdir)(path.dirname(target), { recursive: true });
+        await (0, promises_1.writeFile)(target, source, "utf8");
+    }
+    return { path: target, exportName: generated.exportName, changed };
+}
+/** A source's file and, for a declaration module, its export name (`file.ts#Name`). */
+function splitSource(source) {
+    const hash = source.lastIndexOf("#");
+    return hash > 0
+        ? { file: source.slice(0, hash), exportName: source.slice(hash + 1) }
+        : { file: source };
+}
+/**
+ * The source as the file's header names it: relative to the package root, with `/`, so the
+ * generated file (and `--check`) doesn't depend on where the command ran or on local paths.
+ */
+function sourceLabel(root, source) {
+    const { file, exportName } = splitSource(source);
+    const relative = path.relative(root, path.resolve(file)).split(path.sep).join("/");
+    return exportName === undefined ? relative : `${relative}#${exportName}`;
+}
+async function readContractSource(root, options) {
+    const { file, exportName } = splitSource(options.source);
+    if (exportName !== undefined) {
+        const loaded = (await (0, build_package_1.loadPackageModule)(root, path.resolve(file)));
+        const value = loaded?.[exportName];
+        if ((0, declare_contract_1.isContractDeclaration)(value))
+            return (0, manifest_1.contractManifest)(value.declaration);
+        if ((0, define_package_1.isPackageContract)(value))
+            return (0, manifest_1.contractManifest)(value);
+        throw new Error(`${file} exports no declaration or contract named ${exportName}; pass <file>#<export>`);
+    }
+    const text = (await (0, promises_1.readFile)(path.resolve(options.source), "utf8")).trimStart();
+    if ((0, isolated_artifact_1.looksLikeIsolatedPackageArtifact)(text)) {
+        const artifact = (0, isolated_artifact_1.parseIsolatedPackageArtifact)(text);
+        return (0, contract_source_1.contractSourceFromManifest)(artifact.manifest, options.contract);
+    }
+    const json = JSON.parse(text);
+    if (Array.isArray(json.provides)) {
+        return (0, contract_source_1.contractSourceFromManifest)(json, options.contract);
+    }
+    if (json.definition) {
+        return (0, contract_source_1.contractSourceFromDefinition)(json);
+    }
+    if (typeof json.contractId === "string") {
+        throw new Error(`${options.source} is a contract definition without its tools' access levels; use getContractDefinition's result instead`);
+    }
+    throw new Error(`${options.source} isn't a manifest, a package artifact, or getContractDefinition's result`);
+}
+/** The source as the package's Biome formats it (imports sorted), or as generated without one. */
+function formatSource(root, target, source) {
+    const shim = path.join(root, "node_modules", ".bin", "biome");
+    if (!(0, node_fs_1.existsSync)(shim))
+        return source;
+    const args = ["check", "--write", `--stdin-file-path=${target}`];
+    // Run Biome's Node script when it's there: Windows can't spawn the .bin shell shim itself.
+    const entry = path.join(root, "node_modules", "@biomejs", "biome", "bin", "biome");
+    const [command, commandArgs] = (0, node_fs_1.existsSync)(entry)
+        ? [process.execPath, [entry, ...args]]
+        : [shim, args];
+    const result = (0, node_child_process_1.spawnSync)(command, commandArgs, { cwd: root, input: source, encoding: "utf8" });
+    if (result.status !== 0 || !result.stdout) {
+        throw new Error(`Biome couldn't format the generated declaration: ${result.error?.message || result.stderr || result.stdout}`);
+    }
+    return result.stdout;
+}

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

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