primitive-admin 1.0.54 → 1.0.55

package/dist/src/lib/sync-resource-types.js

@@ -0,0 +1,394 @@
+/**
+ * Shared layout metadata for the per-entity resource types `sync pull` writes
+ * into a sync slot (issue #1659).
+ *
+ * `sync pull` writes one file per server entity and records what it wrote in
+ * `.primitive-sync.json` (`SyncState.entities[<slot>]`). Until #1659 it never
+ * removed a local file whose entity had disappeared server-side, so the next
+ * `sync push` — which treats local TOML as the source of truth — silently
+ * re-created the just-deleted entity.
+ *
+ * This module holds the narrow descriptor the prune pass and `sync diff` share:
+ * directory, extension, state slot, key→filename derivation, and the sidecar
+ * test-directory block type. The pull write loops deliberately stay as they are
+ * — this table is layout metadata, not a write framework.
+ */
+import { existsSync, rmSync, statSync, unlinkSync } from "fs";
+import { dirname, join } from "path";
+const tomlFile = (key) => `${key}.toml`;
+/**
+ * Rule sets are keyed on disk (and in sync state) by their name with
+ * filesystem-hostile characters replaced. Shared by the pull write loop and the
+ * prune pass so the two can never derive a different key for the same rule set.
+ */
+export function ruleSetFileKey(ruleSet) {
+    return String(ruleSet.name || ruleSet.ruleSetId || "").replace(/[/\\:*?"<>|]/g, "_");
+}
+/**
+ * Every per-entity resource type in a sync slot. `app.toml` and `vars.toml` are
+ * root singletons, not per-entity directories, so they are not listed here —
+ * var removal is already handled within-file by `sync push` (`planVarsPush`).
+ */
+export const SYNC_RESOURCE_TYPES = [
+    {
+        label: "integration",
+        dir: "integrations",
+        ext: ".toml",
+        stateSlot: "integrations",
+        fileFromKey: tomlFile,
+        // `/admin/api/apps/{id}/integrations` paginates; pull drains it with fetchAll.
+        listingComplete: true,
+    },
+    {
+        label: "webhook",
+        dir: "webhooks",
+        ext: ".toml",
+        stateSlot: "webhooks",
+        fileFromKey: tomlFile,
+        // `/admin/api/apps/{id}/webhooks` paginates; pull drains it with fetchAll.
+        listingComplete: true,
+    },
+    {
+        label: "cron-trigger",
+        dir: "cron-triggers",
+        ext: ".toml",
+        stateSlot: "cronTriggers",
+        fileFromKey: tomlFile,
+        // `{ limit: 100 }`, no cursor, archived filtered after the query.
+        listingComplete: false,
+    },
+    {
+        label: "blob-bucket",
+        dir: "blob-buckets",
+        ext: ".toml",
+        stateSlot: "blobBuckets",
+        fileFromKey: tomlFile,
+        // `queryByIndex("bucketsForApp")` — no cursor, one page.
+        listingComplete: false,
+    },
+    {
+        label: "prompt",
+        dir: "prompts",
+        ext: ".toml",
+        stateSlot: "prompts",
+        fileFromKey: tomlFile,
+        testBlockType: "prompt",
+        // `/admin/api/apps/{id}/prompts` paginates; pull drains it with fetchAll.
+        listingComplete: true,
+    },
+    {
+        label: "workflow",
+        dir: "workflows",
+        ext: ".toml",
+        stateSlot: "workflows",
+        fileFromKey: tomlFile,
+        testBlockType: "workflow",
+        // `/admin/api/apps/{id}/workflows` paginates; pull drains it with fetchAll.
+        listingComplete: true,
+    },
+    {
+        // Rhai scripts: `.rhai` bodies, not TOML, with tests at
+        // `transforms/<name>.tests/`.
+        label: "transform",
+        dir: "transforms",
+        ext: ".rhai",
+        stateSlot: "scripts",
+        fileFromKey: (key) => `${key}.rhai`,
+        testBlockType: "script",
+        // `queryByIndex("scriptsByApp")` — no cursor, one page.
+        listingComplete: false,
+    },
+    {
+        label: "database-type",
+        dir: "database-types",
+        ext: ".toml",
+        stateSlot: "databaseTypes",
+        fileFromKey: tomlFile,
+        // `queryByIndex("databaseTypeConfigsForApp")` — no cursor, one page.
+        listingComplete: false,
+    },
+    {
+        // The state key is already the sanitized filename the write loop derives
+        // from the rule set's name (`name.replace(/[/\\:*?"<>|]/g, "_")`), so the
+        // filename is the key plus the extension.
+        label: "rule-set",
+        dir: "rule-sets",
+        ext: ".toml",
+        stateSlot: "ruleSets",
+        fileFromKey: tomlFile,
+        // `queryByIndex("ruleSetsForApp")` — no cursor, one page.
+        listingComplete: false,
+    },
+    {
+        label: "group-type-config",
+        dir: "group-type-configs",
+        ext: ".toml",
+        stateSlot: "groupTypeConfigs",
+        fileFromKey: tomlFile,
+        // `queryByIndex("configsForApp")` — no cursor, one page.
+        listingComplete: false,
+    },
+    {
+        label: "collection-type-config",
+        dir: "collection-type-configs",
+        ext: ".toml",
+        stateSlot: "collectionTypeConfigs",
+        fileFromKey: tomlFile,
+        // `queryByIndex("collectionConfigsForApp")` — no cursor, one page.
+        listingComplete: false,
+    },
+    {
+        // State key is the `resourceType#category` pair; the file on disk is
+        // `resourceType.category.toml`.
+        label: "metadata-category-config",
+        dir: "metadata-category-configs",
+        ext: ".toml",
+        stateSlot: "metadataCategoryConfigs",
+        fileFromKey: (key) => `${key.replace("#", ".")}.toml`,
+        // `queryByIndex("metadataCategoriesForApp")` — no cursor, one page.
+        listingComplete: false,
+    },
+    {
+        label: "email-template",
+        dir: "email-templates",
+        ext: ".toml",
+        stateSlot: "emailTemplates",
+        fileFromKey: tomlFile,
+        // `queryByIndex("templatesByApp")` — no cursor, one page.
+        listingComplete: false,
+    },
+];
+/** Generic try/catch wrapper for a server fetch, in the ok/error shape. */
+export async function attemptFetch(fn) {
+    try {
+        return { ok: true, value: await fn() };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+/**
+ * A filename must stay inside its type's directory. State is read from a file
+ * on disk, so a corrupt or hand-edited `.primitive-sync.json` must never be
+ * able to steer an `unlinkSync` outside the sync slot.
+ */
+export function isSafeSyncFilename(filename) {
+    if (!filename || filename === "." || filename === "..")
+        return false;
+    if (filename.includes("/") || filename.includes("\\"))
+        return false;
+    if (filename.includes("\0"))
+        return false;
+    return true;
+}
+/**
+ * Decide which of a type's managed entity keys should have their local file
+ * removed, given the prior sync state and the outcome of this pull's fetch.
+ *
+ * A key is pruned iff it was **managed** (present in the prior
+ * `SyncState.entities[<slot>]`, so a previous pull wrote its file) and is
+ * **absent from the server keys** this pull fetched. A local file that was
+ * never in prior state was hand-authored — it is left alone and reported by
+ * `sync diff` as new.
+ *
+ * Pure and side-effect-free (the caller owns the `unlinkSync`) so the safety
+ * rules are unit-testable without a live server.
+ */
+export function planPrune(input) {
+    const { resourceType, priorKeys, presence, enabled } = input;
+    // Which managed keys the server did not list. Only meaningful when the fetch
+    // succeeded; on a failed fetch we know nothing and must not act.
+    const absentKeys = presence.ok
+        ? priorKeys.filter((key) => !new Set(presence.serverKeys).has(key))
+        : [];
+    if (!enabled) {
+        return {
+            keys: [],
+            skipped: true,
+            skipReason: "disabled",
+            unsafeKeys: [],
+            unprunedAbsentKeys: absentKeys,
+        };
+    }
+    if (!presence.ok) {
+        return {
+            keys: [],
+            skipped: true,
+            skipReason: "fetch-failed",
+            unsafeKeys: [],
+            unprunedAbsentKeys: [],
+        };
+    }
+    // A 200 is not a complete list. Deleting a file because a truncated listing
+    // omitted its entity is unrecoverable-looking to the operator (the entity is
+    // still live, so no later pull rewrites the file), which is worse than
+    // leaving a stale file behind. See `listingComplete`.
+    if (!resourceType.listingComplete) {
+        return {
+            keys: [],
+            skipped: true,
+            skipReason: "listing-incomplete",
+            unsafeKeys: [],
+            unprunedAbsentKeys: absentKeys,
+        };
+    }
+    const keys = [];
+    const unsafeKeys = [];
+    for (const key of absentKeys) {
+        if (!isSafeSyncFilename(resourceType.fileFromKey(key))) {
+            unsafeKeys.push(key);
+            continue;
+        }
+        keys.push(key);
+    }
+    return { keys, skipped: false, unsafeKeys, unprunedAbsentKeys: [] };
+}
+/**
+ * Copy prior state entries for entities the server listed but this pull did not
+ * write (e.g. a script with no active config, or an email template whose detail
+ * fetch failed). Without this the entity would drop out of the state slot and
+ * look hand-authored to the next pull, so its stale file could never be pruned.
+ */
+export function preserveUnwrittenEntries(written, prior, serverKeys) {
+    if (!prior)
+        return written;
+    for (const key of serverKeys) {
+        if (!(key in written) && key in prior) {
+            written[key] = prior[key];
+        }
+    }
+    return written;
+}
+/**
+ * Best-effort check for uncommitted git changes at `path` (a file or a
+ * directory). Returns false when git isn't available, the path isn't in a
+ * repository, or anything else goes wrong — the caller treats "unknown" as
+ * "no local edits", so this never blocks on a non-git checkout.
+ *
+ * `path` is passed as an argument, never interpolated into a shell string:
+ * on the prune path its basename derives from a server entity name, and entity
+ * names are free-form (a rule set may legitimately be named ``a`b`` or `a$b`).
+ * `execFileSync` runs git directly with no shell, so no name can be read as
+ * a command.
+ *
+ * `includeUntracked` decides whether an untracked file counts as a change:
+ * - `true` (default) suits "am I about to overwrite something?" — `sync revert`
+ *   would clobber an untracked file just the same.
+ * - `false` suits "did the operator edit this file?" — an untracked file is the
+ *   ordinary state of a pulled file in a sync dir that was never committed, and
+ *   is not evidence of a local edit.
+ */
+export async function hasUncommittedChanges(path, options = {}) {
+    const { includeUntracked = true } = options;
+    if (!existsSync(path))
+        return false;
+    try {
+        const { execFileSync } = await import("child_process");
+        // Run git from the path's own location, not the process cwd: the sync slot
+        // can sit in a different repository than the one the CLI was invoked from
+        // (or in none at all).
+        const cwd = statSync(path).isDirectory() ? path : dirname(path);
+        const args = ["status", "--porcelain"];
+        if (!includeUntracked)
+            args.push("-uno");
+        args.push("--", path);
+        const out = execFileSync("git", args, {
+            cwd,
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf-8",
+        });
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The phrase pull and diff both use for an entity that is no longer exported.
+ *
+ * The plan of record asked for "archived or deleted" on the assumption that
+ * archiving drops an entity from the export. It does not: the list endpoints
+ * filter by status only when `?status=` is passed and pull never passes it
+ * (`listAppPrompts`/`listAppIntegrations` in `src/admin-api.ts`; `fetchAll` in
+ * `cli/src/commands/sync.ts`). An archived entity stays in the export and its
+ * TOML is rewritten with `status = "archived"`, so it is never pruned. The only
+ * way to be absent from the export is to have been deleted.
+ */
+export const ABSENT_FROM_EXPORT = "absent from sync export (deleted on server)";
+/** `sync diff` status for a local file whose managed entity is gone. */
+export const LOCAL_ONLY_ABSENT = "local only (absent from export)";
+/** `sync diff` status for a local file the operator authored themselves. */
+export const LOCAL_ONLY_NEW = "local only";
+/**
+ * Classify a local file that has no matching server entity (issue #1659).
+ *
+ * The two cases look identical on disk but mean opposite things. A key a prior
+ * pull managed means the entity was deleted server-side and this stale file
+ * will RE-create it on the next push. A key never pulled means the operator
+ * authored the file and push creating it is the intent.
+ */
+export function classifyLocalOnly(priorEntities, slot, key) {
+    const managed = (priorEntities?.[slot] ?? {});
+    return key in managed ? LOCAL_ONLY_ABSENT : LOCAL_ONLY_NEW;
+}
+/**
+ * Remove the local files for `keys` (as decided by `planPrune`), along with any
+ * sidecar `<key>.tests/` directory.
+ *
+ * A file with uncommitted git edits is kept and reported instead: the operator
+ * may be mid-way through authoring a change they meant to push. Everything
+ * removed here is recoverable from the pre-pull snapshot via `sync revert`.
+ */
+export async function applyPrune(options) {
+    const { configDir, resourceType, keys, testCaseEntities, logger } = options;
+    const log = logger ?? (() => { });
+    const result = {
+        prunedKeys: [],
+        removed: [],
+        keptWithLocalEdits: [],
+        removedTestCaseKeys: [],
+    };
+    for (const key of keys) {
+        const filename = resourceType.fileFromKey(key);
+        const relativePath = `${resourceType.dir}/${filename}`;
+        const filePath = join(configDir, resourceType.dir, filename);
+        if (!existsSync(filePath))
+            continue;
+        // Untracked does not mean edited: in a sync dir that was never committed
+        // (or in no repository at all) every pulled file is untracked, and counting
+        // that as a local edit would keep every stale file and leave #1659 unfixed.
+        if (await hasUncommittedChanges(filePath, { includeUntracked: false })) {
+            result.keptWithLocalEdits.push(key);
+            log(`  Kept ${relativePath} — ${ABSENT_FROM_EXPORT} but the file has ` +
+                "uncommitted local edits; remove it yourself or re-create the entity on the server");
+            continue;
+        }
+        unlinkSync(filePath);
+        result.prunedKeys.push(key);
+        result.removed.push(relativePath);
+        log(`  Removed ${relativePath} — ${ABSENT_FROM_EXPORT}`);
+        if (!resourceType.testBlockType)
+            continue;
+        // Sidecar tests: `<key>.tests/` holds the block's test-case TOMLs and their
+        // attachment directories. With the block gone there is nothing to run them
+        // against, so they go too — along with their sync-state records.
+        const testsDirName = `${key}.tests`;
+        const testsDir = join(configDir, resourceType.dir, testsDirName);
+        if (existsSync(testsDir) && isSafeSyncFilename(testsDirName)) {
+            rmSync(testsDir, { recursive: true, force: true });
+            result.removed.push(`${resourceType.dir}/${testsDirName}`);
+            log(`  Removed ${resourceType.dir}/${testsDirName} — ${ABSENT_FROM_EXPORT}`);
+        }
+        if (testCaseEntities) {
+            for (const [stateKey, entry] of Object.entries(testCaseEntities)) {
+                if (entry?.blockType === resourceType.testBlockType &&
+                    entry?.blockKey === key) {
+                    delete testCaseEntities[stateKey];
+                    result.removedTestCaseKeys.push(stateKey);
+                }
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=sync-resource-types.js.map

package/dist/src/lib/sync-resource-types.js.map

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

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

@@ -16,11 +16,24 @@
  *     `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` and `.getStatus` for every
- *     non-reserved workflow (the typed async path, issue #1512 — async-only
- *     workflows are exactly the ones that need a typed `getStatus`). No
- *     `.terminate` member is emitted (the factory stays a start/status helper;
- *     typed termination is available via the client's explicit `terminate<O>`).
+ *     rejects run-sync otherwise); `.start`, `.getStatus`, and `.terminate` for
+ *     every non-reserved workflow (the typed async path, issue #1512 —
+ *     async-only workflows are exactly the ones that need a typed `getStatus` /
+ *     `terminate`). `.terminate` binds `<Key>Output` (a terminated run can carry
+ *     partial output); issue #1543 added the member, reversing #1512's
+ *     start/status-only decision.
+ *   - `.define` is emitted only for an apply-mode workflow
+ *     (`requiresClientApply !== false`, the server's default). It binds
+ *     `<Key>Output` so the `onApply` handler's `output` is the workflow's real
+ *     output type rather than `any` (issue #1543, on top of #1542's
+ *     `define<O>` / `WorkflowDefineOptions<O>` generics). `getPendingApplies`
+ *     gets no member — #1542 made it a concrete `PendingApply[]` with no output
+ *     to bind, and it is scoped to a document rather than a workflow.
+ *   - `.cronTriggers.{create,update}` bind `<Key>Input` to the trigger's
+ *     `rootInput` and pin `workflowKey`, so a cron helper can't be redirected at
+ *     another workflow (issue #1543). `rootInput` is `Partial<<Key>Input>` for
+ *     an object-shaped input schema (an `inputMapping` may supply the rest) and
+ *     the full `<Key>Input` otherwise.
  *   - `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

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

@@ -16,11 +16,24 @@
  *     `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` and `.getStatus` for every
- *     non-reserved workflow (the typed async path, issue #1512 — async-only
- *     workflows are exactly the ones that need a typed `getStatus`). No
- *     `.terminate` member is emitted (the factory stays a start/status helper;
- *     typed termination is available via the client's explicit `terminate<O>`).
+ *     rejects run-sync otherwise); `.start`, `.getStatus`, and `.terminate` for
+ *     every non-reserved workflow (the typed async path, issue #1512 —
+ *     async-only workflows are exactly the ones that need a typed `getStatus` /
+ *     `terminate`). `.terminate` binds `<Key>Output` (a terminated run can carry
+ *     partial output); issue #1543 added the member, reversing #1512's
+ *     start/status-only decision.
+ *   - `.define` is emitted only for an apply-mode workflow
+ *     (`requiresClientApply !== false`, the server's default). It binds
+ *     `<Key>Output` so the `onApply` handler's `output` is the workflow's real
+ *     output type rather than `any` (issue #1543, on top of #1542's
+ *     `define<O>` / `WorkflowDefineOptions<O>` generics). `getPendingApplies`
+ *     gets no member — #1542 made it a concrete `PendingApply[]` with no output
+ *     to bind, and it is scoped to a document rather than a workflow.
+ *   - `.cronTriggers.{create,update}` bind `<Key>Input` to the trigger's
+ *     `rootInput` and pin `workflowKey`, so a cron helper can't be redirected at
+ *     another workflow (issue #1543). `rootInput` is `Partial<<Key>Input>` for
+ *     an object-shaped input schema (an `inputMapping` may supply the rest) and
+ *     the full `<Key>Input` otherwise.
  *   - `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
@@ -30,26 +43,16 @@
  *     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 { schemaToTsType } from "./schemaToTs.js";
 import { describeSchema } from "./generated-schema-descriptor.js";
+import { describeWorkflowInvoker } from "./invokerIR.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`. A plain object type → an `interface`; anything else → a `type`
@@ -74,35 +77,39 @@ function renderTypeDecl(name, schema) {
  * 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.
+ *
+ * The operation metadata (key, `syncCallable`, required-vs-optional `input`,
+ * parsed schemas) comes from the SHARED `describeWorkflowInvoker` IR so the TS
+ * and Swift invokers can never disagree (#1547 binding item 5). Only the
+ * TS-specific naming + type-declaration rendering happens here.
  */
 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);
+    // shared IR uses `parseConfigToml` + `safeJsonParse` under the hood.
+    const ir = describeWorkflowInvoker({
+        fileStem: input.fileStem,
+        tomlContent: input.tomlContent,
+    });
+    if (!ir)
+        return null; // reserved workflow
+    const inputTypeName = workflowInputTypeName(ir.key);
+    const outputTypeName = workflowOutputTypeName(ir.key);
     return {
-        key,
-        syncCallable: workflow.syncCallable === true,
+        key: ir.key,
+        syncCallable: ir.syncCallable,
         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),
+        factoryName: workflowFactoryName(ir.key),
+        inputDecl: renderTypeDecl(inputTypeName, ir.inputSchema),
+        outputDecl: renderTypeDecl(outputTypeName, ir.outputSchema),
+        inputRequired: ir.inputRequired,
+        // Object-shaped only when the schema declares exactly `type: "object"` —
+        // the one case where `Partial<<Key>Input>` is a sound cron `rootInput`
+        // type. Schema-less / union / scalar / array → not object-shaped.
+        inputIsObjectShaped: ir.inputSchema !== undefined &&
+            describeSchema(ir.inputSchema).singularType === "object",
+        requiresClientApply: ir.requiresClientApply,
     };
 }
 /** Render the typed invoker factory for one workflow. */
@@ -149,6 +156,65 @@ function renderFactory(wf) {
         `        ...opts,\n` +
         `        workflowKey: ${keyLiteral},\n` +
         `      }),`);
+    // Typed termination (#1543), emitted for EVERY non-reserved workflow — any
+    // run can be terminated. `output` is bound to `<Key>Output` (a terminated run
+    // can carry partial output), same schema-less → `unknown` rule as getStatus.
+    // `runKey` stays required. Same spread-first / key-last ordering so an untyped
+    // caller cannot override the key and terminate the wrong workflow's run. This
+    // member reverses #1512's start/status-only decision.
+    lines.push(`    terminate: (opts: Omit<TerminateWorkflowOptions, "workflowKey">) =>\n` +
+        `      client.workflows.terminate<${wf.outputTypeName}>({\n` +
+        `        ...opts,\n` +
+        `        workflowKey: ${keyLiteral},\n` +
+        `      }),`);
+    // Typed apply handler (#1543 Phase 2), emitted ONLY for an apply-mode
+    // workflow (`requiresClientApply !== false` — the same default the server
+    // uses to decide a completed run needs a client apply). `WorkflowDefineOptions<O>`
+    // and `WorkflowApplyHandler<O>` come from #1542; binding `<Key>Output` here
+    // makes the `onApply` callback's `output` the workflow's real output type
+    // instead of `any`. The key is passed as a positional argument, so there is
+    // no spread a caller could use to override it.
+    //
+    // No `getPendingApplies` member: #1542 shipped it as a concrete
+    // `PendingApply[]` (the server element carries no `output`, so there is no
+    // output generic to bind), and the call is scoped to a DOCUMENT rather than
+    // a workflow — a per-workflow member would bind nothing and would wrongly
+    // suggest the result only covers this workflow.
+    if (wf.requiresClientApply) {
+        lines.push(`    define: (options: WorkflowDefineOptions<${wf.outputTypeName}>) =>\n` +
+            `      client.workflows.define<${wf.outputTypeName}>(${keyLiteral}, options),`);
+    }
+    // Typed cron-trigger create/update (#1543), folded INTO the factory (not a
+    // separate export). The client's own `rootInput` generic (#1542) is bound to
+    // `<Key>Input`: `Partial<...>` for an object-shaped schema (an `inputMapping`
+    // may supply the rest), the full type otherwise. Binding the generic rather
+    // than restating the field keeps the caller-facing params in step with the
+    // client contract — notably `update` accepts `rootInput: null` to clear a
+    // stored root input, while `create` does not (the server rejects a null there
+    // with a 400). `workflowKey` is Omit-ted from the caller-facing params and
+    // pinned LAST so a caller can't redirect the trigger at another workflow.
+    // Nothing is spread after `workflowKey` — `rootInput` rides in via `...params`
+    // — preserving the key-last convention.
+    const rootInputType = wf.inputIsObjectShaped
+        ? `Partial<${wf.inputTypeName}>`
+        : wf.inputTypeName;
+    lines.push(`    cronTriggers: {\n` +
+        `      create: (\n` +
+        `        params: Omit<CreateCronTriggerParams<${rootInputType}>, "workflowKey">\n` +
+        `      ) =>\n` +
+        `        client.cronTriggers.create<${rootInputType}>({\n` +
+        `          ...params,\n` +
+        `          workflowKey: ${keyLiteral},\n` +
+        `        }),\n` +
+        `      update: (\n` +
+        `        triggerId: string,\n` +
+        `        params: Omit<UpdateCronTriggerParams<${rootInputType}>, "workflowKey">\n` +
+        `      ) =>\n` +
+        `        client.cronTriggers.update<${rootInputType}>(triggerId, {\n` +
+        `          ...params,\n` +
+        `          workflowKey: ${keyLiteral},\n` +
+        `        }),\n` +
+        `    },`);
     lines.push(`  };`, `}`);
     return lines.join("\n");
 }
@@ -163,15 +229,24 @@ export function renderWorkflowFile(input) {
         return null;
     const fingerprint = fingerprintToml(input.tomlContent);
     // Only import the option types actually referenced, so the generated file
-    // compiles under a consumer's `noUnusedLocals`. `GetWorkflowStatusOptions` is
-    // always referenced now — every factory emits a `getStatus` member (#1512).
+    // compiles under a consumer's `noUnusedLocals`. `GetWorkflowStatusOptions`,
+    // `TerminateWorkflowOptions`, and the two cron-param types are always
+    // referenced now — every factory emits `getStatus`, `terminate` (#1512 /
+    // #1543), and `cronTriggers.{create,update}` (#1543).
     const imports = [
+        "CreateCronTriggerParams",
         "GetWorkflowStatusOptions",
         "JsBaoClient",
         "StartWorkflowOptions",
+        "TerminateWorkflowOptions",
+        "UpdateCronTriggerParams",
     ];
     if (wf.syncCallable)
         imports.push("RunSyncWorkflowOptions");
+    // Only an apply-mode workflow emits `define`, so its option type is imported
+    // only then — a non-apply-mode file would otherwise fail `noUnusedLocals`.
+    if (wf.requiresClientApply)
+        imports.push("WorkflowDefineOptions");
     imports.sort();
     const blocks = [];
     blocks.push([