primitive-admin 1.1.0-alpha.43 → 1.1.0-alpha.45

package/dist/src/lib/workflow-codegen/generated-schema-descriptor.d.ts

@@ -0,0 +1,96 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Vendored byte-for-byte from the canonical server module
+ * `src/workflows/schema-descriptor.ts` — the SAME interpretation the server
+ * validator (`validateValue`) enforces. The CLI cannot import server `src/`
+ * at runtime, so `workflows codegen`'s type converter imports this committed
+ * copy instead.
+ *
+ * Regenerate with:
+ *   node cli/scripts/gen-workflow-schema-descriptor.mjs   (runs at CLI prebuild)
+ *
+ * A CI freshness guard
+ * (`cli/scripts/gen-workflow-schema-descriptor.mjs --check`, also asserted by
+ * `cli/tests/unit/workflow-codegen-descriptor-drift-guard.test.ts`) fails if
+ * this committed copy does not match the source — see issue #1442 / #998.
+ */
+/**
+ * Canonical interpretation of the JSON-Schema subset the workflow platform
+ * supports (issue #1442).
+ *
+ * The server validator (`validateValue` in `schema-validation.ts`) and the CLI
+ * `workflows codegen` type converter (`workflow-codegen/schemaToTs.ts`) must
+ * agree EXACTLY on how a workflow `inputSchema`/`outputSchema` is interpreted —
+ * otherwise a generated `<Key>Input` type promises a shape the runtime does not
+ * enforce (or rejects a value the runtime accepts). Previously the converter
+ * re-derived those interpretation decisions by hand, which drifts from the
+ * validator over time.
+ *
+ * This module is the single source of that interpretation. Both consumers read
+ * from `describeSchema` + `isType`:
+ *
+ *   - the type gate is checked before `enum` (a value failing `type` is
+ *     rejected before `enum` is consulted);
+ *   - a type UNION (`type: ["string","null"]`) never descends into
+ *     `properties`/`items` — only the exact string types `"object"`/`"array"`
+ *     do;
+ *   - `integer` means `Number.isInteger`;
+ *   - `additionalProperties` only closes an object; it is not a nested schema.
+ *
+ * It is deliberately dependency-free (no imports) so the CLI can vendor a
+ * byte-for-byte copy as a committed artifact via
+ * `cli/scripts/gen-workflow-schema-descriptor.mjs` (the #998 gen-allowlist
+ * pattern). A drift-guard test runs that generator in `--check` mode, so a
+ * change here that isn't regenerated into the CLI artifact fails CI. The CLI
+ * never imports server `src/` at runtime — only the build-time generator reads
+ * this file.
+ */
+/** Does a value satisfy a JSON-schema `type` name? `integer` = `Number.isInteger`. */
+export declare function isType(value: any, type: string): boolean;
+/**
+ * The interpretation of a single schema node, normalized so both the validator
+ * and the type converter can consume it without re-reading raw schema fields.
+ */
+export interface SchemaDescriptor {
+    /** True when `schema.type` is an array (a type union). */
+    isUnion: boolean;
+    /** `schema.type` when it is a single string; null for a union or absent type. */
+    singularType: string | null;
+    /**
+     * The declared type(s) normalized to an array. An array `type` is kept as-is;
+     * a single string becomes a one-element array; an absent/falsy type is `[]`
+     * (no type gate). Matches the validator's `allowedTypes` normalization.
+     */
+    types: string[];
+    /** The `enum` array when present, else null. */
+    enumValues: any[] | null;
+    /**
+     * Object descent info — non-null ONLY when `schema.type` is exactly the
+     * string `"object"` AND `properties` is a declared object (matching the
+     * validator's `schema.type === "object" && schema.properties` descent gate).
+     * A type UNION containing `"object"` never descends.
+     */
+    object: {
+        /** The raw `properties` map (child schemas). May be empty `{}`. */
+        properties: Record<string, any>;
+        /** The raw `required` list (unfiltered, as the validator reads it). */
+        required: any[];
+        /** True when `additionalProperties === false` (a closed object). */
+        additionalPropertiesClosed: boolean;
+    } | null;
+    /**
+     * Array descent info — non-null ONLY when `schema.type` is exactly the string
+     * `"array"` AND `items` is present (matching the validator's
+     * `schema.type === "array" && schema.items` descent gate).
+     */
+    array: {
+        /** The raw `items` schema (may be a tuple array the validator no-ops on). */
+        items: any;
+    } | null;
+}
+/**
+ * Interpret a parsed schema node. A non-object schema (null, array, scalar)
+ * enforces nothing → the empty descriptor.
+ */
+export declare function describeSchema(schema: any): SchemaDescriptor;

