@peers-app/peers-sdk 0.26.5 → 0.27.0

package/dist/package-build/freeze-contracts.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.freezePackageContracts = freezePackageContracts;
+exports.assertFrozenContracts = assertFrozenContracts;
+exports.readFrozenContracts = readFrozenContracts;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_module_1 = require("node:module");
+const path = require("node:path");
+const zod_1 = require("zod");
+const contract_definition_schema_1 = require("../contracts/contract-definition-schema");
+const frozen_contracts_1 = require("../contracts/frozen-contracts");
+const isolated_artifact_1 = require("../package-loader/isolated-artifact");
+const build_package_1 = require("./build-package");
+/**
+ * Freeze the contract versions a package provides, before releasing it as stable: add each one
+ * not yet in `frozen-contracts.json`, as frozen by the package's version. With `check`, or when a
+ * frozen version's shape changed, write nothing.
+ *
+ * @param options - The package, where its contracts come from, and whether only to check.
+ */
+async function freezePackageContracts(options) {
+    const root = path.resolve(options.root ?? process.cwd());
+    const { contracts, alsoImplements, packageVersion } = options.bundle
+        ? await bundleContracts(path.resolve(options.bundle))
+        : manifestContracts(await (0, build_package_1.packageManifest)({ root, entry: options.entry }));
+    const file = path.join(root, frozen_contracts_1.FROZEN_CONTRACTS_FILE);
+    const current = await readFrozenContracts(root);
+    const check = checkServedContracts(current ?? { contracts: [] }, contracts, alsoImplements);
+    if (options.check) {
+        return { path: file, packageVersion, added: [], check, written: false };
+    }
+    if (!packageVersion)
+        throw new Error("The package has no version to freeze its contracts as");
+    if (check.changed.length > 0) {
+        return { path: file, packageVersion, added: [], check, written: false };
+    }
+    const result = (0, frozen_contracts_1.freezeContracts)(current, contracts, packageVersion);
+    const written = result.check.changed.length === 0 && (result.added.length > 0 || !current);
+    if (written)
+        await (0, promises_1.writeFile)(file, `${JSON.stringify(result.frozen, null, 2)}\n`, "utf8");
+    return { path: file, packageVersion, added: result.added, check, written };
+}
+/** Compare explicit and carried shapes; aliases still serve the versions they name. */
+function checkServedContracts(frozen, contracts, alsoImplements) {
+    const check = (0, frozen_contracts_1.checkFrozenContracts)(frozen, contracts);
+    const changed = new Map(check.changed.map((change) => [
+        `${change.contract.contractId}@${change.contract.version}`,
+        change,
+    ]));
+    // A bundle may have been authored by hand or built against an older snapshot. Merely naming
+    // a frozen version must not let a different carried shape bypass the source-controlled guard.
+    for (const target of alsoImplements) {
+        if (!target.definition)
+            continue;
+        for (const change of (0, frozen_contracts_1.checkFrozenContracts)(frozen, [target.definition]).changed) {
+            changed.set(`${change.contract.contractId}@${change.contract.version}`, change);
+        }
+    }
+    return {
+        changed: [...changed.values()],
+        notProvided: check.notProvided.filter((contract) => !alsoImplements.some((target) => namesVersion(target, contract))),
+    };
+}
+/** Whether an `alsoImplements` declaration names a contract version (a single one or in its range). */
+function namesVersion(target, contract) {
+    const { from, to } = typeof target.version === "number"
+        ? { from: target.version, to: target.version }
+        : target.version;
+    return (target.contractId === contract.contractId && contract.version >= from && contract.version <= to);
+}
+/**
+ * Refuse a manifest that changes a contract version the package's stable releases froze, as
+ * `peers-package build` does. A package without `frozen-contracts.json` passes.
+ *
+ * @param root - The package root.
+ * @param manifest - The manifest about to be built.
+ */
+async function assertFrozenContracts(root, manifest) {
+    const frozen = await readFrozenContracts(root);
+    if (!frozen)
+        return;
+    const { contracts, alsoImplements } = manifestContracts(manifest);
+    const check = checkServedContracts(frozen, contracts, alsoImplements);
+    if (check.changed.length > 0) {
+        throw new Error(`This build changes a frozen contract:\n${(0, frozen_contracts_1.describeFrozenContractChanges)(check).join("\n")}`);
+    }
+}
+/**
+ * Read a package's `frozen-contracts.json`.
+ *
+ * @param root - The package root.
+ * @returns Its content, or undefined when the package has none.
+ */
+async function readFrozenContracts(root) {
+    const file = path.join(root, frozen_contracts_1.FROZEN_CONTRACTS_FILE);
+    if (!(0, node_fs_1.existsSync)(file))
+        return undefined;
+    const frozen = JSON.parse(await (0, promises_1.readFile)(file, "utf8"));
+    const validated = frozenContractsSchema.safeParse(frozen);
+    if (!validated.success) {
+        throw new Error(`Invalid ${file}: ${validated.error.message}`);
+    }
+    // Validate without normalizing or stripping keys: retain the exact released shape, including
+    // IR additions this SDK does not yet know, for comparison and subsequent freezes.
+    return frozen;
+}
+const frozenContractsSchema = zod_1.z.object({
+    about: zod_1.z.string().optional(),
+    contracts: zod_1.z
+        .array(contract_definition_schema_1.contractDefinitionSchema.extend({
+        frozenBy: zod_1.z.string().trim().min(1),
+        devTag: zod_1.z.never().optional(),
+    }))
+        .superRefine((contracts, ctx) => {
+        const keys = new Set();
+        contracts.forEach((contract, index) => {
+            const key = `${contract.contractId}@${contract.version}`;
+            if (keys.has(key)) {
+                ctx.addIssue({
+                    code: zod_1.z.ZodIssueCode.custom,
+                    path: [index],
+                    message: `Duplicate contract ${key}`,
+                });
+            }
+            keys.add(key);
+        });
+    }),
+});
+const aliasVersionSchema = contract_definition_schema_1.contractDefinitionSchema.shape.version;
+const alsoImplementsSchema = zod_1.z.map(zod_1.z.string(), zod_1.z.array(zod_1.z
+    .object({
+    contractId: contract_definition_schema_1.contractDefinitionSchema.shape.contractId,
+    version: zod_1.z.union([
+        aliasVersionSchema,
+        zod_1.z
+            .object({ from: aliasVersionSchema, to: aliasVersionSchema })
+            .refine(({ from, to }) => from <= to, "version.from must not exceed .to"),
+    ]),
+    definition: contract_definition_schema_1.contractDefinitionSchema.optional(),
+})
+    .refine((target) => !target.definition ||
+    (target.definition.contractId === target.contractId &&
+        target.definition.version === target.version), "definition must be the declared contract version")));
+/**
+ * The contracts an isolated manifest provides, as the Runtime registers them, and the versions
+ * they also implement.
+ */
+function manifestContracts(manifest) {
+    return {
+        contracts: manifest.provides.map((contract) => (0, isolated_artifact_1.isolatedContractToDefinition)(contract, manifest.tables ?? [])),
+        alsoImplements: manifest.provides.flatMap((contract) => contract.alsoImplements ?? []),
+        packageVersion: manifest.version,
+    };
+}
+/** The contracts a built bundle provides: an isolated artifact, or a host-backed CommonJS bundle. */
+async function bundleContracts(file) {
+    const text = await (0, promises_1.readFile)(file, "utf8");
+    if ((0, isolated_artifact_1.looksLikeIsolatedPackageArtifact)(text.trimStart())) {
+        return manifestContracts((0, isolated_artifact_1.parseIsolatedPackageArtifact)(text.trimStart()).manifest);
+    }
+    // A host-backed bundle is CommonJS with the Peers SDK and zod as externals, as the package
+    // loader runs it. Its module code runs here, as it would in the host.
+    const sdk = require("../index");
+    const packageRequire = (0, node_module_1.createRequire)(file);
+    const module = { exports: {} };
+    const requireExternal = (id) => {
+        if (id === "PeersSDK" || id === "peers-sdk" || id === "@peers-app/peers-sdk")
+            return sdk;
+        if (id === "zod")
+            return require("zod");
+        return packageRequire(id);
+    };
+    new Function("module", "exports", "require", text)(module, module.exports, requireExternal);
+    const definition = module.exports.packageDefinition;
+    if (!Array.isArray(definition?.contracts)) {
+        throw new Error(`${file} isn't a package artifact and exports no packageDefinition`);
+    }
+    const validated = zod_1.z.array(contract_definition_schema_1.contractDefinitionSchema).safeParse(definition.contracts);
+    if (!validated.success) {
+        throw new Error(`Invalid contracts in ${file}: ${validated.error.message}`);
+    }
+    if (definition.alsoImplements !== undefined) {
+        const aliases = alsoImplementsSchema.safeParse(definition.alsoImplements);
+        if (!aliases.success) {
+            throw new Error(`Invalid alsoImplements in ${file}: ${aliases.error.message}`);
+        }
+    }
+    // The loader reads this map only for contracts actually provided by the bundle. Stale map
+    // entries for removed contracts do not serve their targets and must not quiet retirement notes.
+    const alsoImplements = definition.contracts.flatMap((contract) => definition.alsoImplements?.get(`${contract.contractId}@${contract.version}`) ?? []);
+    // Keep the original definitions: parsing would strip unknown IR keys.
+    return {
+        contracts: definition.contracts,
+        alsoImplements,
+        packageVersion: definition.version ?? "",
+    };
+}

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

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

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

