@zocomputer/system-api 0.0.0-stage → 0.1.1

package/dist/generate/cli.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/**
+ * `zo-system-api` — the offline typed-client generator CLI.
+ *
+ *   zo-system-api generate --out <dir> --base-url <url>
+ *       [--workspace <id>] [--catalog <mode>] [--from <schema.json>] [--check]
+ *
+ * Fetches the authorized catalog export from `<base-url>/catalog/export` (or
+ * reads it from `--from` for offline regeneration), renders the five-file typed
+ * client bundle, and writes it atomically into `--out`. `--check` writes nothing
+ * and exits non-zero if the on-disk bundle differs from what would be generated.
+ *
+ * The access token is read from `ZO_SYSTEM_API_ACCESS_TOKEN`, or from stdin when
+ * that variable is unset. The token, the base URL, and any fetched identifiers
+ * are never written to stdout: on success the CLI prints only a file count and
+ * the output directory.
+ */
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { argv } from "node:process";
+import { fileURLToPath } from "node:url";
+import { BUNDLE_FILE_NAMES, generateBundle } from "./index.js";
+/** A CLI usage or runtime failure whose message is safe to print. */
+class CliError extends Error {
+}
+/**
+ * Client ceiling on the catalog export response, mirroring the service's export
+ * byte bound. A stalled or hostile endpoint cannot make the CLI buffer without
+ * limit: the response body is counted while streaming and aborted past this.
+ */
+const MAX_EXPORT_BYTES = 4 * 1024 * 1024;
+/**
+ * Client deadline for the export request. The service bounds its own work at 90s
+ * (MAX_REQUEST_SECONDS); this leaves margin for the round trip, but a truly
+ * stalled endpoint can never hang the CLI forever.
+ */
+const EXPORT_TIMEOUT_MS = 120_000;
+function parseArgs(argv) {
+    const flags = new Map();
+    let check = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--check") {
+            check = true;
+            continue;
+        }
+        if (!arg.startsWith("--"))
+            throw new CliError(`unexpected argument: ${arg}`);
+        const key = arg.slice(2);
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith("--"))
+            throw new CliError(`flag --${key} requires a value`);
+        flags.set(key, value);
+        i += 1;
+    }
+    const known = new Set(["out", "base-url", "workspace", "catalog", "from"]);
+    for (const key of flags.keys())
+        if (!known.has(key))
+            throw new CliError(`unknown flag --${key}`);
+    const out = flags.get("out");
+    if (out === undefined)
+        throw new CliError("--out <dir> is required");
+    const from = flags.get("from");
+    const baseUrl = flags.get("base-url");
+    if (from === undefined && baseUrl === undefined)
+        throw new CliError("one of --base-url <url> or --from <file> is required");
+    // The two sources are mutually exclusive: accepting both and silently
+    // preferring one could make a release command appear to fetch the current
+    // authorized contract while actually regenerating from a stale local file.
+    if (from !== undefined && baseUrl !== undefined)
+        throw new CliError("--from and --base-url are mutually exclusive: pass exactly one source");
+    return {
+        out,
+        baseUrl,
+        workspace: flags.get("workspace"),
+        catalog: flags.get("catalog"),
+        from,
+        check,
+    };
+}
+/**
+ * Validate the base URL as a credential-bearing endpoint: HTTPS, or explicit
+ * loopback HTTP for local/integration use. Reject any other scheme, non-loopback
+ * HTTP, and any userinfo, query, or fragment — a bearer token must never be able
+ * to ride along in the URL, and the endpoint must not carry hidden state.
+ */
+function validateBaseUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new CliError("--base-url is not a valid URL");
+    }
+    if (url.username !== "" || url.password !== "")
+        throw new CliError("--base-url must not contain a username or password");
+    if (url.search !== "")
+        throw new CliError("--base-url must not contain a query string");
+    if (url.hash !== "")
+        throw new CliError("--base-url must not contain a fragment");
+    const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+    const isLoopback = loopbackHosts.has(url.hostname);
+    if (url.protocol === "https:")
+        return url;
+    if (url.protocol === "http:" && isLoopback)
+        return url;
+    if (url.protocol === "http:")
+        throw new CliError("--base-url must use https except for loopback (localhost/127.0.0.1/[::1])");
+    throw new CliError(`--base-url must use https, not ${url.protocol}`);
+}
+/** Read the access token from the environment, falling back to stdin. */
+async function readToken() {
+    const fromEnv = process.env["ZO_SYSTEM_API_ACCESS_TOKEN"];
+    if (fromEnv !== undefined && fromEnv.trim() !== "")
+        return fromEnv.trim();
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const token = Buffer.concat(chunks).toString("utf8").trim();
+    if (token === "")
+        throw new CliError("no access token: set ZO_SYSTEM_API_ACCESS_TOKEN or pipe the token on stdin");
+    return token;
+}
+async function fetchExport(baseUrl, workspace, catalog, token, options = {}) {
+    const timeoutMs = options.timeoutMs ?? EXPORT_TIMEOUT_MS;
+    const maxBytes = options.maxBytes ?? MAX_EXPORT_BYTES;
+    const endpoint = new URL("catalog/export", ensureTrailingSlash(baseUrl));
+    endpoint.searchParams.set("workspace_id", workspace);
+    if (catalog !== undefined)
+        endpoint.searchParams.set("catalog", catalog);
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+            redirect: "manual",
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (error) {
+        if (error.name === "TimeoutError")
+            throw new CliError(`catalog export request timed out after ${timeoutMs / 1000}s`);
+        throw new CliError(`could not reach the catalog export endpoint: ${error.message}`);
+    }
+    // With redirect:"manual", undici surfaces a 3xx as an opaque redirect: refuse
+    // it rather than let fetch resend the Authorization header to a new origin.
+    if (response.type === "opaqueredirect" ||
+        (response.status >= 300 && response.status < 400))
+        throw new CliError("catalog export endpoint returned a redirect; refusing to follow it");
+    if (!response.ok)
+        throw new CliError(`catalog export request failed with HTTP ${response.status}`);
+    return readBounded(response, maxBytes);
+}
+/** Read a response body into memory, aborting if it exceeds `max` bytes. */
+async function readBounded(response, max) {
+    const body = response.body;
+    if (body === null) {
+        const buffered = new Uint8Array(await response.arrayBuffer());
+        if (buffered.byteLength > max)
+            throw new CliError(`catalog export exceeded the ${max}-byte limit`);
+        return buffered;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > max) {
+            await reader.cancel();
+            throw new CliError(`catalog export exceeded the ${max}-byte limit`);
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+function ensureTrailingSlash(url) {
+    if (url.pathname.endsWith("/"))
+        return url;
+    const copy = new URL(url.href);
+    copy.pathname = `${url.pathname}/`;
+    return copy;
+}
+function toBytes(content) {
+    return typeof content === "string"
+        ? new TextEncoder().encode(content)
+        : content;
+}
+function digest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Compare the generated bundle to the on-disk directory; return changed files. */
+async function diffBundle(outDir, files) {
+    const changed = [];
+    for (const name of BUNDLE_FILE_NAMES) {
+        const target = join(outDir, name);
+        const next = toBytes(files[name]);
+        if (!existsSync(target)) {
+            changed.push(name);
+            continue;
+        }
+        const current = new Uint8Array(await readFile(target));
+        if (digest(current) !== digest(next))
+            changed.push(name);
+    }
+    // A stray extra file in the bundle directory is also drift.
+    if (existsSync(outDir))
+        for (const entry of readdirSync(outDir))
+            if (!BUNDLE_FILE_NAMES.includes(entry))
+                changed.push(entry);
+    return changed;
+}
+/**
+ * Write the bundle into `outDir`, replacing it atomically at the directory
+ * boundary: stage every file in a sibling temp directory, then swap it into
+ * place, so a reader never sees a half-written mix of old and new files.
+ */
+async function writeBundleAtomically(outDir, files, deps = { rename }) {
+    // Restore uses the real rename by default so a test that injects a failing
+    // `rename` to simulate an install failure does not also sabotage the rollback;
+    // it is separately injectable to exercise the both-fail data-loss guard.
+    const restore = deps.restore ?? rename;
+    const parent = dirname(outDir);
+    await mkdir(parent, { recursive: true });
+    const suffix = `${process.pid}-${Date.now().toString(36)}`;
+    const stage = join(parent, `.zo-system-api-${suffix}`);
+    await mkdir(stage, { recursive: true });
+    const old = existsSync(outDir)
+        ? join(parent, `.zo-system-api-old-${suffix}`)
+        : undefined;
+    // True only while the moved-aside old bundle is the sole surviving copy of the
+    // output — install failed AND restore failed. While it holds, the backup must
+    // never be deleted: that would turn a failed regeneration into data loss. It is
+    // cleared the moment the new bundle installs or the old one is restored.
+    let oldIsOnlyCopy = false;
+    try {
+        for (const name of BUNDLE_FILE_NAMES)
+            await writeFile(join(stage, name), toBytes(files[name]));
+        if (old) {
+            await deps.rename(outDir, old);
+            oldIsOnlyCopy = true;
+        }
+        try {
+            await deps.rename(stage, outDir);
+            oldIsOnlyCopy = false;
+        }
+        catch (installError) {
+            // Installing the new bundle failed after moving the old one aside; restore
+            // it so the caller is never left with a missing output and a stray backup.
+            // If the restore itself fails, the moved-aside bundle is the only copy left
+            // — keep it (oldIsOnlyCopy stays true) so the cleanup below never drops it.
+            if (old && !existsSync(outDir)) {
+                try {
+                    await restore(old, outDir);
+                    oldIsOnlyCopy = false;
+                }
+                catch {
+                    // Restore failed; the backup is the only surviving copy. Leave it.
+                }
+            }
+            throw installError;
+        }
+        if (old)
+            await rm(old, { recursive: true, force: true });
+    }
+    finally {
+        await rm(stage, { recursive: true, force: true });
+        if (old && !oldIsOnlyCopy)
+            await rm(old, { recursive: true, force: true });
+    }
+}
+async function runGenerate(args) {
+    let schemaBytes;
+    if (args.from !== undefined) {
+        schemaBytes = new Uint8Array(readFileSync(resolve(args.from)));
+    }
+    else {
+        const baseUrl = validateBaseUrl(args.baseUrl);
+        if (args.workspace === undefined || args.workspace === "")
+            throw new CliError("--workspace <id> is required when fetching from --base-url");
+        schemaBytes = await fetchExport(baseUrl, args.workspace, args.catalog, await readToken());
+    }
+    // generateBundle snapshots schemaBytes and derives the model internally, so the
+    // emitted types and persisted schema.json always come from one immutable source.
+    // The requested selection is verified against the export's own echo inside
+    // generateBundle; it never fabricates provenance. Empty fields are not checked.
+    const { files } = await generateBundle({
+        schemaBytes,
+        selection: {
+            workspace: args.workspace ?? "",
+            catalog: args.catalog ?? "",
+        },
+    });
+    const outDir = resolve(args.out);
+    if (args.check) {
+        const changed = await diffBundle(outDir, files);
+        if (changed.length === 0) {
+            process.stdout.write("Bundle is up to date.\n");
+            return 0;
+        }
+        process.stdout.write(`Bundle is out of date; ${changed.length} file(s) differ: ${changed
+            .sort()
+            .join(", ")}\n`);
+        return 1;
+    }
+    await writeBundleAtomically(outDir, files);
+    process.stdout.write(`Wrote ${BUNDLE_FILE_NAMES.length} files to ${args.out}\n`);
+    return 0;
+}
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "--help" || command === "-h") {
+        process.stdout.write("Usage: zo-system-api generate --out <dir> --base-url <url> " +
+            "[--workspace <id>] [--catalog <mode>] [--from <file>] [--check]\n");
+        return command === undefined ? 1 : 0;
+    }
+    if (command !== "generate")
+        throw new CliError(`unknown command: ${command}`);
+    return runGenerate(parseArgs(rest));
+}
+/** True when this module is the process entry point (run as the `zo-system-api` bin). */
+function isMainEntry() {
+    const entry = argv[1];
+    if (entry === undefined)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainEntry())
+    main(argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((error) => {
+        const message = error instanceof CliError
+            ? error.message
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        process.stderr.write(`zo-system-api: ${message}\n`);
+        process.exitCode = 1;
+    });
+// Exported for tests and the programmatic path; `main` runs only as the bin entry.
+export { fetchExport, main, parseArgs, readToken, validateBaseUrl, writeBundleAtomically, };

package/dist/generate/generate.d.ts

@@ -0,0 +1,46 @@
+/** The generator version stamped into every emitted catalog and manifest. */
+export declare const GENERATOR_VERSION = "0.1.0";
+/** The file names in the generated bundle, in a stable order. */
+export declare const BUNDLE_FILE_NAMES: readonly ["index.ts", "operations.ts", "catalog.ts", "schema.json", "manifest.json"];
+/**
+ * The selection the caller asked for, used only to *verify* against the service's
+ * own echo — never to fabricate provenance. Fields left empty are not checked.
+ * Deliberately excludes the service URL: the base URL carries the bearer token
+ * and may be an internal host, and persisting it would make two identical
+ * authorized exports differ by endpoint.
+ */
+export interface CatalogSelection {
+    readonly workspace: string;
+    readonly catalog: string;
+}
+/** Everything the orchestrator needs to emit a bundle. */
+export interface GenerateInput {
+    /**
+     * The exact catalog export bytes: the single source of truth. The generator
+     * snapshots these before any async work and derives the {@link NormalizedCatalog}
+     * from the same snapshot it persists as `schema.json` and digests, so the
+     * emitted types can never describe a different export than the one recorded.
+     */
+    readonly schemaBytes: Uint8Array;
+    /**
+     * The selection the caller requested, verified against the export's own echo.
+     * Optional: the builtin export carries no selection, so there is nothing to
+     * record or verify. Recorded provenance always comes from the export itself.
+     */
+    readonly selection?: CatalogSelection;
+}
+/**
+ * The emitted bundle: `schema.json` is exact bytes, every other file is text.
+ * Keys are exactly {@link BUNDLE_FILE_NAMES}.
+ */
+export interface GeneratedBundle {
+    readonly files: {
+        readonly "index.ts": string;
+        readonly "operations.ts": string;
+        readonly "catalog.ts": string;
+        readonly "schema.json": Uint8Array;
+        readonly "manifest.json": string;
+    };
+}
+/** Emit the full five-file bundle for one catalog. */
+export declare function generateBundle(input: GenerateInput): Promise<GeneratedBundle>;

package/dist/generate/generate.js

@@ -0,0 +1,215 @@
+/**
+ * The generation orchestrator: turn one normalized catalog export into the
+ * five-file typed-client bundle a consumer commits and imports.
+ *
+ * The bundle is deterministic and self-consistent:
+ *   - `operations.ts` — every operation Input/Output model and every resource
+ *     type, plus the `Operations` and `DefaultVersions` type maps.
+ *   - `catalog.ts` — the runtime `catalog` value (default-version pins and
+ *     per-version digests) built with `defineCatalog`, tied to the type maps.
+ *   - `index.ts` — the consumer entry that re-exports both.
+ *   - `schema.json` — the exact original export bytes (lossless; drives the
+ *     schema digest and offline regeneration).
+ *   - `manifest.json` — selection metadata, the generator version, and the
+ *     schema/bundle digests that identify this bundle.
+ *
+ * Every emitted type name is minted through one shared {@link NameRegistry}, so
+ * the independently compiled schemas never collide when concatenated.
+ */
+import { createHash } from "node:crypto";
+import { loadNormalizedCatalog } from "./manifest.js";
+import { operationTypeName, resourceTypeName } from "./identifiers.js";
+import { GeneratorError, NameRegistry, renderSchemaType } from "./types.js";
+/** The generator version stamped into every emitted catalog and manifest. */
+export const GENERATOR_VERSION = "0.1.0";
+/** Reserved top-level names the generator never assigns to a schema type. */
+const RESERVED_NAMES = ["Operations", "DefaultVersions"];
+/** The file names in the generated bundle, in a stable order. */
+export const BUNDLE_FILE_NAMES = [
+    "index.ts",
+    "operations.ts",
+    "catalog.ts",
+    "schema.json",
+    "manifest.json",
+];
+const BANNER = "// Generated by @zocomputer/system-api. Do not edit by hand.\n" +
+    "// Regenerate with the `zo-system-api generate` CLI.\n";
+function sha256Hex(...parts) {
+    const hash = createHash("sha256");
+    for (const part of parts)
+        hash.update(part);
+    return `sha256:${hash.digest("hex")}`;
+}
+/** Emit the full five-file bundle for one catalog. */
+export async function generateBundle(input) {
+    // One immutable source of truth: copy the export bytes before any async work,
+    // then derive the model from the same snapshot we persist and digest. The copy
+    // means a caller mutating its array mid-generation or after return cannot make
+    // the emitted types disagree with schema.json or the recorded digests.
+    const schemaBytes = input.schemaBytes.slice();
+    const { catalog } = loadNormalizedCatalog(schemaBytes);
+    // Provenance is the service's own selection echo, never fabricated from the
+    // caller's request. A requested selection, when given, only verifies the echo;
+    // a requested workspace/catalog with no echo to verify against is a mismatch,
+    // so a scoped request can never silently accept an unscoped/echoless export.
+    const echoed = catalog.selection;
+    const requested = input.selection;
+    if (requested !== undefined) {
+        const wantsWorkspace = requested.workspace !== "";
+        const wantsCatalog = requested.catalog !== "";
+        if ((wantsWorkspace || wantsCatalog) && echoed === undefined)
+            throw new GeneratorError(`a selection was requested (workspace '${requested.workspace}', ` +
+                `catalog '${requested.catalog}'), but the export carries no selection ` +
+                `echo to verify it against`);
+        if (echoed !== undefined) {
+            if (wantsWorkspace && requested.workspace !== echoed.workspace)
+                throw new GeneratorError(`requested workspace '${requested.workspace}' does not match the export's ` +
+                    `selection workspace '${echoed.workspace}'`);
+            if (wantsCatalog && requested.catalog !== echoed.catalog)
+                throw new GeneratorError(`requested catalog '${requested.catalog}' does not match the export's ` +
+                    `selection catalog '${echoed.catalog}'`);
+        }
+    }
+    const registry = new NameRegistry(RESERVED_NAMES);
+    const modelTexts = [];
+    let usesJsonValue = false;
+    // Assign a name to every operation model, in deterministic order.
+    const opNames = new Map();
+    for (const op of catalog.operations) {
+        for (const version of op.versions) {
+            const inKey = `op:${op.action}:${version.version}:Input`;
+            const outKey = `op:${op.action}:${version.version}:Output`;
+            const inName = registry.claim(inKey, operationTypeName(op.action, version.version, "Input"));
+            const outName = registry.claim(outKey, operationTypeName(op.action, version.version, "Output"));
+            const inRendered = await renderSchemaType(version.input, inName, inKey, registry, `${op.action} v${version.version} input`);
+            const outRendered = await renderSchemaType(version.output, outName, outKey, registry, `${op.action} v${version.version} output`);
+            usesJsonValue ||= inRendered.usesJsonValue || outRendered.usesJsonValue;
+            modelTexts.push(inRendered.text, outRendered.text);
+            let queryName;
+            if (version.query !== undefined) {
+                const queryKey = `op:${op.action}:${version.version}:Query`;
+                queryName = registry.claim(queryKey, operationTypeName(op.action, version.version, "Query"));
+                const queryRendered = await renderSchemaType(version.query, queryName, queryKey, registry, `${op.action} v${version.version} query`);
+                usesJsonValue ||= queryRendered.usesJsonValue;
+                modelTexts.push(queryRendered.text);
+            }
+            opNames.set(`${op.action}:${version.version}`, {
+                input: inName,
+                output: outName,
+                ...(queryName !== undefined ? { query: queryName } : {}),
+            });
+        }
+    }
+    // Assign a name to every resource type.
+    for (const resource of catalog.resourceTypes) {
+        const key = `res:${resource.type}:${resource.version}`;
+        const name = registry.claim(key, resourceTypeName(resource.type, resource.version));
+        const rendered = await renderSchemaType(resource.propertiesSchema, name, key, registry, `resource ${resource.type} v${resource.version}`);
+        usesJsonValue ||= rendered.usesJsonValue;
+        modelTexts.push(rendered.text);
+    }
+    const operationsFile = renderOperationsFile(catalog, opNames, modelTexts, usesJsonValue);
+    const catalogFile = renderCatalogFile(catalog);
+    const indexFile = renderIndexFile();
+    const schemaDigest = sha256Hex(schemaBytes);
+    const bundleDigest = sha256Hex(indexFile, "\0", operationsFile, "\0", catalogFile, "\0", schemaBytes);
+    const manifestFile = renderManifestFile(catalog, echoed, schemaDigest, bundleDigest);
+    return {
+        files: {
+            "index.ts": indexFile,
+            "operations.ts": operationsFile,
+            "catalog.ts": catalogFile,
+            "schema.json": schemaBytes,
+            "manifest.json": manifestFile,
+        },
+    };
+}
+function renderOperationsFile(catalog, opNames, modelTexts, usesJsonValue) {
+    const parts = [BANNER];
+    if (usesJsonValue)
+        parts.push('import type { JsonValue } from "@zocomputer/system-api/core";\n');
+    parts.push(modelTexts.join("\n\n"));
+    // The `Operations` type map: action → version → { input; output; query? },
+    // with `query` only for a version that declares list query options.
+    const opLines = ["export type Operations = {"];
+    for (const op of catalog.operations) {
+        opLines.push(`  ${JSON.stringify(op.action)}: {`);
+        for (const version of op.versions) {
+            const names = opNames.get(`${op.action}:${version.version}`);
+            const query = names.query !== undefined ? `; query: ${names.query}` : "";
+            opLines.push(`    ${version.version}: { input: ${names.input}; output: ${names.output}${query} };`);
+        }
+        opLines.push("  };");
+    }
+    opLines.push("};");
+    parts.push(opLines.join("\n"));
+    // The `DefaultVersions` type map: action → its default version. Only actions
+    // with an eligible pin appear; a visible but unpinned action is omitted, so a
+    // typed call against it requires an explicit version.
+    const defLines = ["export type DefaultVersions = {"];
+    for (const op of catalog.operations)
+        if (op.defaultVersion !== undefined)
+            defLines.push(`  ${JSON.stringify(op.action)}: ${op.defaultVersion};`);
+    defLines.push("};");
+    parts.push(defLines.join("\n"));
+    return `${parts.join("\n\n")}\n`;
+}
+function renderCatalogFile(catalog) {
+    const lines = [
+        BANNER,
+        // Generated for a NodeNext consumer without allowImportingTsExtensions:
+        // emit `.js` specifiers, which resolve to the sibling `.ts` at compile time.
+        'import { defineCatalog } from "@zocomputer/system-api/core";\n' +
+            'import type { DefaultVersions, Operations } from "./operations.js";',
+        "",
+        "export const catalog = defineCatalog<Operations, DefaultVersions>({",
+        `  generatorVersion: ${JSON.stringify(GENERATOR_VERSION)},`,
+        "  actions: {",
+    ];
+    for (const op of catalog.operations) {
+        lines.push(`    ${JSON.stringify(op.action)}: {`);
+        // Omit the field for an unpinned action: TypedActions forbids a numeric
+        // default there, and the runtime rejects an omitted version for it.
+        if (op.defaultVersion !== undefined)
+            lines.push(`      defaultVersion: ${op.defaultVersion},`);
+        lines.push("      versions: {");
+        for (const version of op.versions)
+            lines.push(`        ${version.version}: { digest: ${JSON.stringify(version.digest)} },`);
+        lines.push("      },");
+        lines.push("    },");
+    }
+    lines.push("  },");
+    lines.push("});");
+    return `${lines.join("\n")}\n`;
+}
+function renderIndexFile() {
+    return (`${BANNER}\n` +
+        'export * from "./operations.js";\n' +
+        'export { catalog } from "./catalog.js";\n');
+}
+function renderManifestFile(catalog, echoed, schemaDigest, bundleDigest) {
+    const manifest = {
+        generatorVersion: GENERATOR_VERSION,
+        // Provenance from the export itself only: the selection the service echoed
+        // (absent for the builtin export) and its canonical digest, never the
+        // caller's request or the service URL.
+        ...(echoed !== undefined
+            ? { selection: { workspace: echoed.workspace, catalog: echoed.catalog } }
+            : {}),
+        ...(catalog.catalogDigest !== undefined
+            ? { catalogDigest: catalog.catalogDigest }
+            : {}),
+        schemaDigest,
+        bundleDigest,
+        actions: catalog.operations.flatMap((op) => op.versions.map((v) => ({
+            action: op.action,
+            version: v.version,
+            digest: v.digest,
+        }))),
+        resourceTypes: catalog.resourceTypes.map((r) => ({
+            type: r.type,
+            version: r.version,
+        })),
+    };
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}

package/dist/generate/identifiers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Deterministic, collision-safe TypeScript identifiers and sanitized doc text
+ * for generated output. Schema data is never code: a generated type name is
+ * derived only from a safe character class, and documentation text is
+ * neutralized so it can never terminate a comment or inject TypeScript.
+ */
+/**
+ * PascalCase a raw token from its alphanumeric runs. Non-alphanumeric
+ * characters (dots, dashes, underscores, anything else) are treated as segment
+ * separators, so `zo.machine.read_file` becomes `ZoMachineReadFile`. A leading
+ * digit run is prefixed with `_` so the result is a valid identifier head.
+ */
+export declare function pascalCase(raw: string): string;
+/**
+ * Type name for an action's input or output at a version:
+ * `("zo.machine.read_file", 1, "Input")` → `ZoMachineReadFileInputV1`.
+ */
+export declare function operationTypeName(action: string, version: number, kind: "Input" | "Output" | "Query"): string;
+/** Type name for a resource type: `("machine", 1)` → `MachineV1`. */
+export declare function resourceTypeName(type: string, version: number): string;
+/**
+ * Neutralize free-form documentation text so it is safe inside a `/** … *\/`
+ * block: drop control characters (except newline/tab), collapse the comment
+ * terminator `*\/`, and bound the length. The result contains no sequence that
+ * can close the comment or start a new syntactic construct.
+ */
+export declare function sanitizeDoc(text: string): string;