package/dist/src/lib/workflow-codegen/generated-schema-descriptor.js

@@ -0,0 +1,112 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Vendored byte-for-byte from the canonical server module
+ * `src/workflows/schema-descriptor.ts` — the SAME interpretation the server
+ * validator (`validateValue`) enforces. The CLI cannot import server `src/`
+ * at runtime, so `workflows codegen`'s type converter imports this committed
+ * copy instead.
+ *
+ * Regenerate with:
+ *   node cli/scripts/gen-workflow-schema-descriptor.mjs   (runs at CLI prebuild)
+ *
+ * A CI freshness guard
+ * (`cli/scripts/gen-workflow-schema-descriptor.mjs --check`, also asserted by
+ * `cli/tests/unit/workflow-codegen-descriptor-drift-guard.test.ts`) fails if
+ * this committed copy does not match the source — see issue #1442 / #998.
+ */
+/**
+ * Canonical interpretation of the JSON-Schema subset the workflow platform
+ * supports (issue #1442).
+ *
+ * The server validator (`validateValue` in `schema-validation.ts`) and the CLI
+ * `workflows codegen` type converter (`workflow-codegen/schemaToTs.ts`) must
+ * agree EXACTLY on how a workflow `inputSchema`/`outputSchema` is interpreted —
+ * otherwise a generated `<Key>Input` type promises a shape the runtime does not
+ * enforce (or rejects a value the runtime accepts). Previously the converter
+ * re-derived those interpretation decisions by hand, which drifts from the
+ * validator over time.
+ *
+ * This module is the single source of that interpretation. Both consumers read
+ * from `describeSchema` + `isType`:
+ *
+ *   - the type gate is checked before `enum` (a value failing `type` is
+ *     rejected before `enum` is consulted);
+ *   - a type UNION (`type: ["string","null"]`) never descends into
+ *     `properties`/`items` — only the exact string types `"object"`/`"array"`
+ *     do;
+ *   - `integer` means `Number.isInteger`;
+ *   - `additionalProperties` only closes an object; it is not a nested schema.
+ *
+ * It is deliberately dependency-free (no imports) so the CLI can vendor a
+ * byte-for-byte copy as a committed artifact via
+ * `cli/scripts/gen-workflow-schema-descriptor.mjs` (the #998 gen-allowlist
+ * pattern). A drift-guard test runs that generator in `--check` mode, so a
+ * change here that isn't regenerated into the CLI artifact fails CI. The CLI
+ * never imports server `src/` at runtime — only the build-time generator reads
+ * this file.
+ */
+/** Does a value satisfy a JSON-schema `type` name? `integer` = `Number.isInteger`. */
+export function isType(value, type) {
+    if (type === "array")
+        return Array.isArray(value);
+    if (type === "object")
+        return !!value && typeof value === "object" && !Array.isArray(value);
+    if (type === "string")
+        return typeof value === "string";
+    if (type === "number")
+        return typeof value === "number" && !Number.isNaN(value);
+    if (type === "integer")
+        return Number.isInteger(value);
+    if (type === "boolean")
+        return typeof value === "boolean";
+    if (type === "null")
+        return value === null;
+    // Unknown type name: nothing to enforce, so treat as a match (the validator
+    // must not reject a value against a keyword it does not model).
+    return true;
+}
+const EMPTY_DESCRIPTOR = {
+    isUnion: false,
+    singularType: null,
+    types: [],
+    enumValues: null,
+    object: null,
+    array: null,
+};
+/**
+ * Interpret a parsed schema node. A non-object schema (null, array, scalar)
+ * enforces nothing → the empty descriptor.
+ */
+export function describeSchema(schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        return EMPTY_DESCRIPTOR;
+    }
+    const typeSpec = schema.type;
+    const isUnion = Array.isArray(typeSpec);
+    const singularType = typeof typeSpec === "string" ? typeSpec : null;
+    // Mirror the validator's normalization exactly: an array stays an array; a
+    // truthy non-array becomes `[typeSpec]`; anything falsy is `[]`.
+    const types = isUnion ? typeSpec : typeSpec ? [typeSpec] : [];
+    const enumValues = Array.isArray(schema.enum)
+        ? schema.enum
+        : null;
+    const props = schema.properties;
+    const object = singularType === "object" &&
+        props &&
+        typeof props === "object" &&
+        !Array.isArray(props)
+        ? {
+            properties: props,
+            required: Array.isArray(schema.required)
+                ? schema.required
+                : [],
+            additionalPropertiesClosed: schema.additionalProperties === false,
+        }
+        : null;
+    const array = singularType === "array" && schema.items
+        ? { items: schema.items }
+        : null;
+    return { isUnion, singularType, types, enumValues, object, array };
+}
+//# sourceMappingURL=generated-schema-descriptor.js.map