@@ -0,0 +1,355 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const path = require("node:path");
+const peer_id_1 = require("../peer-id");
+const build_package_1 = require("./build-package");
+const cli_1 = require("./cli");
+const freeze_contracts_1 = require("./freeze-contracts");
+const sdkRoot = path.resolve(__dirname, "../..");
+const packageId = (0, peer_id_1.newid)();
+const contractId = (0, peer_id_1.newid)();
+let root;
+/** A `/define` package providing Probe v1 (and v2 when asked), its tool shaped by `input`. */
+function declaration(version, input, description = "Probe.", withV2 = false) {
+    const contract = (contractVersion) => `defineContract({
+    contractId: ${JSON.stringify(contractId)}, version: ${contractVersion}, name: "Probe",
+    tools: [defineTool({
+      name: "probe", usageDescription: ${JSON.stringify(description)}, accessLevel: 0,
+      inputSchema: z.object(${input}), outputSchema: z.object({}),
+      handler: () => ({}),
+    })],
+  })`;
+    return `
+    import { defineContract, definePackage, defineTool, z } from "@peers-app/peers-sdk/define";
+    export default definePackage((pkg) => {
+      pkg.packageId = ${JSON.stringify(packageId)};
+      pkg.version = ${JSON.stringify(version)};
+      pkg.provides(${contract(1)});
+      ${withV2 ? `pkg.provides(${contract(2)});` : ""}
+    });
+  `;
+}
+const frozen = async () => JSON.parse(await (0, promises_1.readFile)(path.join(root, "frozen-contracts.json"), "utf8"));
+beforeEach(async () => {
+    root = await (0, promises_1.mkdtemp)(path.join((0, node_os_1.tmpdir)(), "peers-package-freeze-"));
+    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");
+    await (0, promises_1.writeFile)(path.join(root, "package.json"), '{"name":"freeze-probe","version":"1.0.0"}');
+    await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration("1.0.0", "{ name: z.string() }"));
+});
+afterEach(async () => {
+    await (0, promises_1.rm)(root, { recursive: true, force: true });
+});
+test("freezes a release's contracts, then the build refuses a shape change but not a new description", async () => {
+    const log = jest.spyOn(console, "log").mockImplementation(() => undefined);
+    const error = jest.spyOn(console, "error").mockImplementation(() => undefined);
+    try {
+        // Nothing frozen yet: the check passes, saying so, and the build runs.
+        await expect((0, cli_1.main)(["contract", "freeze", "--check", "--root", root])).resolves.toBe(0);
+        expect(log).toHaveBeenCalledWith(expect.stringContaining("nothing is frozen yet"));
+        await expect((0, freeze_contracts_1.freezePackageContracts)({ root })).resolves.toMatchObject({
+            packageVersion: "1.0.0",
+            added: [expect.objectContaining({ contractId, version: 1, frozenBy: "1.0.0" })],
+            written: true,
+        });
+        expect((await frozen()).contracts.map(({ version, frozenBy }) => [version, frozenBy])).toEqual([
+            [1, "1.0.0"],
+        ]);
+        await expect((0, freeze_contracts_1.freezePackageContracts)({ root })).resolves.toMatchObject({
+            added: [],
+            written: false,
+        });
+        // A new description is allowed; a changed input isn't, in the build or the check.
+        await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration("1.1.0", "{ name: z.string() }", "Probe, described again."));
+        await expect((0, build_package_1.buildPackage)({ root })).resolves.toMatchObject({});
+        await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration("1.1.0", "{ name: z.string(), count: z.number() }"));
+        await expect((0, build_package_1.buildPackage)({ root })).rejects.toThrow(`This build changes a frozen contract:\nProbe (${contractId}@1), frozen by 1.0.0: tool probe changed.`);
+        await expect((0, build_package_1.generatePackageManifest)({ root })).rejects.toThrow("tool probe changed");
+        const beforeFailure = await (0, promises_1.readFile)(path.join(root, "frozen-contracts.json"), "utf8");
+        await expect((0, cli_1.main)(["contract", "freeze", "--check", "--root", root])).resolves.toBe(1);
+        await expect((0, cli_1.main)(["contract", "freeze", "--root", root])).resolves.toBe(1);
+        expect(error).toHaveBeenCalledWith(expect.stringContaining("tool probe changed"));
+        expect((await frozen()).contracts).toHaveLength(1);
+        expect(await (0, promises_1.readFile)(path.join(root, "frozen-contracts.json"), "utf8")).toBe(beforeFailure);
+        // The change goes in a new version, which the next stable release freezes.
+        await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), declaration("2.0.0", "{ name: z.string() }", "Probe.", true));
+        await expect((0, cli_1.main)(["contract", "freeze", "--root", root])).resolves.toBe(0);
+        expect((await frozen()).contracts.map(({ version, frozenBy }) => [version, frozenBy])).toEqual([
+            [1, "1.0.0"],
+            [2, "2.0.0"],
+        ]);
+    }
+    finally {
+        log.mockRestore();
+        error.mockRestore();
+    }
+});
+test("doesn't note a frozen version the package still serves through alsoImplements", async () => {
+    const log = jest.spyOn(console, "log").mockImplementation(() => undefined);
+    const v2 = (alsoImplements) => `
+    import { defineContract, definePackage, defineTool, z } from "@peers-app/peers-sdk/define";
+    export default definePackage((pkg) => {
+      pkg.packageId = ${JSON.stringify(packageId)};
+      pkg.version = "2.0.0";
+      pkg.provides(defineContract({
+        contractId: ${JSON.stringify(contractId)}, version: 2, name: "Probe",
+        tools: [defineTool({
+          name: "probe", usageDescription: "Probe.", accessLevel: 0,
+          inputSchema: z.object({ name: z.string(), tag: z.string().optional() }),
+          outputSchema: z.object({}), handler: () => ({}),
+        })],
+        ${alsoImplements}
+      }));
+    });
+  `;
+    try {
+        await (0, freeze_contracts_1.freezePackageContracts)({ root });
+        await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), v2("alsoImplements: [1],"));
+        await expect((0, freeze_contracts_1.freezePackageContracts)({ root, check: true })).resolves.toMatchObject({
+            check: { changed: [], notProvided: [] },
+        });
+        await expect((0, cli_1.main)(["contract", "freeze", "--root", root])).resolves.toBe(0);
+        expect(log).not.toHaveBeenCalledWith(expect.stringContaining("is no longer provided"));
+        expect((await frozen()).contracts.map(({ version, frozenBy }) => [version, frozenBy])).toEqual([
+            [1, "1.0.0"],
+            [2, "2.0.0"],
+        ]);
+        // Without the alias, v1's consumers lose this provider, and the check says so.
+        await (0, promises_1.writeFile)(path.join(root, "src/package.ts"), v2(""));
+        const checked = await (0, freeze_contracts_1.freezePackageContracts)({ root, check: true });
+        expect(checked.check.notProvided.map(({ version }) => version)).toEqual([1]);
+    }
+    finally {
+        log.mockRestore();
+    }
+});
+test("reads an isolated artifact with a cwd-relative bundle and a separate root", async () => {
+    const built = await (0, build_package_1.buildPackage)({ root });
+    await expect((0, freeze_contracts_1.freezePackageContracts)({
+        root,
+        bundle: path.relative(process.cwd(), built.artifactPath),
+    })).resolves.toMatchObject({ written: true, packageVersion: "1.0.0" });
+    await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle: built.artifactPath, check: true })).resolves.toMatchObject({ written: false, check: { changed: [] } });
+});
+test("checks a bundle's carried shapes against frozen versions before writing", async () => {
+    await (0, freeze_contracts_1.freezePackageContracts)({ root });
+    const file = path.join(root, "frozen-contracts.json");
+    const before = await (0, promises_1.readFile)(file, "utf8");
+    const built = await (0, build_package_1.buildPackage)({ root });
+    const { frozenBy: _frozenBy, ...original } = (await frozen()).contracts[0];
+    const carried = {
+        ...original,
+        tools: [{ ...original.tools[0], inputFields: [] }],
+    };
+    const manifest = structuredClone(built.manifest);
+    manifest.provides[0].version = 2;
+    manifest.provides[0].tools[0].inputFields = [];
+    manifest.provides[0].alsoImplements = [{ contractId, version: 1, definition: carried }];
+    await (0, promises_1.writeFile)(built.artifactPath, `PEERS_ISOLATED_PACKAGE_V1\n${JSON.stringify({ manifest, providerSource: "void 0;" })}\n`);
+    for (const check of [true, false]) {
+        await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle: built.artifactPath, check })).resolves.toMatchObject({
+            added: [],
+            written: false,
+            check: {
+                changed: [{ contract: { contractId, version: 1 }, changes: ["tool probe changed"] }],
+            },
+        });
+        expect(await (0, promises_1.readFile)(file, "utf8")).toBe(before);
+    }
+    await expect((0, freeze_contracts_1.assertFrozenContracts)(root, manifest)).rejects.toThrow("tool probe changed");
+});
+test("only a provided host contract's aliases quiet retirement notes, with inclusive ranges", async () => {
+    await (0, freeze_contracts_1.freezePackageContracts)({ root });
+    const { frozenBy: _frozenBy, ...original } = (await frozen()).contracts[0];
+    const otherId = (0, peer_id_1.newid)();
+    const provided = { ...original, contractId: otherId, version: 3 };
+    const bundle = path.join(root, "aliases.bundle.js");
+    const target = { contractId, version: { from: 1, to: 2 } };
+    const cases = [
+        { key: `${otherId}@3`, target, notProvided: [] },
+        { key: `${otherId}@2`, target, notProvided: [expect.objectContaining({ contractId })] },
+        {
+            key: `${otherId}@3`,
+            target: { contractId: otherId, version: { from: 1, to: 2 } },
+            notProvided: [expect.objectContaining({ contractId })],
+        },
+    ];
+    for (const { key, target, notProvided } of cases) {
+        await (0, promises_1.writeFile)(bundle, `exports.packageDefinition = {
+        version: "2.0.0", contracts: [${JSON.stringify(provided)}],
+        alsoImplements: new Map([[${JSON.stringify(key)}, [${JSON.stringify(target)}]]]),
+      };`);
+        for (const check of [true, false]) {
+            await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle, check })).resolves.toMatchObject({
+                check: { changed: [], notProvided },
+            });
+        }
+    }
+});
+test.each([
+    "{}",
+    `new Map([[${JSON.stringify(`${contractId}@2`)}, {}]])`,
+    `new Map([[${JSON.stringify(`${contractId}@2`)}, [null]]])`,
+    `new Map([[${JSON.stringify(`${contractId}@2`)}, [{ contractId: ${JSON.stringify(contractId)}, version: 1.5 }]]])`,
+    `new Map([[${JSON.stringify(`${contractId}@2`)}, [{ contractId: ${JSON.stringify(contractId)}, version: { from: 2, to: 1 } }]]])`,
+])("rejects malformed host alsoImplements without changing the snapshot: %s", async (aliases) => {
+    await (0, freeze_contracts_1.freezePackageContracts)({ root });
+    const file = path.join(root, "frozen-contracts.json");
+    const before = await (0, promises_1.readFile)(file, "utf8");
+    const { frozenBy: _frozenBy, ...original } = (await frozen()).contracts[0];
+    const bundle = path.join(root, "invalid-alias.bundle.js");
+    await (0, promises_1.writeFile)(bundle, `exports.packageDefinition = {
+      version: "2.0.0", contracts: [${JSON.stringify({ ...original, version: 2 })}],
+      alsoImplements: ${aliases},
+    };`);
+    for (const check of [true, false]) {
+        await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle, check })).rejects.toThrow("Invalid alsoImplements");
+        expect(await (0, promises_1.readFile)(file, "utf8")).toBe(before);
+    }
+});
+test.each([
+    "",
+    "{",
+    "null",
+    "{}",
+    '{"contracts":[{}]}',
+    '{"contracts":null}',
+])("rejects a malformed snapshot without overwriting it: %s", async (content) => {
+    const file = path.join(root, "frozen-contracts.json");
+    await (0, promises_1.writeFile)(file, content);
+    await expect((0, freeze_contracts_1.freezePackageContracts)({ root })).rejects.toThrow();
+    await expect((0, freeze_contracts_1.freezePackageContracts)({ root, check: true })).rejects.toThrow();
+    await expect((0, build_package_1.buildPackage)({ root })).rejects.toThrow();
+    expect(await (0, promises_1.readFile)(file, "utf8")).toBe(content);
+});
+test("rejects incomplete shapes and duplicate frozen identities", async () => {
+    await (0, freeze_contracts_1.freezePackageContracts)({ root });
+    const snapshot = await frozen();
+    const invalid = [
+        { contracts: snapshot.contracts.map(({ version: _version, ...entry }) => entry) },
+        { contracts: snapshot.contracts.map(({ tools: _tools, ...entry }) => entry) },
+        { contracts: snapshot.contracts.map((entry) => ({ ...entry, tools: [{ name: "broken" }] })) },
+        { contracts: [...snapshot.contracts, ...snapshot.contracts] },
+    ];
+    for (const content of invalid) {
+        await (0, promises_1.writeFile)(path.join(root, "frozen-contracts.json"), JSON.stringify(content));
+        await expect((0, freeze_contracts_1.freezePackageContracts)({ root, check: true })).rejects.toThrow("Invalid");
+    }
+});
+test("accepts an empty contracts list and refuses to freeze a missing package version", async () => {
+    await (0, promises_1.writeFile)(path.join(root, "frozen-contracts.json"), '{"contracts":[]}');
+    await expect((0, freeze_contracts_1.freezePackageContracts)({ root })).resolves.toMatchObject({ written: true });
+    const snapshot = await (0, promises_1.readFile)(path.join(root, "frozen-contracts.json"), "utf8");
+    const bundle = path.join(root, "missing-version.js");
+    await (0, promises_1.writeFile)(bundle, "exports.packageDefinition = { contracts: [] };");
+    await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle })).rejects.toThrow("no version");
+    expect(await (0, promises_1.readFile)(path.join(root, "frozen-contracts.json"), "utf8")).toBe(snapshot);
+});
+test("reports a newly written empty snapshot", async () => {
+    const bundle = path.join(root, "empty.js");
+    await (0, promises_1.writeFile)(bundle, 'exports.packageDefinition = { version: "1.0.0", contracts: [] };');
+    const log = jest.spyOn(console, "log").mockImplementation(() => undefined);
+    try {
+        await expect((0, cli_1.main)(["contract", "freeze", "--root", root, "--bundle", bundle])).resolves.toBe(0);
+        expect(log).toHaveBeenCalledWith(expect.stringContaining("Wrote "));
+        expect((await frozen()).contracts).toEqual([]);
+    }
+    finally {
+        log.mockRestore();
+    }
+});
+test("rejects malformed host definitions without creating or replacing a snapshot", async () => {
+    const bundle = path.join(root, "malformed.bundle.js");
+    await (0, promises_1.writeFile)(bundle, 'exports.packageDefinition = { version: "1.0.0", contracts: [{}] };');
+    for (const check of [true, false]) {
+        await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle, check })).rejects.toThrow("Invalid contracts");
+    }
+    await expect((0, promises_1.readFile)(path.join(root, "frozen-contracts.json"))).rejects.toMatchObject({
+        code: "ENOENT",
+    });
+    await (0, freeze_contracts_1.freezePackageContracts)({ root });
+    const before = await (0, promises_1.readFile)(path.join(root, "frozen-contracts.json"), "utf8");
+    for (const check of [true, false]) {
+        await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle, check })).rejects.toThrow("Invalid contracts");
+    }
+    expect(await (0, promises_1.readFile)(path.join(root, "frozen-contracts.json"), "utf8")).toBe(before);
+});
+test("rejects duplicate host contracts without writing and preserves unknown shape keys", async () => {
+    await (0, freeze_contracts_1.freezePackageContracts)({ root });
+    const file = path.join(root, "frozen-contracts.json");
+    const before = await (0, promises_1.readFile)(file, "utf8");
+    const { frozenBy: _frozenBy, ...original } = (await frozen()).contracts[0];
+    const changed = { ...original, tools: [] };
+    const bundle = path.join(root, "duplicate.bundle.js");
+    const writeBundle = (contracts) => (0, promises_1.writeFile)(bundle, `exports.packageDefinition = ${JSON.stringify({ version: "1.1.0", contracts })};`);
+    await writeBundle([changed, original]);
+    for (const check of [true, false]) {
+        await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle, check })).rejects.toThrow("Duplicate provided contract");
+    }
+    expect(await (0, promises_1.readFile)(file, "utf8")).toBe(before);
+    await (0, promises_1.rm)(file);
+    await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle })).rejects.toThrow("Duplicate provided contract");
+    await expect((0, promises_1.readFile)(file)).rejects.toMatchObject({ code: "ENOENT" });
+    const extended = {
+        ...original,
+        tools: [{ ...original.tools[0], futureShape: { enabled: true } }],
+    };
+    await writeBundle([extended]);
+    await (0, freeze_contracts_1.freezePackageContracts)({ root, bundle });
+    expect((await frozen()).contracts[0].tools[0]).toMatchObject({ futureShape: { enabled: true } });
+    await writeBundle([
+        { ...extended, tools: [{ ...extended.tools[0], futureShape: { enabled: false } }] },
+    ]);
+    expect((await (0, freeze_contracts_1.freezePackageContracts)({ root, bundle, check: true })).check.changed).toHaveLength(1);
+});
+test("reads a host-backed package's CommonJS bundle, with the SDK and zod as externals", async () => {
+    const bundle = path.join(root, "legacy.bundle.js");
+    const tool = (fields) => `{
+    tool: {
+      toolId: ${JSON.stringify((0, peer_id_1.newid)())}, name: "act", code: "", usageDescription: "Act.",
+      inputSchema: { type: "complex", fields: ${fields} },
+      outputSchema: { type: "complex", fields: [] },
+    },
+  }`;
+    const legacy = (version, fields) => `
+    const { definePackage } = require("PeersSDK");
+    require("zod");
+    exports.packageDefinition = definePackage((pkg) => {
+      pkg.packageId = ${JSON.stringify(packageId)};
+      pkg.version = ${JSON.stringify(version)};
+      const contract = pkg.contract(${JSON.stringify(contractId)}, 1, "Legacy", "A legacy contract.");
+      contract.tools = [${tool(fields)}];
+    });
+  `;
+    await (0, promises_1.writeFile)(bundle, legacy("0.5.0", '[{ name: "value", type: "string" }]'));
+    await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle })).resolves.toMatchObject({
+        packageVersion: "0.5.0",
+        added: [expect.objectContaining({ name: "Legacy", version: 1, frozenBy: "0.5.0" })],
+    });
+    expect((await frozen()).contracts[0]).not.toHaveProperty("devTag");
+    await (0, promises_1.writeFile)(bundle, legacy("0.6.0", '[{ name: "value", type: "number" }]'));
+    const checked = await (0, freeze_contracts_1.freezePackageContracts)({ root, bundle, check: true });
+    expect(checked.check.changed.map(({ changes }) => changes)).toEqual([["tool act changed"]]);
+    // v2 also implementing v1 still serves it; without that, v1 is no longer provided.
+    const upgraded = (alsoImplements) => `
+    const { definePackage } = require("PeersSDK");
+    exports.packageDefinition = definePackage((pkg) => {
+      pkg.packageId = ${JSON.stringify(packageId)};
+      pkg.version = "1.0.0";
+      const contract = pkg.contract(${JSON.stringify(contractId)}, 2, "Legacy", "A legacy contract.");
+      contract.tools = [${tool('[{ name: "value", type: "string" }]')}];
+      ${alsoImplements}
+    });
+  `;
+    await (0, promises_1.writeFile)(bundle, upgraded(`contract.alsoImplements(${JSON.stringify(contractId)}, 1);`));
+    await expect((0, freeze_contracts_1.freezePackageContracts)({ root, bundle, check: true })).resolves.toMatchObject({
+        check: { changed: [], notProvided: [] },
+    });
+    await (0, promises_1.writeFile)(bundle, upgraded(""));
+    const dropped = await (0, freeze_contracts_1.freezePackageContracts)({ root, bundle, check: true });
+    expect(dropped.check.notProvided.map(({ version }) => version)).toEqual([1]);
+});

package/dist/package-installer/package-creator.d.ts

@@ -2,6 +2,10 @@ import type { DataContext } from "../context/data-context";
 import type { ICreatePackageOpts, ICreatePackageResult, IPackageInstallerDeps, ITemplateCacheResult, TemplateCacheRefreshFailure } from "./types";
 /**
  * Convert a human-readable package name to a filesystem-safe folder slug.
+ * Keeps existing ASCII slugs so creation still imports folders made by older creators.
+ * Uses Unicode letters/numbers when the ASCII slug is empty, or a fresh package folder for
+ * names with no letters or numbers, rather than resolving to the packages root.
+ * Shortens names exceeding a filesystem component's byte limit with a stable hash suffix.
  * "My Widget" → "my-widget", "camelCase Thing" → "camel-case-thing"
  */
 export declare function nameToFolderSlug(name: string): string;