@zocomputer/system-api 0.0.0-stage → 0.1.0

package/dist/generate/identifiers.js

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+/** Longest doc-comment body kept per node; longer text is truncated with an ellipsis. */
+const MAX_DOC_LENGTH = 4096;
+/**
+ * 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 function pascalCase(raw) {
+    const segments = raw.split(/[^A-Za-z0-9]+/).filter((s) => s.length > 0);
+    const joined = segments
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+        .join("");
+    if (joined.length === 0)
+        return "_";
+    return /^[0-9]/.test(joined) ? `_${joined}` : joined;
+}
+/**
+ * Type name for an action's input or output at a version:
+ * `("zo.machine.read_file", 1, "Input")` → `ZoMachineReadFileInputV1`.
+ */
+export function operationTypeName(action, version, kind) {
+    return `${pascalCase(action)}${kind}V${version}`;
+}
+/** Type name for a resource type: `("machine", 1)` → `MachineV1`. */
+export function resourceTypeName(type, version) {
+    return `${pascalCase(type)}V${version}`;
+}
+/**
+ * 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 function sanitizeDoc(text) {
+    // Strip C0/C1 control characters other than newline and tab; they have no
+    // place in a comment and can confuse editors and tooling.
+    let out = "";
+    for (const ch of text) {
+        const code = ch.codePointAt(0);
+        if (code === 0x09 || code === 0x0a) {
+            out += ch;
+        }
+        else if (code < 0x20 || (code >= 0x7f && code <= 0x9f)) {
+            // drop
+        }
+        else {
+            out += ch;
+        }
+    }
+    // Neutralize the comment terminator anywhere it appears (including a `*` and
+    // `/` split across sanitization) so the doc text cannot close the block.
+    out = out.replace(/\*\//g, "*​/");
+    // Bound the length in Unicode code points, matching the server/SDK annotation
+    // bound. A UTF-16 `.length`/`.slice` would truncate a valid astral-character
+    // description early and could split a surrogate pair, emitting U+FFFD.
+    const points = Array.from(out);
+    if (points.length > MAX_DOC_LENGTH)
+        out = points.slice(0, MAX_DOC_LENGTH).join("") + "…";
+    return out;
+}

package/dist/generate/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@zocomputer/system-api/generate` — the programmatic generator entry.
+ *
+ * Exposes the pure generation pipeline (parse a normalized catalog export →
+ * emit the five-file typed-client bundle) without the CLI's I/O. A caller that
+ * already has the export bytes can drive generation directly; the
+ * `zo-system-api` CLI is a thin wrapper over this surface.
+ *
+ * This entry pulls in json-schema-to-typescript and its dependencies, so a
+ * runtime consumer of the generated client never imports it — it lives behind
+ * this separate specifier, distinct from the dependency-light `.` and `./core`.
+ */
+export { BUNDLE_FILE_NAMES, GENERATOR_VERSION, generateBundle, type CatalogSelection, type GenerateInput, type GeneratedBundle, } from "./generate.ts";
+export { CatalogFormatError, loadNormalizedCatalog, parseNormalizedCatalog, toPlainJson, type CatalogSelectionEcho, type NormalizedCatalog, type OperationEntry, type OperationVersion, type ResourceTypeEntry, } from "./manifest.ts";
+export { GeneratorError } from "./types.ts";