package/dist/src/lib/workflow-codegen/generated-schema-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-schema-descriptor.js","sourceRoot":"","sources":["../../../../src/lib/workflow-codegen/generated-schema-descriptor.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/workflow-codegen/generator.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `workflows codegen` orchestrator (issue #1442).
+ *
+ * Reads synced workflow TOMLs (`.primitive/sync/<env>/<appId>/workflows/*.toml`)
+ * and emits ONE generated file per workflow —
+ * `workflows/generated/<key>.generated.ts` — each containing the workflow's
+ * `<Key>Input`/`<Key>Output` types plus a typed `<key>(client)` invoker factory
+ * returning `{ runSync?, start }`. This mirrors `databases codegen`'s per-type
+ * `<Type>.generated.ts` layout (#1441's `<type>Ops`): per-file artifacts keep
+ * team merges conflict-free and let a `[workflow-key]` filter regenerate exactly
+ * one file.
+ *
+ * Design decisions (see the plan of record on #1442, post-pivot):
+ *   - Schemas are interpreted through the SHARED descriptor
+ *     (`generated-schema-descriptor.ts`, a vendored copy of the server's
+ *     `schema-validation` descriptor) so the generated types match runtime
+ *     validation exactly. A malformed schema throws (fail-and-exit).
+ *   - `.runSync` is emitted only for `syncCallable: true` workflows (the server
+ *     rejects run-sync otherwise); `.start` for every non-reserved workflow.
+ *   - `input` is a REQUIRED option iff the schema rejects `{}` (the client's
+ *     `input ?? {}` fallback would fail validation); otherwise `input?`.
+ *   - The runtime call always passes the ORIGINAL key string; only identifiers
+ *     are sanitized. `workflowKey` is set AFTER spreading `opts`, so a caller
+ *     cannot override it.
+ *   - Disk lifecycle (write / `--check` / suffix-based cleanup) delegates to the
+ *     shared `writeOrCheckGeneratedFiles`, exactly like `databases codegen`.
+ */
+import { type WriteOrCheckResult } from "../codegen-shared/generatedFiles.js";
+/** Suffix identifying a generated file (shared with `databases codegen`). */
+export declare const GENERATED_FILE_SUFFIX = ".generated.ts";
+export interface WorkflowCodegenInput {
+    /** Source `.toml` filename stem (fallback key when `[workflow].key` is absent). */
+    fileStem: string;
+    /** Path to the source `workflows/<key>.toml` file. */
+    tomlPath: string;
+    /** Raw TOML content (already read from disk). */
+    tomlContent: string;
+}
+export interface GenerateWorkflowTypesOptions {
+    inputs: WorkflowCodegenInput[];
+    /** Directory where the `<key>.generated.ts` files are written. */
+    outputDir: string;
+    /** `--check`: compare against disk, do not write. */
+    check?: boolean;
+    /**
+     * Set when the run was filtered to a single workflow key (the
+     * `primitive workflows codegen <key>` argument). The `inputs` set is then
+     * PARTIAL — it does not represent the full set of owned generated files — so
+     * stale-output cleanup (and `--check` stale detection) is scoped to the
+     * filtered workflow's own file and must NOT touch / flag sibling workflows'
+     * `*.generated.ts` files. The unfiltered "generate all" run leaves this unset
+     * and keeps full orphan cleanup. Mirrors `databases codegen`'s `singleType`.
+     */
+    singleWorkflow?: boolean;
+}
+/**
+ * Render the full `<key>.generated.ts` content for a single workflow TOML input.
+ * Returns null for a reserved (`__internal.*`) workflow. Pure — exported so
+ * tests can assert on the string directly.
+ */
+export declare function renderWorkflowFile(input: WorkflowCodegenInput): {
+    key: string;
+    content: string;
+} | null;
+/**
+ * Run workflow codegen end-to-end. One `<key>.generated.ts` per workflow;
+ * delegates the disk lifecycle to the shared writer/checker, exactly like
+ * `databases codegen`.
+ */
+export declare function generateWorkflowTypes(options: GenerateWorkflowTypesOptions): Promise<WriteOrCheckResult>;

package/dist/src/lib/workflow-codegen/generator.js

@@ -0,0 +1,186 @@
+/**
+ * `workflows codegen` orchestrator (issue #1442).
+ *
+ * Reads synced workflow TOMLs (`.primitive/sync/<env>/<appId>/workflows/*.toml`)
+ * and emits ONE generated file per workflow —
+ * `workflows/generated/<key>.generated.ts` — each containing the workflow's
+ * `<Key>Input`/`<Key>Output` types plus a typed `<key>(client)` invoker factory
+ * returning `{ runSync?, start }`. This mirrors `databases codegen`'s per-type
+ * `<Type>.generated.ts` layout (#1441's `<type>Ops`): per-file artifacts keep
+ * team merges conflict-free and let a `[workflow-key]` filter regenerate exactly
+ * one file.
+ *
+ * Design decisions (see the plan of record on #1442, post-pivot):
+ *   - Schemas are interpreted through the SHARED descriptor
+ *     (`generated-schema-descriptor.ts`, a vendored copy of the server's
+ *     `schema-validation` descriptor) so the generated types match runtime
+ *     validation exactly. A malformed schema throws (fail-and-exit).
+ *   - `.runSync` is emitted only for `syncCallable: true` workflows (the server
+ *     rejects run-sync otherwise); `.start` for every non-reserved workflow.
+ *   - `input` is a REQUIRED option iff the schema rejects `{}` (the client's
+ *     `input ?? {}` fallback would fail validation); otherwise `input?`.
+ *   - The runtime call always passes the ORIGINAL key string; only identifiers
+ *     are sanitized. `workflowKey` is set AFTER spreading `opts`, so a caller
+ *     cannot override it.
+ *   - Disk lifecycle (write / `--check` / suffix-based cleanup) delegates to the
+ *     shared `writeOrCheckGeneratedFiles`, exactly like `databases codegen`.
+ */
+import * as path from "path";
+import { parseConfigToml } from "../config-toml.js";
+import { safeJsonParse } from "../workflow-payload.js";
+import { writeOrCheckGeneratedFiles, } from "../codegen-shared/generatedFiles.js";
+import { fingerprintToml } from "../db-codegen/dbFingerprint.js";
+import { schemaToTsType, schemaRejectsEmptyObject } from "./schemaToTs.js";
+import { workflowInputTypeName, workflowOutputTypeName, workflowFactoryName, } from "./naming.js";
+/** Prefix marking a platform-owned workflow key (mirrors the server's
+ * `INTERNAL_WORKFLOW_KEY_PREFIX`; inlined because the CLI cannot import from
+ * `src/`). Such workflows are never client-invocable and are skipped. */
+const INTERNAL_WORKFLOW_KEY_PREFIX = "__internal.";
+/** Suffix identifying a generated file (shared with `databases codegen`). */
+export const GENERATED_FILE_SUFFIX = ".generated.ts";
+/** The client package the generated file imports its types from. */
+const CLIENT_PACKAGE = "js-bao-wss-client";
+/** True for a platform-owned workflow key. */
+function isReservedKey(key) {
+    return (typeof key === "string" &&
+        key.trim().toLowerCase().startsWith(INTERNAL_WORKFLOW_KEY_PREFIX));
+}
+/**
+ * Render a top-level `<Name>Input`/`<Name>Output` declaration. An absent schema
+ * → `unknown`. An object type → an `interface`; anything else → a `type` alias.
+ */
+function renderTypeDecl(name, schema) {
+    if (schema === undefined) {
+        return `export type ${name} = unknown;`;
+    }
+    const expr = schemaToTsType(schema, 0);
+    if (expr.startsWith("{")) {
+        return `export interface ${name} ${expr}`;
+    }
+    return `export type ${name} = ${expr};`;
+}
+/**
+ * Parse a single workflow TOML into the data the emitter needs. Throws on
+ * malformed schema JSON (fail-and-exit) — the honest `unknown` fallback is for
+ * valid-but-untypeable schemas only. Returns null for a reserved workflow.
+ */
+function parseWorkflow(input) {
+    // #1464 removed `@iarna/toml`; #1446 makes `sync pull` emit schemas as native
+    // TOML tables (incl. mixed-type enums like `enum = ["ok", 1]`, TOML 1.0). The
+    // `parseConfigToml` facade parses both. `safeJsonParse` still owns the
+    // string-vs-inline-table schema handling.
+    const data = parseConfigToml(input.tomlContent);
+    const workflow = data?.workflow ?? {};
+    const key = typeof workflow.key === "string" && workflow.key.length > 0
+        ? workflow.key
+        : input.fileStem;
+    if (isReservedKey(key))
+        return null;
+    // safeJsonParse throws on invalid JSON in a schema string — let it bubble.
+    const inputSchema = safeJsonParse(workflow.inputSchema);
+    const outputSchema = safeJsonParse(workflow.outputSchema);
+    const inputTypeName = workflowInputTypeName(key);
+    const outputTypeName = workflowOutputTypeName(key);
+    return {
+        key,
+        syncCallable: workflow.syncCallable === true,
+        inputTypeName,
+        outputTypeName,
+        factoryName: workflowFactoryName(key),
+        inputDecl: renderTypeDecl(inputTypeName, inputSchema),
+        outputDecl: renderTypeDecl(outputTypeName, outputSchema),
+        // `input` is required iff the schema rejects the client's `{}` fallback.
+        // A schema-less workflow (`undefined`) accepts anything → optional.
+        inputRequired: inputSchema !== undefined && schemaRejectsEmptyObject(inputSchema),
+    };
+}
+/** Render the typed invoker factory for one workflow. */
+function renderFactory(wf) {
+    const keyLiteral = JSON.stringify(wf.key);
+    const inputMember = wf.inputRequired
+        ? `input: ${wf.inputTypeName}`
+        : `input?: ${wf.inputTypeName}`;
+    const lines = [
+        `export function ${wf.factoryName}(client: JsBaoClient) {`,
+        `  return {`,
+    ];
+    // Spread `opts` FIRST, then set `workflowKey` LAST, so the factory's intended
+    // key always wins. `Omit<..., "workflowKey">` only rejects an excess
+    // `workflowKey` on object literals; a caller passing an options *variable*
+    // carrying an extra `workflowKey` (or any untyped JS caller) would otherwise
+    // override the key and invoke the wrong workflow if the spread came last.
+    if (wf.syncCallable) {
+        lines.push(`    runSync: (\n` +
+            `      opts: { ${inputMember} } & Omit<RunSyncWorkflowOptions, "workflowKey" | "input">\n` +
+            `    ) =>\n` +
+            `      client.workflows.runSync<${wf.inputTypeName}, ${wf.outputTypeName}>({\n` +
+            `        ...opts,\n` +
+            `        workflowKey: ${keyLiteral},\n` +
+            `      }),`);
+    }
+    lines.push(`    start: (\n` +
+        `      opts: { ${inputMember} } & Omit<StartWorkflowOptions, "workflowKey" | "input">\n` +
+        `    ) =>\n` +
+        `      client.workflows.start<${wf.inputTypeName}>({\n` +
+        `        ...opts,\n` +
+        `        workflowKey: ${keyLiteral},\n` +
+        `      }),`);
+    lines.push(`  };`, `}`);
+    return lines.join("\n");
+}
+/**
+ * Render the full `<key>.generated.ts` content for a single workflow TOML input.
+ * Returns null for a reserved (`__internal.*`) workflow. Pure — exported so
+ * tests can assert on the string directly.
+ */
+export function renderWorkflowFile(input) {
+    const wf = parseWorkflow(input);
+    if (!wf)
+        return null;
+    const fingerprint = fingerprintToml(input.tomlContent);
+    // Only import the option types actually referenced, so the generated file
+    // compiles under a consumer's `noUnusedLocals`.
+    const imports = ["JsBaoClient", "StartWorkflowOptions"];
+    if (wf.syncCallable)
+        imports.push("RunSyncWorkflowOptions");
+    imports.sort();
+    const blocks = [];
+    blocks.push([
+        `// AUTO-GENERATED FROM workflows/${wf.key}.toml — DO NOT EDIT.`,
+        "// Run `primitive workflows codegen` to regenerate.",
+        `// fingerprint: ${fingerprint}`,
+    ].join("\n"));
+    blocks.push(`import type {\n${imports
+        .map((i) => `  ${i},`)
+        .join("\n")}\n} from "${CLIENT_PACKAGE}";`);
+    blocks.push(wf.inputDecl);
+    blocks.push(wf.outputDecl);
+    blocks.push(renderFactory(wf));
+    return { key: wf.key, content: blocks.join("\n\n") + "\n" };
+}
+/**
+ * Run workflow codegen end-to-end. One `<key>.generated.ts` per workflow;
+ * delegates the disk lifecycle to the shared writer/checker, exactly like
+ * `databases codegen`.
+ */
+export async function generateWorkflowTypes(options) {
+    const outAbs = path.resolve(options.outputDir);
+    const filesToWrite = new Map();
+    for (const input of options.inputs) {
+        const rendered = renderWorkflowFile(input);
+        if (!rendered)
+            continue; // reserved workflow — no file
+        const filePath = path.join(outAbs, `${rendered.key}${GENERATED_FILE_SUFFIX}`);
+        filesToWrite.set(filePath, rendered.content);
+    }
+    return await writeOrCheckGeneratedFiles({
+        outputDir: outAbs,
+        filesToWrite,
+        check: options.check,
+        // A single-workflow filter run owns only a subset of the generated files,
+        // so orphan cleanup / stale detection must be scoped to the filtered file.
+        fullOwnership: options.singleWorkflow !== true,
+        generatedSuffix: GENERATED_FILE_SUFFIX,
+    });
+}
+//# sourceMappingURL=generator.js.map

package/dist/src/lib/workflow-codegen/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../../../src/lib/workflow-codegen/generator.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/workflow-codegen/naming.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Identifier-naming helpers for `workflows codegen` (issue #1442).
+ *
+ * Workflow keys resolve case-insensitively server-side and may contain
+ * characters that aren't valid TS identifiers (`.`, `-`). Only the emitted
+ * identifiers are sanitized — the runtime call always passes the ORIGINAL key
+ * string.
+ *
+ * Type names: `pascalCase(key) + "Input" | "Output"` (reuses `pascalCase` from
+ * the database codegen so the two commands share one PascalCase rule).
+ * Factory property: a camelCase form of the key.
+ */
+/**
+ * `create-checkout-session` / `createCheckoutSession` → `CreateCheckoutSession`.
+ * A digit-leading key (`123-job` → `_123Job`) is prefixed with `_` so the
+ * emitted type name is a valid TS identifier.
+ */
+export declare function workflowTypeBaseName(key: string): string;
+/** PascalCase base + `Input` (e.g. `CreateCheckoutSessionInput`). */
+export declare function workflowInputTypeName(key: string): string;
+/** PascalCase base + `Output` (e.g. `CreateCheckoutSessionOutput`). */
+export declare function workflowOutputTypeName(key: string): string;
+/**
+ * camelCase factory function name for a workflow key: PascalCase, then lowercase
+ * the first character (`create-checkout-session` → `createCheckoutSession`,
+ * `refresh-sheet` → `refreshSheet`). Used as the top-level exported factory
+ * function name in the per-workflow generated file, so it must be a legal
+ * function identifier: a digit-leading key (`123-job` → `_123Job`) is
+ * underscore-prefixed, and a key that lands on a JS reserved word (`delete`,
+ * `new`, `import`) is underscore-suffixed (`delete_`). Only the emitted
+ * identifier changes; the runtime call still passes the ORIGINAL key string.
+ */
+export declare function workflowFactoryName(key: string): string;

package/dist/src/lib/workflow-codegen/naming.js

@@ -0,0 +1,81 @@
+/**
+ * Identifier-naming helpers for `workflows codegen` (issue #1442).
+ *
+ * Workflow keys resolve case-insensitively server-side and may contain
+ * characters that aren't valid TS identifiers (`.`, `-`). Only the emitted
+ * identifiers are sanitized — the runtime call always passes the ORIGINAL key
+ * string.
+ *
+ * Type names: `pascalCase(key) + "Input" | "Output"` (reuses `pascalCase` from
+ * the database codegen so the two commands share one PascalCase rule).
+ * Factory property: a camelCase form of the key.
+ */
+import { pascalCase } from "../db-codegen/dbNaming.js";
+/**
+ * Ensure an identifier is a valid TS identifier start. The server accepts
+ * workflow keys matching `^[a-z0-9][a-z0-9-_]{2,}$`, so a digit-leading key
+ * like `123-job` PascalCases to `123Job` — not a legal TS type name or
+ * unquoted object property, since identifiers can't start with a digit.
+ * Prefix an underscore in that case (`123Job` → `_123Job`). Only the emitted
+ * identifier changes; the runtime call still passes the ORIGINAL key string.
+ */
+function ensureValidIdentifierStart(name) {
+    const first = name.charAt(0);
+    if (first >= "0" && first <= "9") {
+        return `_${name}`;
+    }
+    return name;
+}
+/**
+ * `create-checkout-session` / `createCheckoutSession` → `CreateCheckoutSession`.
+ * A digit-leading key (`123-job` → `_123Job`) is prefixed with `_` so the
+ * emitted type name is a valid TS identifier.
+ */
+export function workflowTypeBaseName(key) {
+    return ensureValidIdentifierStart(pascalCase(key));
+}
+/** PascalCase base + `Input` (e.g. `CreateCheckoutSessionInput`). */
+export function workflowInputTypeName(key) {
+    return `${workflowTypeBaseName(key)}Input`;
+}
+/** PascalCase base + `Output` (e.g. `CreateCheckoutSessionOutput`). */
+export function workflowOutputTypeName(key) {
+    return `${workflowTypeBaseName(key)}Output`;
+}
+/**
+ * Reserved words that cannot be used as a bare `function <name>` declaration.
+ * The per-workflow factory is now a top-level exported function (not an
+ * object-literal property), so a key that camelCases to one of these must be
+ * escaped or `export function delete(client) {}` is a syntax error. Covers ES
+ * reserved words plus the strict-mode/future set — a workflow key resolves case
+ * -insensitively and matches `^[a-z0-9][a-z0-9-_]{2,}$`, so only the lowercase
+ * single-word forms can actually collide.
+ */
+const RESERVED_WORDS = new Set([
+    "break", "case", "catch", "class", "const", "continue", "debugger",
+    "default", "delete", "do", "else", "enum", "export", "extends", "false",
+    "finally", "for", "function", "if", "import", "in", "instanceof", "new",
+    "null", "return", "super", "switch", "this", "throw", "true", "try",
+    "typeof", "var", "void", "while", "with", "yield", "let", "static",
+    "implements", "interface", "package", "private", "protected", "public",
+    "await",
+]);
+/**
+ * camelCase factory function name for a workflow key: PascalCase, then lowercase
+ * the first character (`create-checkout-session` → `createCheckoutSession`,
+ * `refresh-sheet` → `refreshSheet`). Used as the top-level exported factory
+ * function name in the per-workflow generated file, so it must be a legal
+ * function identifier: a digit-leading key (`123-job` → `_123Job`) is
+ * underscore-prefixed, and a key that lands on a JS reserved word (`delete`,
+ * `new`, `import`) is underscore-suffixed (`delete_`). Only the emitted
+ * identifier changes; the runtime call still passes the ORIGINAL key string.
+ */
+export function workflowFactoryName(key) {
+    const pascal = pascalCase(key);
+    if (pascal.length === 0)
+        return pascal;
+    const camel = pascal.charAt(0).toLowerCase() + pascal.slice(1);
+    const safeStart = ensureValidIdentifierStart(camel);
+    return RESERVED_WORDS.has(safeStart) ? `${safeStart}_` : safeStart;
+}
+//# sourceMappingURL=naming.js.map

package/dist/src/lib/workflow-codegen/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../../../../src/lib/workflow-codegen/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD;;;;;;;GAOG;AACH,SAAS,0BAA0B,CAAC,IAAY;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;QACjC,OAAO,IAAI,IAAI,EAAE,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,0BAA0B,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,OAAO,GAAG,oBAAoB,CAAC,GAAG,CAAC,OAAO,CAAC;AAC7C,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,OAAO,GAAG,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC;AAC9C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU;IAClE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO;IACvE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK;IACvE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK;IACnE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ;IAClE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ;IACtE,OAAO;CACR,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,0BAA0B,CAAC,KAAK,CAAC,CAAC;IACpD,OAAO,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC"}

package/dist/src/lib/workflow-codegen/schemaToTs.d.ts

@@ -0,0 +1,55 @@
+/**
+ * JSON-Schema → TypeScript converter for `workflows codegen` (issue #1442).
+ *
+ * Workflow `inputSchema`/`outputSchema` are real JSON Schema. This converter
+ * types only the subset the server's validator descends into — and it reads
+ * that interpretation from the SAME descriptor the server validator consumes,
+ * vendored into the CLI as `generated-schema-descriptor.ts` (a byte copy of
+ * `src/workflows/schema-descriptor.ts`, kept fresh by
+ * `cli/scripts/gen-workflow-schema-descriptor.mjs` + its drift guard). So the
+ * generated type and the runtime validation can never disagree on:
+ *
+ *   - `type` single scalar (`string`/`number`/`integer`/`boolean`/`null`) →
+ *     the mapped TS scalar.
+ *   - `type` array-union — only when every member is a scalar/`null` → a TS
+ *     union. A union that contains `object` or `array` renders `unknown`,
+ *     because the server only walks `properties`/`items` for the bare string
+ *     `"object"`/`"array"` — a union is never descended, so a precise-looking
+ *     type would over-promise.
+ *   - `enum` → a scalar-literal union, intersected with the declared `type`
+ *     first (the server gates on `type` before checking `enum`).
+ *   - `type: "object"` with `properties` → a nested object type; `required[]`
+ *     drives `name:` vs `name?:`. An OPEN object (no `additionalProperties:
+ *     false`) also emits `[key: string]: unknown` so extra keys the runtime
+ *     validator accepts don't hit TS excess-property errors; a CLOSED object
+ *     (`additionalProperties: false`) omits the index signature.
+ *   - `type: "array"` with `items` → `T[]`.
+ *
+ * Everything the server ignores (`$ref`, `oneOf`/`anyOf`/`allOf`, `format`,
+ * `patternProperties`, numeric constraints, tuple `items`) renders `unknown`.
+ *
+ * Errors are NOT swallowed here — a malformed schema fails upstream at parse
+ * time; this walker only sees an already-parsed schema and returns `unknown`
+ * for anything it does not recognize.
+ */
+/**
+ * Convert a parsed JSON Schema node to a TypeScript type expression. Object
+ * types render multi-line (2-space indent per level); everything else renders
+ * on a single line. `indent` is the current indentation depth.
+ */
+export declare function schemaToTsType(schema: any, indent?: number): string;
+/**
+ * True when the schema REJECTS an empty object `{}` — i.e. the client's
+ * `rootInput: options.input ?? {}` fallback would fail validation, so `input`
+ * must be a compile-time-required option (issue #1442, P4). Derived from the
+ * shared descriptor so it matches the server validator exactly:
+ *
+ *   - a declared top-level `type` that `{}` does not satisfy (anything but
+ *     `object`, e.g. `string`/`array`, or a union with no `object` arm);
+ *   - a top-level `enum` (a fresh `{}` is never an enum member);
+ *   - `type: "object"` with a non-empty `required[]` (a missing required key).
+ *
+ * An all-optional object schema, or a schema with no top-level constraints,
+ * accepts `{}` → `input` is optional.
+ */
+export declare function schemaRejectsEmptyObject(schema: any): boolean;