@peers-app/peers-sdk 0.26.5 → 0.27.0

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

@@ -0,0 +1,467 @@
+"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 ts = require("typescript");
+const validate_1 = require("../contracts/validate");
+const declare_contract_1 = require("../define/declare-contract");
+const manifest_1 = require("../define/manifest");
+const isolated_artifact_1 = require("../package-loader/isolated-artifact");
+const peer_id_1 = require("../peer-id");
+const field_type_1 = require("../types/field-type");
+const build_package_1 = require("./build-package");
+const cli_1 = require("./cli");
+const contract_add_1 = require("./contract-add");
+const contract_source_1 = require("./contract-source");
+const sdkRoot = path.resolve(__dirname, "../..");
+const contractId = (0, peer_id_1.newid)();
+let root;
+/** A declaration covering schema-inferred IR features. Hand-written IR is tested separately. */
+const richDeclaration = `
+  import {
+    AccessLevel, declareContract, declareObservable, declareTool, defineEvent, defineTable, z,
+    zodPeerId,
+  } from "@peers-app/peers-sdk/define";
+
+  enum Level { Low = 1, High = 2 }
+  const place = z.object({
+    city: z.string().describe("City."),
+    unit: z.enum(["F", "C"]).optional(),
+    zone: z.string().nullish(),
+  });
+
+  const Places = defineTable({
+        name: "Places",
+        description: "Places.",
+        primaryKeyName: "placeId",
+        schema: z.object({
+          placeId: zodPeerId,
+          label: z.string(),
+          at: z.date().optional(),
+          tags: z.array(z.string()),
+        }),
+        versionNumber: 3,
+  });
+
+  export const Rich = declareContract({
+    contractId: ${JSON.stringify(contractId)},
+    version: 2,
+    name: "Rich Things",
+    description: "Every shape the IR carries.",
+    tables: [Places],
+    tools: [
+      declareTool({
+        name: "plan",
+        usageDescription: "Plan a trip.",
+        accessLevel: AccessLevel.Writer,
+        remoteAccessLevel: AccessLevel.Admin,
+        inputSchema: z.object({
+          place,
+          places: z.array(place).optional(),
+          level: z.nativeEnum(Level),
+          size: z.union([z.literal("small"), z.literal(3)]),
+          mode: z.literal("fast"),
+          when: z.date(),
+          anything: z.unknown().optional(),
+          count: z.number().int().min(1).default(5),
+          extra: z.record(z.string()).optional(),
+        }),
+        outputSchema: z.object({ ok: z.boolean(), ids: z.array(zodPeerId) }),
+      }),
+      declareTool({
+        name: "skim",
+        usageDescription: "Skim.",
+        accessLevel: AccessLevel.Reader,
+        authorityPropagation: "preserve",
+        inputSchema: z.object({}),
+        outputSchema: z.object({ note: z.string().optional() }),
+      }),
+    ],
+    observables: [
+      declareObservable({
+        name: "state",
+        description: "Current state, or null.",
+        schema: z.object({ on: z.boolean(), place }).nullable(),
+        writable: true,
+      }),
+      declareObservable({ name: "count", description: "A count.", schema: z.number() }),
+      declareObservable({ name: "names", description: "Names.", schema: z.array(z.string()) }),
+      declareObservable({
+        name: "transformed",
+        description: "The original code's transform is not part of the IR.",
+        schema: z.number().transform(String),
+      }),
+      declareObservable({ name: "level", description: "A numeric enum.", schema: z.nativeEnum(Level) }),
+    ],
+    events: [
+      defineEvent({
+        name: "place-changed",
+        description: "A place moved.",
+        payloadSchema: z.object({ placeId: zodPeerId, place, at: z.date() }),
+      }),
+      defineEvent({ name: "ping", description: "No payload." }),
+    ],
+  });
+`;
+beforeEach(async () => {
+    root = await (0, promises_1.mkdtemp)(path.join((0, node_os_1.tmpdir)(), "peers-contract-add-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");
+    await (0, promises_1.writeFile)(path.join(root, "package.json"), '{"name":"contract-add-probe","version":"1.0.0"}');
+    await (0, promises_1.writeFile)(path.join(root, "src/rich.ts"), richDeclaration);
+});
+afterEach(async () => {
+    await (0, promises_1.rm)(root, { recursive: true, force: true });
+});
+/** The IR of the declaration a module exports. */
+async function irOf(file, exportName) {
+    const loaded = (await (0, build_package_1.loadPackageModule)(root, file));
+    const value = loaded[exportName];
+    if (!(0, declare_contract_1.isContractDeclaration)(value))
+        throw new Error(`${exportName} isn't a declaration`);
+    return (0, manifest_1.contractManifest)(value.declaration);
+}
+/** esbuild loads the generated file without typechecking; authors also compile it with tsc. */
+function checkTypes(...files) {
+    const program = ts.createProgram(files, {
+        noEmit: true,
+        strict: true,
+        noUnusedLocals: true,
+        skipLibCheck: true,
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.CommonJS,
+        types: [],
+    });
+    expect(ts.formatDiagnostics(ts.getPreEmitDiagnostics(program), {
+        getCurrentDirectory: () => root,
+        getCanonicalFileName: (file) => file,
+        getNewLine: () => "\n",
+    })).toBe("");
+}
+test("a generated declaration has the source's IR, member for member", async () => {
+    const source = path.join(root, "src/rich.ts");
+    const result = await (0, contract_add_1.addContract)({ source: `${source}#Rich`, root });
+    expect(path.relative(root, result.path)).toBe("src/contracts/rich-things.v2.ts");
+    expect(result).toMatchObject({ exportName: "RichThings", changed: true });
+    const generated = await (0, promises_1.readFile)(result.path, "utf8");
+    expect(generated).toMatch(/^\/\/ Generated by `peers-package contract add` from /);
+    expect(generated).toContain("export const richThingsPlaceChanged = defineEvent({");
+    expect(generated).toContain("export type RichThingsObservables = ContractObservableValuesOf<");
+    const original = await irOf(source, "Rich");
+    const copy = await irOf(result.path, "RichThings");
+    expect(copy).toEqual(original);
+    const types = path.join(root, "src/generated-types.ts");
+    await (0, promises_1.writeFile)(types, `
+    import type { RichThingsObservables, RichThingsRows, RichThingsEvents } from "./contracts/rich-things.v2";
+    export const allowed: RichThingsObservables["level"] = 1;
+    // @ts-expect-error The IR's numeric enum admits only 1 or 2.
+    export const refused: RichThingsObservables["level"] = 3;
+    export const row: RichThingsRows["Places"] = { placeId: "id", label: "Place", tags: [] };
+    export const event: RichThingsEvents["place-changed"] = { placeId: "id", place: { city: "City" }, at: new Date() };
+    // @ts-expect-error Member maps keep each row's field types.
+    export const badRow: RichThingsRows["Places"] = { placeId: "id", label: 4, tags: [] };
+  `);
+    checkTypes(result.path, types);
+    const loaded = (await (0, build_package_1.loadPackageModule)(root, result.path));
+    expect(loaded.RichThings.declaration.tools[1].definition.inputSchema.parse({ extra: 1 })).toEqual({ extra: 1 });
+    // A provider built from the copy registers a shape the original's frozen version accepts.
+    const definitions = [original, copy].map(({ contract, tables }) => (0, isolated_artifact_1.isolatedContractToDefinition)(contract, tables));
+    expect((0, validate_1.validateImmutability)(definitions[0], definitions[1])).toEqual({ valid: true, errors: [] });
+    expect((0, validate_1.validateImmutability)(definitions[1], definitions[0])).toEqual({ valid: true, errors: [] });
+});
+test("--check reports a missing, edited, or current declaration", async () => {
+    const source = `${path.join(root, "src/rich.ts")}#Rich`;
+    const check = () => (0, cli_1.main)(["contract", "add", source, "--root", root, "--check"]);
+    const errors = jest.spyOn(console, "error").mockImplementation(() => undefined);
+    const logs = jest.spyOn(console, "log").mockImplementation(() => undefined);
+    try {
+        expect(await check()).toBe(1);
+        await expect((0, promises_1.readFile)(path.join(root, "src/contracts/rich-things.v2.ts"))).rejects.toMatchObject({ code: "ENOENT" });
+        expect(await (0, cli_1.main)(["contract", "add", source, "--root", root])).toBe(0);
+        expect(await check()).toBe(0);
+        const file = path.join(root, "src/contracts/rich-things.v2.ts");
+        // The header names the source relative to the package, however the command spelled it.
+        expect(await (0, promises_1.readFile)(file, "utf8")).toMatch(/^\/\/ Generated by .* from src\/rich\.ts#Rich\./);
+        const fromCwd = path.relative(process.cwd(), path.join(root, "src/rich.ts"));
+        expect(await (0, cli_1.main)(["contract", "add", `${fromCwd}#Rich`, "--root", root, "--check"])).toBe(0);
+        const edited = `${await (0, promises_1.readFile)(file, "utf8")}// edited\n`;
+        await (0, promises_1.writeFile)(file, edited);
+        expect(await check()).toBe(1);
+        expect(await (0, promises_1.readFile)(file, "utf8")).toBe(edited);
+        expect(errors.mock.calls.at(-1)?.[0]).toMatch(/out of date\. Run: peers-package contract add/);
+        expect(await (0, cli_1.main)([
+            "contract",
+            "add",
+            source,
+            "--root",
+            root,
+            "--out-dir",
+            "custom folder",
+            "--name",
+            "Trips",
+            "--check",
+        ])).toBe(1);
+        expect(errors.mock.calls.at(-1)?.[0]).toContain(`--root ${root} --out-dir 'custom folder' --name Trips`);
+    }
+    finally {
+        errors.mockRestore();
+        logs.mockRestore();
+    }
+});
+test("formats with the destination package's Biome and checks that formatted copy", async () => {
+    await (0, promises_1.mkdir)(path.join(root, "node_modules/.bin"));
+    await (0, promises_1.symlink)(path.join(sdkRoot, "node_modules/.bin/biome"), path.join(root, "node_modules/.bin/biome"));
+    await (0, promises_1.writeFile)(path.join(root, "biome.json"), JSON.stringify({ formatter: { indentStyle: "tab" } }));
+    const source = `${path.join(root, "src/rich.ts")}#Rich`;
+    // Without @biomejs/biome in the package's node_modules, the .bin shim runs.
+    const result = await (0, contract_add_1.addContract)({ source, root });
+    expect(await (0, promises_1.readFile)(result.path, "utf8")).toContain("\tcontractId:");
+    expect((await (0, contract_add_1.addContract)({ source, root, check: true })).changed).toBe(false);
+    // With it, Biome's Node script runs (Windows can't spawn the shim), formatting the same way.
+    await (0, promises_1.mkdir)(path.join(root, "node_modules/@biomejs"));
+    await (0, promises_1.symlink)(path.join(sdkRoot, "node_modules/@biomejs/biome"), path.join(root, "node_modules/@biomejs/biome"), "dir");
+    await (0, promises_1.rm)(path.join(root, "node_modules/.bin/biome"));
+    await (0, promises_1.writeFile)(path.join(root, "node_modules/.bin/biome"), "#!/bin/sh\nexit 1\n", {
+        mode: 0o755,
+    });
+    expect((await (0, contract_add_1.addContract)({ source, root, check: true })).changed).toBe(false);
+});
+test("reads a provider's manifest or artifact, choosing the contract when it provides several", async () => {
+    const { contract, tables } = await irOf(path.join(root, "src/rich.ts"), "Rich");
+    const other = {
+        contractId: (0, peer_id_1.newid)(),
+        version: 1,
+        name: "Other",
+        tools: [{ name: "noop", usageDescription: "Nothing.", inputFields: [], outputFields: [] }],
+    };
+    const manifest = {
+        packageId: (0, peer_id_1.newid)(),
+        version: "1.0.0",
+        guestApi: 3,
+        provides: [contract, other],
+        consumes: [],
+        tables,
+    };
+    expect(() => (0, contract_source_1.contractSourceFromManifest)(manifest)).toThrow(/choose one with --contract/);
+    expect(() => (0, contract_source_1.contractSourceFromManifest)(manifest, `${(0, peer_id_1.newid)()}@1`)).toThrow(/doesn't provide/);
+    expect((0, contract_source_1.contractSourceFromManifest)(manifest, `${contractId}@2`)).toEqual({
+        contract,
+        tables,
+    });
+    // What a provider exposes through a contract isn't part of the contract: it isn't generated.
+    const exposing = { ...contract, exposes: [{ contractId: other.contractId, version: 1 }] };
+    expect((0, contract_source_1.generateContractDeclaration)((0, contract_source_1.contractSourceFromManifest)({ ...manifest, provides: [exposing, other] }, `${contractId}@2`), { from: "x" }).source).toBe((0, contract_source_1.generateContractDeclaration)({ contract, tables }, { from: "x" }).source);
+    await (0, promises_1.writeFile)(path.join(root, "manifest.json"), `\uFEFF${JSON.stringify(manifest)}`);
+    const fromManifest = await (0, contract_add_1.addContract)({
+        source: path.join(root, "manifest.json"),
+        contract: `${contractId}@2`,
+        root,
+        outDir: "a",
+    });
+    await (0, promises_1.writeFile)(path.join(root, "package.bundle.js"), 
+    // Serializing validates, which fills in defaults on what it's given.
+    (0, isolated_artifact_1.serializeIsolatedPackageArtifact)({
+        manifest: structuredClone(manifest),
+        providerSource: "void 0;",
+    }));
+    const fromArtifact = await (0, contract_add_1.addContract)({
+        source: path.join(root, "package.bundle.js"),
+        contract: `${contractId}@2`,
+        root,
+        outDir: "b",
+    });
+    expect(await irOf(fromManifest.path, "RichThings")).toEqual({ contract, tables });
+    expect(await (0, promises_1.readFile)(fromArtifact.path, "utf8")).toBe((await (0, promises_1.readFile)(fromManifest.path, "utf8")).replace("from manifest.json.", "from package.bundle.js."));
+    const windowsArtifact = path.join(root, "windows.bundle.js");
+    await (0, promises_1.writeFile)(windowsArtifact, `\uFEFF\r\n${(await (0, promises_1.readFile)(path.join(root, "package.bundle.js"), "utf8")).replace(/\n/g, "\r\n")}`);
+    const fromWindows = await (0, contract_add_1.addContract)({
+        source: windowsArtifact,
+        contract: `${contractId}@2`,
+        root,
+        outDir: "c",
+    });
+    expect(await irOf(fromWindows.path, "RichThings")).toEqual({ contract, tables });
+});
+test("reads getContractDefinition's result, taking each tool's policy from it", async () => {
+    const { contract, tables } = await irOf(path.join(root, "src/rich.ts"), "Rich");
+    const definition = (0, isolated_artifact_1.isolatedContractToDefinition)(contract, tables);
+    const policy = [
+        { name: "plan", accessLevel: 40 },
+        { name: "skim", accessLevel: 20, authorityPropagation: "preserve" },
+    ];
+    const source = (0, contract_source_1.contractSourceFromDefinition)({ definition, tools: policy });
+    // The registry keeps no table storage policy and no persistent-variable bindings.
+    expect(source.contract.tools).toEqual(contract.tools);
+    expect(source.tables.map(({ versionNumber: _v, ...table }) => table)).toEqual(tables.map(({ versionNumber: _v, ...table }) => table));
+    expect(() => (0, contract_source_1.contractSourceFromDefinition)({ definition })).toThrow(/no access level/);
+    expect(() => (0, contract_source_1.contractSourceFromDefinition)({ definition, tools: [policy[0]] })).toThrow(/Runtime reported no access level for tool "skim"/);
+    await (0, promises_1.writeFile)(path.join(root, "definition.json"), JSON.stringify(definition));
+    await expect((0, contract_add_1.addContract)({ source: path.join(root, "definition.json"), root })).rejects.toThrow(/use getContractDefinition's result/);
+    await (0, promises_1.writeFile)(path.join(root, "result.json"), JSON.stringify({ definition, tools: policy }));
+    const written = await (0, contract_add_1.addContract)({ source: path.join(root, "result.json"), root });
+    expect((await irOf(written.path, "RichThings")).contract.tools).toEqual(contract.tools);
+});
+test("names come from the contract unless given, and must be identifiers", async () => {
+    const { contract, tables } = await irOf(path.join(root, "src/rich.ts"), "Rich");
+    expect((0, contract_source_1.generateContractDeclaration)({ contract, tables }, { from: "x" }).exportName).toBe("RichThings");
+    expect((0, contract_source_1.generateContractDeclaration)({ contract, tables }, { from: "x", exportName: "Trips" }).source).toContain("export const Trips = declareContract(");
+    const acronym = (0, contract_source_1.generateContractDeclaration)({ contract: { ...contract, name: "HTTPService" }, tables }, { from: "x" });
+    expect(acronym.fileName).toBe("http-service.v2.ts");
+    expect(acronym.source).toContain("export const httpServicePlaceChanged = defineEvent(");
+    expect(() => (0, contract_source_1.generateContractDeclaration)({ contract, tables }, { from: "x", exportName: "not ok" })).toThrow(/usable export name/);
+    for (const exportName of ["class", "z", "declareContract", "AccessLevel"]) {
+        expect(() => (0, contract_source_1.generateContractDeclaration)({ contract, tables }, { from: "x", exportName })).toThrow(/usable export name/);
+    }
+    for (const exportName of ["$", "_"]) {
+        const generated = (0, contract_source_1.generateContractDeclaration)({ contract, tables }, { from: "x", exportName });
+        const file = path.join(root, `src/${exportName}.ts`);
+        await (0, promises_1.writeFile)(file, generated.source);
+        expect(await irOf(file, exportName)).toEqual({ contract, tables });
+    }
+    await expect((0, contract_add_1.addContract)({ source: `${path.join(root, "src/rich.ts")}#Missing`, root })).rejects.toThrow(/exports no declaration or contract named Missing/);
+});
+test("hand-written IR survives generation, including stored defaults, blobs and opaque objects", async () => {
+    const fields = [
+        { name: "key", type: field_type_1.FieldType.id, subType: "record" },
+        { name: "selectedId", type: field_type_1.FieldType.id, enumValues: [contractId] },
+        { name: "bytes", type: field_type_1.FieldType.blob },
+        { name: "opaque", type: field_type_1.FieldType.object },
+        { name: "literal", type: field_type_1.FieldType.any, enumValues: ["only"] },
+        { name: "repeated", type: field_type_1.FieldType.string, enumValues: ["same", "same"] },
+        { name: "flag", type: field_type_1.FieldType.boolean, enumValues: [true, false] },
+        { name: "oneFlag", type: field_type_1.FieldType.boolean, enumValues: [false, false] },
+        { name: "numericChoice", type: field_type_1.FieldType.number, enumValues: [1, 2] },
+        { name: "numericChoices", type: field_type_1.FieldType.number, enumValues: [1, 2], isArray: true },
+        {
+            name: "nestedChoice",
+            type: field_type_1.FieldType.object,
+            fields: [{ name: "choice", type: field_type_1.FieldType.number, enumValues: [1, 2], optional: true }],
+        },
+        { name: "count", type: field_type_1.FieldType.number, defaultValue: 5, optional: true },
+        { name: "requiredDefault", type: field_type_1.FieldType.number, defaultValue: 7 },
+        { name: "plainAny", type: field_type_1.FieldType.any },
+        { name: "anyItems", type: field_type_1.FieldType.any, isArray: true },
+        { name: "explicit", type: field_type_1.FieldType.string, optional: false, isArray: false, description: "" },
+        { name: "__proto__", type: field_type_1.FieldType.string },
+        {
+            name: "nested",
+            type: field_type_1.FieldType.object,
+            fields: [
+                { name: "answer", type: field_type_1.FieldType.number, defaultValue: 42 },
+                { name: "choice", type: field_type_1.FieldType.number, enumValues: [1, 2] },
+            ],
+            defaultValue: JSON.parse('{"answer":42,"choice":1,"__proto__":{"kept":true}}'),
+        },
+    ];
+    const source = {
+        contract: {
+            contractId,
+            version: 1,
+            name: "Stored Fields",
+            tools: [
+                {
+                    name: "go",
+                    usageDescription: "Go.",
+                    suggestedAccessLevel: 20,
+                    inputFields: fields,
+                    outputFields: fields,
+                },
+            ],
+            tables: [{ name: "Records" }],
+            events: [{ name: "changed", description: "Changed.", payloadFields: fields }],
+            observables: [
+                {
+                    name: "explicit",
+                    description: "Explicit flags.",
+                    valueType: field_type_1.FieldType.number,
+                    value: { type: field_type_1.FieldType.number, optional: false },
+                    writable: false,
+                },
+            ],
+        },
+        tables: [{ name: "Records", description: "Records.", primaryKeyName: "key", fields }],
+    };
+    const generated = (0, contract_source_1.generateContractDeclaration)(source, { from: "manifest.json" });
+    const file = path.join(root, "src/stored.ts");
+    await (0, promises_1.writeFile)(file, generated.source);
+    const copy = await irOf(file, "StoredFields");
+    expect(copy).toEqual(source);
+    const types = path.join(root, "src/stored-types.ts");
+    await (0, promises_1.writeFile)(types, `
+    import type { StoredFieldsEvents, StoredFieldsRows } from "./stored";
+    // @ts-expect-error Required any fields still need a value.
+    export const missingEventValue: Pick<StoredFieldsEvents["changed"], "plainAny"> = {};
+    // @ts-expect-error Required any row fields still need a value.
+    export const missingRowValue: Pick<StoredFieldsRows["Records"], "plainAny"> = {};
+    export const event: Pick<StoredFieldsEvents["changed"], "plainAny"> = { plainAny: null };
+  `);
+    checkTypes(file, types);
+    const definitions = [source, copy].map(({ contract, tables }) => (0, isolated_artifact_1.isolatedContractToDefinition)(contract, tables));
+    expect((0, validate_1.validateImmutability)(definitions[0], definitions[1])).toEqual({ valid: true, errors: [] });
+    expect((0, validate_1.validateImmutability)(definitions[1], definitions[0])).toEqual({ valid: true, errors: [] });
+    const loaded = (await (0, build_package_1.loadPackageModule)(root, file));
+    const schema = loaded.StoredFields.declaration.tools[0].definition.inputSchema;
+    expect(schema.shape.bytes.safeParse(new Uint8Array([1, 2])).success).toBe(true);
+    expect(schema.shape.literal.safeParse("different").success).toBe(false);
+    expect(schema.shape.oneFlag.safeParse(false).success).toBe(true);
+    expect(schema.shape.oneFlag.safeParse(true).success).toBe(false);
+    expect(schema.shape.numericChoice.safeParse(3).success).toBe(false);
+    expect(schema.shape.numericChoices.safeParse([1, 2]).success).toBe(true);
+    expect(schema.pick({ plainAny: true }).safeParse({}).success).toBe(false);
+    expect(schema.shape.anyItems.safeParse([undefined, null, 1]).success).toBe(true);
+    expect(schema.shape.count.parse(undefined)).toBe(5);
+    expect(Object.hasOwn(schema.shape, "__proto__")).toBe(true);
+    expect(Object.hasOwn(schema.shape.nested._def.defaultValue(), "__proto__")).toBe(true);
+});
+test("source labels and member names stay data in generated TypeScript", async () => {
+    const { contract, tables } = await irOf(path.join(root, "src/rich.ts"), "Rich");
+    const named = {
+        ...contract,
+        observables: [
+            {
+                name: '*/\nthrow new Error("injected")\n/*',
+                description: "A value.",
+                valueType: field_type_1.FieldType.string,
+                writable: false,
+            },
+        ],
+    };
+    const generated = (0, contract_source_1.generateContractDeclaration)({ contract: named, tables }, { from: 'file\nthrow new Error("injected")\n//source' });
+    const file = path.join(root, "src/escaped.ts");
+    await (0, promises_1.writeFile)(file, generated.source);
+    expect((await irOf(file, "RichThings")).contract.observables).toEqual(named.observables);
+});
+test("selectors accept case-sensitive ids without rounding the version", () => {
+    const upper = contractId.toUpperCase();
+    expect((0, contract_source_1.parseContractSelector)(`${upper}@2`)).toEqual({ contractId: upper, version: 2 });
+    expect(() => (0, contract_source_1.parseContractSelector)(`${contractId}@9007199254740993`)).toThrow(/Expected/);
+});
+test("JSON sources cannot inject code or paths through numeric metadata", async () => {
+    const { contract, tables } = await irOf(path.join(root, "src/rich.ts"), "Rich");
+    const injected = '1, injected: (() => { throw new Error("injected"); })()';
+    const source = path.join(root, "unsafe.json");
+    const writeManifest = async (provided, definitions) => (0, promises_1.writeFile)(source, JSON.stringify({ provides: [provided], tables: definitions }));
+    for (const version of [injected, "../../outside", 0, 1.5, Number.MAX_SAFE_INTEGER + 1]) {
+        await writeManifest({ ...contract, version }, tables);
+        await expect((0, contract_add_1.addContract)({ source, root })).rejects.toThrow(/contract version/i);
+    }
+    for (const key of ["suggestedAccessLevel", "remoteAccessLevel"]) {
+        for (const level of [injected, -1, 101, 1.5]) {
+            await writeManifest({ ...contract, tools: [{ ...contract.tools[0], [key]: level }] }, tables);
+            await expect((0, contract_add_1.addContract)({ source, root })).rejects.toThrow(/access level/i);
+        }
+    }
+    await writeManifest(contract, [{ ...tables[0], versionNumber: injected }]);
+    await expect((0, contract_add_1.addContract)({ source, root })).rejects.toThrow(/table version/i);
+    await (0, promises_1.writeFile)(source, JSON.stringify({
+        definition: { ...(0, isolated_artifact_1.isolatedContractToDefinition)(contract, tables), version: injected },
+        tools: contract.tools.map((tool) => ({ name: tool.name, accessLevel: 20 })),
+    }));
+    await expect((0, contract_add_1.addContract)({ source, root })).rejects.toThrow(/contract version/i);
+    await expect((0, promises_1.readFile)(path.join(root, "src/contracts/rich-things.v2.ts"))).rejects.toMatchObject({
+        code: "ENOENT",
+    });
+});

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

@@ -0,0 +1,59 @@
+import type { IContractDefinitionWithPolicy } from "../contracts/system/contract-catalog-contract";
+import type { IIsolatedPackageManifest, IIsolatedPackageTable, IIsolatedProvidedContract } from "../package-loader/isolated-artifact";
+/** A contract as the generator reads it: its manifest entry and its tables' definitions. */
+export interface IContractSource {
+    /** The contract, as a provider's manifest carries it. */
+    contract: IIsolatedProvidedContract;
+    /** Definitions of the tables the contract exposes. */
+    tables: IIsolatedPackageTable[];
+}
+/** A generated declaration file. */
+export interface IGeneratedContractDeclaration {
+    /** File name: the contract's name in kebab case and its version (`voice-skill.v1.ts`). */
+    fileName: string;
+    /** The declaration's export name (`VoiceSkill`). */
+    exportName: string;
+    /** TypeScript source, before formatting. */
+    source: string;
+}
+/**
+ * The contract in a provider's manifest, by `contractId@version` (or the only one).
+ *
+ * @param manifest - A package's manifest.
+ * @param selector - `contractId@version`; optional when the package provides one contract.
+ */
+export declare function contractSourceFromManifest(manifest: IIsolatedPackageManifest, selector?: string): IContractSource;
+/**
+ * A registered contract definition, with the active provider's tool policy, as the generator
+ * reads it.
+ *
+ * @param input - `getContractDefinition`'s result.
+ */
+export declare function contractSourceFromDefinition(input: IContractDefinitionWithPolicy): IContractSource;
+/**
+ * Parse `contractId@version`.
+ *
+ * @param selector - The contract's id and version.
+ */
+export declare function parseContractSelector(selector: string): {
+    contractId: string;
+    version: number;
+};
+/**
+ * Write a contract's declaration as TypeScript: a `declareContract(...)` call whose zod schemas
+ * give the same IR, for a package that implements or calls a contract it doesn't own. The file
+ * is meant to be checked in and regenerated, not edited.
+ *
+ * What the IR carries comes through: names, types, optional fields, arrays, nested object
+ * fields, enum and literal values, descriptions, and each tool's access level and authority
+ * propagation. Refinements (a regex, a minimum) and defaults made by code aren't in the IR, so
+ * generated schemas check only what the IR describes. Objects keep keys their fields don't list.
+ *
+ * @param input - The contract and its tables.
+ * @param options - Where it came from (for the file's header), and an export name to use
+ *   instead of the one made from the contract's name.
+ */
+export declare function generateContractDeclaration(input: IContractSource, options: {
+    from: string;
+    exportName?: string;
+}): IGeneratedContractDeclaration;