package/dist/generate/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@zocomputer/system-api/generate` — the programmatic generator entry.
+ *
+ * Exposes the pure generation pipeline (parse a normalized catalog export →
+ * emit the five-file typed-client bundle) without the CLI's I/O. A caller that
+ * already has the export bytes can drive generation directly; the
+ * `zo-system-api` CLI is a thin wrapper over this surface.
+ *
+ * This entry pulls in json-schema-to-typescript and its dependencies, so a
+ * runtime consumer of the generated client never imports it — it lives behind
+ * this separate specifier, distinct from the dependency-light `.` and `./core`.
+ */
+export { BUNDLE_FILE_NAMES, GENERATOR_VERSION, generateBundle, } from "./generate.js";
+export { CatalogFormatError, loadNormalizedCatalog, parseNormalizedCatalog, toPlainJson, } from "./manifest.js";
+export { GeneratorError } from "./types.js";

package/dist/generate/manifest.d.ts

@@ -0,0 +1 @@
+export * from "../catalog/index.ts";

package/dist/generate/manifest.js

@@ -0,0 +1 @@
+export * from "../catalog/index.js";

package/dist/generate/types.d.ts

@@ -0,0 +1,57 @@
+import { type JsonValue } from "../validation/json.ts";
+/** Thrown when a schema cannot be rendered to safe, exact TypeScript. */
+export declare class GeneratorError extends Error {
+    constructor(message: string);
+}
+/**
+ * A single, deterministic, collision-proof registry of every top-level
+ * TypeScript name the generator emits. `claim` is idempotent per source: the
+ * same `sourceKey` always returns the same name, and two distinct sources that
+ * want the same base name are separated by a content-addressed suffix derived
+ * from the losing source's identity.
+ */
+export declare class NameRegistry {
+    private readonly used;
+    private readonly assigned;
+    constructor(reserved?: Iterable<string>);
+    /** True if `name` is already taken (reserved or claimed). */
+    has(name: string): boolean;
+    /**
+     * Return the unique name for `sourceKey`, minting it on first request.
+     * `desiredBase` must be a valid identifier; if it is free the source keeps it,
+     * otherwise the source receives `${desiredBase}_${hash}` with the shortest
+     * hash prefix that is free (extended, then counter-suffixed, only in the
+     * astronomically unlikely event of a further clash).
+     */
+    claim(sourceKey: string, desiredBase: string): string;
+}
+/**
+ * Fail if any numeric `enum`/`const` literal in the (lossless) schema would
+ * change value when represented as a JS `number`. Those keywords become emitted
+ * TypeScript literal types, so a silent round would make the generated type
+ * disagree with the contract; the author must string-encode such a value
+ * instead. Only `enum`/`const` are checked — other numeric keywords never become
+ * literal types.
+ */
+export declare function assertRenderableLiterals(schema: JsonValue, where: string): void;
+/** The result of rendering one schema: emitted text and whether it used JsonValue. */
+export interface RenderedType {
+    readonly text: string;
+    readonly usesJsonValue: boolean;
+}
+/**
+ * Render one admitted schema to a named TypeScript declaration (plus its
+ * reachable `$defs` interfaces). `rootName` must already be a registry-minted
+ * name; `rootSourceKey` scopes this schema's `$defs` names within the registry.
+ */
+export declare function renderSchemaType(schema: JsonValue, rootName: string, rootSourceKey: string, registry: NameRegistry, where: string): Promise<RenderedType>;
+/**
+ * Lexically scan `text` for a bare `any` type token. This is comment- and
+ * string-aware: an `any` inside a line/block comment or a quoted string
+ * (including an `enum`/`const` value literally `"any"`) is skipped, and a `//`
+ * or `/*` inside a string literal is not mistaken for a comment. An `any`
+ * identifier immediately followed (past whitespace) by `:` or `?` is a property
+ * name, not the `any` type, so it is ignored; any other bare `any` token in code
+ * is a real `any` type.
+ */
+export declare function containsAnyType(text: string): boolean;

package/dist/generate/types.js

@@ -0,0 +1,357 @@
+/**
+ * The schema → TypeScript renderer: turn one admitted Zo-dialect schema into a
+ * named, collision-safe TypeScript declaration.
+ *
+ * Every emitted top-level name — an operation's Input/Output type, a resource
+ * type, and every `$defs` interface reachable from a schema — is minted through
+ * one shared {@link NameRegistry}, so independently compiled schemas can be
+ * concatenated without ever colliding or relying on TypeScript interface
+ * merging (which would silently union two unrelated shapes). Naming is fully
+ * deterministic: the first claimant of a base name in a fixed traversal order
+ * keeps the clean name; a distinct later claimant gets a content-addressed
+ * suffix.
+ *
+ * The pipeline per schema:
+ *   1. Admit through the SDK's own {@link compileSchema} — the authoritative
+ *      "supported dialect" gate. A schema it rejects is rejected here too; we
+ *      never fall back to emitting `any`.
+ *   2. Guard emitted literals: a numeric `enum`/`const` becomes a TypeScript
+ *      literal type, so it must fail loudly (not silently round) when the value
+ *      is not representable as a JS number. Ordinary bounds
+ *      (minimum/maximum/multipleOf) are type-level metadata TypeScript ignores,
+ *      so they may round harmlessly.
+ *   3. Project the lossless tree to plain JSON, then rewrite it for the
+ *      compiler: strip every `title` (forcing anonymous inlining of nested
+ *      objects so only registry-named declarations survive), rename `$defs`
+ *      keys to registry names and rewrite `#/$defs/` refs, sanitize doc text,
+ *      and rewrite the `x-zo-json-value` marker to the SDK's `JsonValue` type.
+ *   4. Compile with json-schema-to-typescript and post-scan the output: any
+ *      `any` in a type position is a generator bug and throws.
+ */
+import { createHash } from "node:crypto";
+import Decimal from "decimal.js";
+import { compile } from "json-schema-to-typescript";
+import { JsonNumber } from "../validation/json.js";
+import { SchemaDefinitionError, compileSchema } from "../validation/schema.js";
+import { pascalCase, sanitizeDoc } from "./identifiers.js";
+import { toPlainJson } from "./manifest.js";
+/** The local-definition ref prefix, matching the validator's supported dialect. */
+const REF_PREFIX = "#/$defs/";
+/** Options passed to json-schema-to-typescript for every schema. */
+const COMPILE_OPTIONS = {
+    // We prepend our own file banner in the orchestrator; none per schema.
+    bannerComment: "",
+    // Emit every reachable `$defs` interface as its own top-level declaration
+    // (named by the registry) rather than inlining it.
+    declareExternallyReferenced: true,
+    // Objects without an explicit `additionalProperties` are closed; our exporter
+    // sets it explicitly anyway.
+    additionalProperties: false,
+    // Deterministic raw output; the orchestrator owns final formatting.
+    format: false,
+    // Unknown/empty schemas become `unknown`, never `any`.
+    unknownAny: true,
+    // No `$ref` fetching: our dialect is local-only, and network/file resolution
+    // must never happen during generation.
+    $refOptions: {},
+};
+/** Thrown when a schema cannot be rendered to safe, exact TypeScript. */
+export class GeneratorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GeneratorError";
+    }
+}
+/**
+ * A single, deterministic, collision-proof registry of every top-level
+ * TypeScript name the generator emits. `claim` is idempotent per source: the
+ * same `sourceKey` always returns the same name, and two distinct sources that
+ * want the same base name are separated by a content-addressed suffix derived
+ * from the losing source's identity.
+ */
+export class NameRegistry {
+    used = new Set();
+    assigned = new Map();
+    constructor(reserved = []) {
+        for (const name of reserved)
+            this.used.add(name);
+    }
+    /** True if `name` is already taken (reserved or claimed). */
+    has(name) {
+        return this.used.has(name);
+    }
+    /**
+     * Return the unique name for `sourceKey`, minting it on first request.
+     * `desiredBase` must be a valid identifier; if it is free the source keeps it,
+     * otherwise the source receives `${desiredBase}_${hash}` with the shortest
+     * hash prefix that is free (extended, then counter-suffixed, only in the
+     * astronomically unlikely event of a further clash).
+     */
+    claim(sourceKey, desiredBase) {
+        const prior = this.assigned.get(sourceKey);
+        if (prior !== undefined)
+            return prior;
+        let name = desiredBase;
+        if (this.used.has(name)) {
+            const digest = createHash("sha256").update(sourceKey).digest("hex");
+            let width = 8;
+            name = `${desiredBase}_${digest.slice(0, width)}`;
+            while (this.used.has(name)) {
+                width += 4;
+                if (width > digest.length) {
+                    let counter = 2;
+                    while (this.used.has(`${desiredBase}_${digest}_${counter}`))
+                        counter += 1;
+                    name = `${desiredBase}_${digest}_${counter}`;
+                    break;
+                }
+                name = `${desiredBase}_${digest.slice(0, width)}`;
+            }
+        }
+        this.used.add(name);
+        this.assigned.set(sourceKey, name);
+        return name;
+    }
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Fail if any numeric `enum`/`const` literal in the (lossless) schema would
+ * change value when represented as a JS `number`. Those keywords become emitted
+ * TypeScript literal types, so a silent round would make the generated type
+ * disagree with the contract; the author must string-encode such a value
+ * instead. Only `enum`/`const` are checked — other numeric keywords never become
+ * literal types.
+ */
+export function assertRenderableLiterals(schema, where) {
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        if (!isObjectTree(node))
+            return;
+        if ("const" in node)
+            assertJsSafeNumbers(node["const"], where, "const");
+        if ("enum" in node) {
+            const values = node["enum"];
+            if (Array.isArray(values))
+                for (const value of values)
+                    assertJsSafeNumbers(value, where, "enum");
+        }
+        // Recurse only through schema-bearing positions of the supported dialect, so
+        // a data value under `default`/`examples` is never mistaken for a keyword.
+        for (const key of ["items", "additionalProperties"])
+            if (key in node)
+                visit(node[key]);
+        for (const key of ["anyOf", "oneOf"]) {
+            const branches = node[key];
+            if (Array.isArray(branches))
+                for (const branch of branches)
+                    visit(branch);
+        }
+        for (const key of ["properties", "$defs"]) {
+            const holder = node[key];
+            if (isObjectTree(holder))
+                for (const child of Object.values(holder))
+                    visit(child);
+        }
+    };
+    visit(schema);
+}
+function isObjectTree(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof JsonNumber));
+}
+/** Deep-check every number inside an `enum`/`const` value for JS-safety. */
+function assertJsSafeNumbers(value, where, keyword) {
+    if (value instanceof JsonNumber) {
+        const text = value.text;
+        if (!new Decimal(text).equals(new Decimal(Number(text))))
+            throw new GeneratorError(`${where}: numeric ${keyword} value ${text} is not representable as a ` +
+                `JavaScript number and would change if emitted as a TypeScript literal; ` +
+                `encode it as a string in the schema instead`);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertJsSafeNumbers(item, where, keyword);
+        return;
+    }
+    if (value !== null && typeof value === "object")
+        for (const item of Object.values(value))
+            assertJsSafeNumbers(item, where, keyword);
+}
+/**
+ * Render one admitted schema to a named TypeScript declaration (plus its
+ * reachable `$defs` interfaces). `rootName` must already be a registry-minted
+ * name; `rootSourceKey` scopes this schema's `$defs` names within the registry.
+ */
+export async function renderSchemaType(schema, rootName, rootSourceKey, registry, where) {
+    // 1. Admit through the authoritative dialect gate.
+    try {
+        compileSchema(schema);
+    }
+    catch (error) {
+        if (error instanceof SchemaDefinitionError)
+            throw new GeneratorError(`${where}: schema is outside the supported dialect: ${error.message}`);
+        throw error;
+    }
+    // 2. Guard emitted numeric literals against silent rounding.
+    assertRenderableLiterals(schema, where);
+    // 3. Project to plain JSON and rewrite for the compiler.
+    const plain = toPlainJson(schema);
+    if (!isObject(plain))
+        throw new GeneratorError(`${where}: schema must be a JSON object`);
+    const renameMap = buildDefsRenameMap(plain, rootName, rootSourceKey, registry);
+    const marker = { used: false };
+    const prepared = rewriteForCompile(plain, renameMap, marker);
+    // 4. Compile and post-scan for `any`.
+    let text;
+    try {
+        text = await compile(prepared, rootName, COMPILE_OPTIONS);
+    }
+    catch (error) {
+        throw new GeneratorError(`${where}: json-schema-to-typescript failed: ${error.message}`);
+    }
+    assertNoAny(text, where);
+    return { text: text.trim(), usesJsonValue: marker.used };
+}
+/** Build the `$defs` key → registry-name map for one root schema. */
+function buildDefsRenameMap(plain, rootName, rootSourceKey, registry) {
+    const map = new Map();
+    const defs = plain["$defs"];
+    if (!isObject(defs))
+        return map;
+    // Sort keys so the first claimant of any clashing base is deterministic.
+    for (const key of Object.keys(defs).sort()) {
+        const assigned = registry.claim(`def:${rootSourceKey}:${key}`, `${rootName}${pascalCase(key)}`);
+        map.set(key, assigned);
+    }
+    return map;
+}
+/**
+ * Rewrite a plain schema for json-schema-to-typescript: strip titles, sanitize
+ * descriptions, rewrite `x-zo-json-value` to a `JsonValue` tsType, rename the
+ * root `$defs` keys, rewrite `#/$defs/` refs, and drop any schema-supplied
+ * `tsType` (never honor raw type injection from schema data) and `discriminator`
+ * (OpenAPI metadata the compiler ignores). Objects are built with a null
+ * prototype so a property literally named `__proto__` survives.
+ */
+function rewriteForCompile(value, renameMap, marker) {
+    if (Array.isArray(value))
+        return value.map((item) => rewriteForCompile(item, renameMap, marker));
+    if (!isObject(value))
+        return value;
+    // The arbitrary-JSON marker: emit the SDK's exact wire type. We mint this
+    // tsType ourselves — a schema-supplied tsType is never trusted.
+    if (value["x-zo-json-value"] === true) {
+        marker.used = true;
+        const out = Object.create(null);
+        out["tsType"] = "JsonValue";
+        if (typeof value["description"] === "string")
+            out["description"] = sanitizeDoc(value["description"]);
+        return out;
+    }
+    const out = Object.create(null);
+    for (const [key, item] of Object.entries(value)) {
+        if (key === "title" || key === "tsType" || key === "discriminator")
+            continue;
+        if (key === "description" && typeof item === "string") {
+            out[key] = sanitizeDoc(item);
+        }
+        else if (key === "$ref" && typeof item === "string") {
+            out[key] = rewriteRef(item, renameMap);
+        }
+        else if (key === "$defs" && isObject(item)) {
+            const defs = Object.create(null);
+            for (const [defKey, defValue] of Object.entries(item))
+                defs[renameMap.get(defKey) ?? defKey] = rewriteForCompile(defValue, renameMap, marker);
+            out[key] = defs;
+        }
+        else {
+            out[key] = rewriteForCompile(item, renameMap, marker);
+        }
+    }
+    return out;
+}
+function rewriteRef(ref, renameMap) {
+    if (!ref.startsWith(REF_PREFIX))
+        return ref;
+    const name = ref.slice(REF_PREFIX.length);
+    const mapped = renameMap.get(name);
+    return mapped === undefined ? ref : `${REF_PREFIX}${mapped}`;
+}
+/**
+ * Fail if the compiled output contains `any` in a type position. With
+ * `unknownAny: true` this should never happen; it is a defense-in-depth check so
+ * a compiler regression can never silently widen a generated type to `any`.
+ */
+function assertNoAny(text, where) {
+    if (containsAnyType(text))
+        throw new GeneratorError(`${where}: generated TypeScript contains 'any'; refusing to emit an unsound type`);
+}
+const IDENT_CHAR = /[A-Za-z0-9_$]/;
+/**
+ * Lexically scan `text` for a bare `any` type token. This is comment- and
+ * string-aware: an `any` inside a line/block comment or a quoted string
+ * (including an `enum`/`const` value literally `"any"`) is skipped, and a `//`
+ * or `/*` inside a string literal is not mistaken for a comment. An `any`
+ * identifier immediately followed (past whitespace) by `:` or `?` is a property
+ * name, not the `any` type, so it is ignored; any other bare `any` token in code
+ * is a real `any` type.
+ */
+export function containsAnyType(text) {
+    const n = text.length;
+    let i = 0;
+    while (i < n) {
+        const ch = text[i];
+        // Line comment.
+        if (ch === "/" && text[i + 1] === "/") {
+            i += 2;
+            while (i < n && text[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        // Block comment.
+        if (ch === "/" && text[i + 1] === "*") {
+            i += 2;
+            while (i < n && !(text[i] === "*" && text[i + 1] === "/"))
+                i += 1;
+            i += 2;
+            continue;
+        }
+        // String literal (single, double, or template): skip to the matching
+        // delimiter, honoring backslash escapes.
+        if (ch === '"' || ch === "'" || ch === "`") {
+            const quote = ch;
+            i += 1;
+            while (i < n && text[i] !== quote)
+                i += text[i] === "\\" ? 2 : 1;
+            i += 1;
+            continue;
+        }
+        // Identifier run in code.
+        if (IDENT_CHAR.test(ch)) {
+            const start = i;
+            while (i < n && IDENT_CHAR.test(text[i]))
+                i += 1;
+            if (text.slice(start, i) === "any") {
+                // A property name (`any:` / `any?:`) is not the `any` type.
+                let j = i;
+                while (j < n && /\s/.test(text[j]))
+                    j += 1;
+                const next = text[j];
+                if (next !== ":" && next !== "?")
+                    return true;
+            }
+            continue;
+        }
+        i += 1;
+    }
+    return false;
+}

package/dist/generated/catalog.d.ts

@@ -0,0 +1,2 @@
+import type { DefaultVersions, Operations } from "./operations.js";
+export declare const catalog: import("@zocomputer/system-api/core").TypedCatalog<Operations, DefaultVersions>;