zitejs 0.10.0-start.1 → 0.10.0-start.2

package/dist/cjs/check/index.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCheck = runCheck;
 const child_process_1 = require("child_process");
@@ -58,15 +91,60 @@ function bundleFailures(output) {
     }
     return failures;
 }
+const indent = (output) => output.trim().split('\n').map(l => `    ${l}`).join('\n');
+/**
+ * A Start app: `vite build` first, since it regenerates the route tree tsc
+ * reads, then tsc, then describe, which reports what the platform's build
+ * refuses, read the same way.
+ */
+async function checkStartApp(appPath) {
+    process.stdout.write('  vite build ... ');
+    const vite = run('npx', ['vite', 'build'], appPath);
+    console.log(vite.ok ? '✓' : '✗');
+    if (!vite.ok) {
+        console.log(indent(vite.output));
+        return false;
+    }
+    process.stdout.write('  tsc --noEmit ... ');
+    // --pretty for `file:line:col - error` lines, the shape the platform re-roots.
+    const tsc = run('npx', ['tsc', '--noEmit', '--pretty', '-p', 'tsconfig.app.json'], appPath);
+    console.log(tsc.ok ? '✓' : '✗');
+    if (!tsc.ok)
+        console.log(indent(tsc.output));
+    process.stdout.write('  describe ... ');
+    try {
+        const { describeBuiltApp } = await Promise.resolve().then(() => __importStar(require('../start/describeBuilt.js')));
+        const { descriptionProblems } = await Promise.resolve().then(() => __importStar(require('../start/problems.js')));
+        const problems = descriptionProblems((await describeBuiltApp(appPath)));
+        console.log(problems.length ? '✗' : '✓');
+        if (problems.length)
+            console.log(problems.map(p => `    ${p}`).join('\n'));
+        return tsc.ok && problems.length === 0;
+    }
+    catch (err) {
+        console.log('✗');
+        console.log(`    ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
 async function runCheck() {
-    const appDirs = (0, sourceRoots_js_1.listSourceDirs)();
-    if (appDirs.length === 0) {
+    const { isStartAppDir } = await Promise.resolve().then(() => __importStar(require('../start/entries.js')));
+    // Run inside a Start app, its own zitejs checks just that app: the workspace
+    // root's is a classic release that doesn't know Start.
+    const inStartApp = isStartAppDir('.');
+    const appDirs = inStartApp ? [] : (0, sourceRoots_js_1.listSourceDirs)();
+    if (!inStartApp && appDirs.length === 0) {
         console.error('No apps or automations found under apps/ or automations/.');
         process.exit(1);
     }
-    let allPassed = true;
+    let allPassed = inStartApp ? await checkStartApp('.') : true;
     for (const { root, dir: app, path: appPath } of appDirs) {
         console.log(`\n── ${appPath} ──`);
+        if (isStartAppDir(appPath)) {
+            if (!(await checkStartApp(appPath)))
+                allPassed = false;
+            continue;
+        }
         // Only tsconfig.app.json compiles anything. The app's tsconfig.json is a
         // solution-style config — `"files": []` plus a reference — so
         // `tsc --noEmit -p tsconfig.json` type-checks zero files and exits 0. It

package/dist/cjs/start/entries.d.ts

@@ -8,4 +8,9 @@ export declare const renderStartInstance: (hasAppStart: boolean) => string;
 export declare const hasAppStart: (appDir: string) => boolean;
 /** Writes `file` under `appDir` when its content differs. Returns whether it wrote. */
 export declare const writeIfChanged: (appDir: string, file: string, content: string) => boolean;
+export declare const isStartAppDir: (appPath: string) => boolean;
 export declare function regenerateStartEntries(app: SourceDir): void;
+/** App modules that mention createWorkflow: what the workflow registry imports. Describe decides what each one really exports. */
+export declare function workflowFiles(appDir: string): string[];
+/** The registry zite() builds in place of zitejs's empty one. */
+export declare const renderWorkflowModules: (appDir: string, files: string[]) => string;

package/dist/cjs/start/entries.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeIfChanged = exports.hasAppStart = exports.renderStartInstance = exports.renderStartServerEntry = exports.START_INSTANCE_ENTRY = exports.START_SERVER_ENTRY = void 0;
+exports.renderWorkflowModules = exports.isStartAppDir = exports.writeIfChanged = exports.hasAppStart = exports.renderStartInstance = exports.renderStartServerEntry = exports.START_INSTANCE_ENTRY = exports.START_SERVER_ENTRY = void 0;
 exports.regenerateStartEntries = regenerateStartEntries;
+exports.workflowFiles = workflowFiles;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 exports.START_SERVER_ENTRY = ".zite/server.ts";
@@ -42,14 +43,16 @@ const writeIfChanged = (appDir, file, content) => {
     return true;
 };
 exports.writeIfChanged = writeIfChanged;
-const isStartApp = (app) => {
+const isStartAppDir = (appPath) => {
     try {
-        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(app.path, "zite.config.json"), "utf-8"))?.runtime === "start";
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(appPath, "zite.config.json"), "utf-8"))?.runtime === "start";
     }
     catch {
         return false;
     }
 };
+exports.isStartAppDir = isStartAppDir;
+const isStartApp = (app) => (0, exports.isStartAppDir)(app.path);
 function regenerateStartEntries(app) {
     if (!isStartApp(app))
         return;
@@ -62,3 +65,29 @@ function regenerateStartEntries(app) {
             console.log(`Wrote ${(0, node_path_1.join)(app.path, file)}`);
     }
 }
+const SOURCE_FILE = /\.[mc]?[jt]sx?$/;
+const NOT_APP_CODE = /(\.(test|spec)\.[^.]+|\.d\.ts|routeTree\.gen\.ts)$/;
+/** App modules that mention createWorkflow: what the workflow registry imports. Describe decides what each one really exports. */
+function workflowFiles(appDir) {
+    const found = [];
+    const walk = (dir) => {
+        for (const entry of (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })) {
+            const full = (0, node_path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name !== "node_modules")
+                    walk(full);
+            }
+            else if (SOURCE_FILE.test(entry.name) && !NOT_APP_CODE.test(entry.name) && (0, node_fs_1.readFileSync)(full, "utf-8").includes("createWorkflow")) {
+                found.push((0, node_path_1.relative)(appDir, full).split("\\").join("/"));
+            }
+        }
+    };
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(appDir, "src")))
+        walk((0, node_path_1.join)(appDir, "src"));
+    return found.sort();
+}
+/** The registry zite() builds in place of zitejs's empty one. */
+const renderWorkflowModules = (appDir, files) => `export const workflowModules = {\n${files
+    .map((file) => `  ${JSON.stringify(file)}: () => import(${JSON.stringify((0, node_path_1.join)(appDir, file))}),`)
+    .join("\n")}\n};\n`;
+exports.renderWorkflowModules = renderWorkflowModules;

package/dist/cjs/start/problems.d.ts

@@ -0,0 +1,19 @@
+type WithProblems = {
+    problems: string[];
+};
+type Described = {
+    functions: Array<WithProblems & {
+        id: string;
+        file?: string;
+    }>;
+    routes: Array<WithProblems & {
+        path: string;
+    }>;
+    workflows?: Array<WithProblems & {
+        id: string;
+        file: string;
+    }>;
+};
+/** Every problem in a description, one line each, named by its rule. Any of them fails the build. */
+export declare function descriptionProblems(description: Described): string[];
+export {};

package/dist/cjs/start/problems.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.descriptionProblems = descriptionProblems;
+/** Every problem in a description, one line each, named by its rule. Any of them fails the build. */
+function descriptionProblems(description) {
+    return [
+        ...description.functions.flatMap((f) => f.problems.map((p) => `function ${f.id}${f.file ? ` (${f.file})` : ""}: ${p}`)),
+        ...description.routes.flatMap((r) => r.problems.map((p) => `route ${r.path}: ${p}`)),
+        ...(description.workflows ?? []).flatMap((w) => w.problems.map((p) => `workflow ${w.id} (${w.file}): ${p}`)),
+    ];
+}

package/dist/esm/check/index.js

@@ -55,15 +55,60 @@ function bundleFailures(output) {
     }
     return failures;
 }
+const indent = (output) => output.trim().split('\n').map(l => `    ${l}`).join('\n');
+/**
+ * A Start app: `vite build` first, since it regenerates the route tree tsc
+ * reads, then tsc, then describe, which reports what the platform's build
+ * refuses, read the same way.
+ */
+async function checkStartApp(appPath) {
+    process.stdout.write('  vite build ... ');
+    const vite = run('npx', ['vite', 'build'], appPath);
+    console.log(vite.ok ? '✓' : '✗');
+    if (!vite.ok) {
+        console.log(indent(vite.output));
+        return false;
+    }
+    process.stdout.write('  tsc --noEmit ... ');
+    // --pretty for `file:line:col - error` lines, the shape the platform re-roots.
+    const tsc = run('npx', ['tsc', '--noEmit', '--pretty', '-p', 'tsconfig.app.json'], appPath);
+    console.log(tsc.ok ? '✓' : '✗');
+    if (!tsc.ok)
+        console.log(indent(tsc.output));
+    process.stdout.write('  describe ... ');
+    try {
+        const { describeBuiltApp } = await import('../start/describeBuilt.js');
+        const { descriptionProblems } = await import('../start/problems.js');
+        const problems = descriptionProblems((await describeBuiltApp(appPath)));
+        console.log(problems.length ? '✗' : '✓');
+        if (problems.length)
+            console.log(problems.map(p => `    ${p}`).join('\n'));
+        return tsc.ok && problems.length === 0;
+    }
+    catch (err) {
+        console.log('✗');
+        console.log(`    ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
 export async function runCheck() {
-    const appDirs = listSourceDirs();
-    if (appDirs.length === 0) {
+    const { isStartAppDir } = await import('../start/entries.js');
+    // Run inside a Start app, its own zitejs checks just that app: the workspace
+    // root's is a classic release that doesn't know Start.
+    const inStartApp = isStartAppDir('.');
+    const appDirs = inStartApp ? [] : listSourceDirs();
+    if (!inStartApp && appDirs.length === 0) {
         console.error('No apps or automations found under apps/ or automations/.');
         process.exit(1);
     }
-    let allPassed = true;
+    let allPassed = inStartApp ? await checkStartApp('.') : true;
     for (const { root, dir: app, path: appPath } of appDirs) {
         console.log(`\n── ${appPath} ──`);
+        if (isStartAppDir(appPath)) {
+            if (!(await checkStartApp(appPath)))
+                allPassed = false;
+            continue;
+        }
         // Only tsconfig.app.json compiles anything. The app's tsconfig.json is a
         // solution-style config — `"files": []` plus a reference — so
         // `tsc --noEmit -p tsconfig.json` type-checks zero files and exits 0. It

package/dist/esm/start/describe.d.ts

@@ -1,3 +1,5 @@
+import type { LoadedWorkflow } from "./workflowRun.js";
+import type { WorkflowConfig } from "./workflow.js";
 export type Access = {
     kind: "signedIn" | "anyone" | "webhook" | "none";
     roles: string[];
@@ -7,6 +9,8 @@ export type DescribedFunction = {
     name?: string;
     file?: string;
     method?: string;
+    /** From the factory's `description` option; display-only. */
+    description?: string;
     access: Access;
     input?: unknown;
     problems: string[];
@@ -16,9 +20,18 @@ export type DescribedRoute = {
     methods: Record<string, Access>;
     problems: string[];
 };
+export type DescribedWorkflow = {
+    id: string;
+    file: string;
+    description?: string;
+    schedule?: WorkflowConfig["schedule"];
+    trigger?: WorkflowConfig["trigger"];
+    problems: string[];
+};
 export type Description = {
     functions: DescribedFunction[];
     routes: DescribedRoute[];
+    workflows: DescribedWorkflow[];
 };
 export declare function describeFunction(id: string, request: Request): Promise<DescribedFunction>;
 type RouteLike = {
@@ -32,9 +45,12 @@ type RouteLike = {
     };
 };
 export declare function describeRoutes(routesById: Record<string, RouteLike>): DescribedRoute[];
+export declare function describeWorkflows(workflows: LoadedWorkflow[]): DescribedWorkflow[];
 export declare function describeApp(opts: {
     fnIds: string[];
+    descriptions?: Record<string, string>;
     getRouter: () => unknown;
     request: Request;
+    workflows?: LoadedWorkflow[];
 }): Promise<Description>;
 export {};

package/dist/esm/start/describe.js

@@ -38,6 +38,8 @@ const describeProbe = createMiddleware({ type: "function" }).server(({ serverFnM
         Object.assign(probe, { meta: serverFnMeta, method, reached: true });
     return "zite:describe";
 });
+const SERVER_ONLY = "server-only: nothing in the browser calls it, and a server function that only other server functions call can't run. " +
+    "Move the shared logic into a *.server.ts helper and call that.";
 export async function describeFunction(id, request) {
     const problems = [];
     const seen = [];
@@ -64,7 +66,14 @@ export async function describeFunction(id, request) {
         await runWithStartContext(startContext, () => createSsrRpc(id)({ data: undefined, context: {} }));
     }
     catch (error) {
-        problems.push(`probe-failed: ${error instanceof Error ? error.message : String(error)}`);
+        const message = error instanceof Error ? error.message : String(error);
+        // TanStack registers only functions something can call through it. One that
+        // only other server functions call isn't registered, and calling it fails.
+        if (message === `Server function info not found for ${id}`) {
+            probe = null;
+            return { id, access: { kind: "none", roles: [] }, problems: [SERVER_ONLY] };
+        }
+        problems.push(`probe-failed: ${message}`);
     }
     const state = probe;
     probe = null;
@@ -113,10 +122,26 @@ export function describeRoutes(routesById) {
     }
     return out;
 }
+// A workflow's id is its export name: what the host invokes it by and the editor shows.
+export function describeWorkflows(workflows) {
+    return workflows.map(({ id, file, workflow }) => {
+        const problems = [];
+        if (id === "default")
+            problems.push("workflow-default-export: export it by name, which becomes its id");
+        const elsewhere = workflows.find((other) => other.id === id && other.file !== file);
+        if (elsewhere)
+            problems.push(`duplicate-workflow: ${id} is also exported from ${elsewhere.file}`);
+        const { description, schedule, trigger } = workflow.config;
+        return { id, file, description, ...(schedule ? { schedule } : { trigger }), problems };
+    });
+}
 export async function describeApp(opts) {
     const functions = [];
-    for (const id of opts.fnIds)
-        functions.push(await describeFunction(id, opts.request));
+    for (const id of opts.fnIds) {
+        const described = await describeFunction(id, opts.request);
+        const description = opts.descriptions?.[id];
+        functions.push(description ? { ...described, description } : described);
+    }
     const router = (await opts.getRouter());
-    return { functions, routes: describeRoutes(router.routesById) };
+    return { functions, routes: describeRoutes(router.routesById), workflows: describeWorkflows(opts.workflows ?? []) };
 }

package/dist/esm/start/descriptions.d.ts

@@ -0,0 +1,4 @@
+/** `name -> description` for each top-level const built with a description option. */
+export declare function factoryDescriptions(program: {
+    body: unknown[];
+}): Map<string, string>;

package/dist/esm/start/descriptions.js

@@ -0,0 +1,47 @@
+const stringValue = (node) => {
+    if (node?.type === "Literal" && typeof node.value === "string")
+        return node.value;
+    const quasis = node?.quasis;
+    if (node?.type === "TemplateLiteral" && node.expressions.length === 0)
+        return quasis?.[0]?.value.cooked;
+    return undefined;
+};
+const descriptionProperty = (node) => {
+    for (const property of node.properties) {
+        const key = property.key;
+        const named = key?.type === "Identifier" ? key.name : key?.type === "Literal" ? key.value : undefined;
+        if (property.type === "Property" && named === "description")
+            return stringValue(property.value);
+    }
+    return undefined;
+};
+// Walks a builder chain, `signedInFn({ description }).validator(…).handler(…)`, to an object option.
+const descriptionIn = (node) => {
+    if (node?.type === "CallExpression") {
+        for (const arg of node.arguments) {
+            const found = arg.type === "ObjectExpression" ? descriptionProperty(arg) : undefined;
+            if (found !== undefined)
+                return found;
+        }
+        return descriptionIn(node.callee);
+    }
+    if (node?.type === "MemberExpression")
+        return descriptionIn(node.object);
+    return undefined;
+};
+/** `name -> description` for each top-level const built with a description option. */
+export function factoryDescriptions(program) {
+    const found = new Map();
+    for (const statement of program.body) {
+        const declaration = (statement.type === "ExportNamedDeclaration" ? statement.declaration : statement);
+        if (declaration?.type !== "VariableDeclaration")
+            continue;
+        for (const declarator of declaration.declarations) {
+            const id = declarator.id;
+            const description = descriptionIn(declarator.init);
+            if (id.type === "Identifier" && description)
+                found.set(id.name, description);
+        }
+    }
+    return found;
+}

package/dist/esm/start/entries.d.ts

@@ -8,4 +8,9 @@ export declare const renderStartInstance: (hasAppStart: boolean) => string;
 export declare const hasAppStart: (appDir: string) => boolean;
 /** Writes `file` under `appDir` when its content differs. Returns whether it wrote. */
 export declare const writeIfChanged: (appDir: string, file: string, content: string) => boolean;
+export declare const isStartAppDir: (appPath: string) => boolean;
 export declare function regenerateStartEntries(app: SourceDir): void;
+/** App modules that mention createWorkflow: what the workflow registry imports. Describe decides what each one really exports. */
+export declare function workflowFiles(appDir: string): string[];
+/** The registry zite() builds in place of zitejs's empty one. */
+export declare const renderWorkflowModules: (appDir: string, files: string[]) => string;

package/dist/esm/start/entries.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
 export const START_SERVER_ENTRY = ".zite/server.ts";
 export const START_INSTANCE_ENTRY = ".zite/start.ts";
 const APP_START_FILES = ["src/start.ts", "src/start.tsx"];
@@ -34,14 +34,15 @@ export const writeIfChanged = (appDir, file, content) => {
     writeFileSync(target, content);
     return true;
 };
-const isStartApp = (app) => {
+export const isStartAppDir = (appPath) => {
     try {
-        return JSON.parse(readFileSync(join(app.path, "zite.config.json"), "utf-8"))?.runtime === "start";
+        return JSON.parse(readFileSync(join(appPath, "zite.config.json"), "utf-8"))?.runtime === "start";
     }
     catch {
         return false;
     }
 };
+const isStartApp = (app) => isStartAppDir(app.path);
 export function regenerateStartEntries(app) {
     if (!isStartApp(app))
         return;
@@ -54,3 +55,28 @@ export function regenerateStartEntries(app) {
             console.log(`Wrote ${join(app.path, file)}`);
     }
 }
+const SOURCE_FILE = /\.[mc]?[jt]sx?$/;
+const NOT_APP_CODE = /(\.(test|spec)\.[^.]+|\.d\.ts|routeTree\.gen\.ts)$/;
+/** App modules that mention createWorkflow: what the workflow registry imports. Describe decides what each one really exports. */
+export function workflowFiles(appDir) {
+    const found = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name !== "node_modules")
+                    walk(full);
+            }
+            else if (SOURCE_FILE.test(entry.name) && !NOT_APP_CODE.test(entry.name) && readFileSync(full, "utf-8").includes("createWorkflow")) {
+                found.push(relative(appDir, full).split("\\").join("/"));
+            }
+        }
+    };
+    if (existsSync(join(appDir, "src")))
+        walk(join(appDir, "src"));
+    return found.sort();
+}
+/** The registry zite() builds in place of zitejs's empty one. */
+export const renderWorkflowModules = (appDir, files) => `export const workflowModules = {\n${files
+    .map((file) => `  ${JSON.stringify(file)}: () => import(${JSON.stringify(join(appDir, file))}),`)
+    .join("\n")}\n};\n`;

package/dist/esm/start/index.d.ts

@@ -1,6 +1,9 @@
 import type { User } from "./types.js";
 export type { User, ZiteRequestContext } from "./types.js";
 export { createZiteRouter, type ZiteRouterContext } from "./router.js";
+export { createWorkflow, type Workflow, type WorkflowArgs, type WorkflowConfig } from "./workflow.js";
+export type { ZiteSchedule } from "../schedules/index.js";
+export type { ZiteTrigger } from "../backend/index.js";
 declare module "@tanstack/start-client-core" {
     interface ServerFnOptions {
         /** What this function does, in a sentence. Shown in the editor. */

package/dist/esm/start/index.js

@@ -4,6 +4,7 @@ import { USAGE_TOKEN_QUERY_PARAM } from "../auth/constants.js";
 import { currentHost } from "./host.js";
 import { getHost, inScope, runInScope } from "./scope.js";
 export { createZiteRouter } from "./router.js";
+export { createWorkflow } from "./workflow.js";
 const STATUS = {
     BAD_REQUEST: 400,
     UNAUTHORIZED: 401,

package/dist/esm/start/instance.js

@@ -3,6 +3,7 @@
 import { createCsrfMiddleware, createMiddleware, createStart } from "@tanstack/react-start";
 import { createSerializationAdapter, redirect } from "@tanstack/react-router";
 import { isSignInRequired, loginHref, ZiteError } from "./index.js";
+import { errorOf, preview } from "./runLog.js";
 import { getHost, inScope } from "./scope.js";
 // TanStack drops its default CSRF check once an app has a start instance.
 const csrf = createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === "serverFn" });
@@ -21,23 +22,6 @@ const signInOn401 = createMiddleware({ type: "function" }).client(async ({ next
         throw redirect({ href, reloadDocument: true });
     }
 });
-const PREVIEW_LIMIT = 8_000;
-const preview = (value) => {
-    if (value === undefined)
-        return undefined;
-    if (typeof value === "object" && value !== null && Symbol.asyncIterator in value)
-        return "[stream]";
-    try {
-        const json = JSON.stringify(value);
-        return json && json.length > PREVIEW_LIMIT ? `${json.slice(0, PREVIEW_LIMIT)}…` : json;
-    }
-    catch {
-        return "[unserializable]";
-    }
-};
-const errorOf = (error) => error instanceof ZiteError
-    ? { code: error.code, message: error.message }
-    : { code: "INTERNAL_ERROR", message: error instanceof Error ? error.message : String(error) };
 // Records each call for the run log. The host's own record of the request is the
 // floor; this adds what only the app sees: decoded input, output and errors.
 const runCapture = createMiddleware({ type: "function" }).server(async ({ next, data, serverFnMeta }) => {

package/dist/esm/start/problems.d.ts

@@ -0,0 +1,19 @@
+type WithProblems = {
+    problems: string[];
+};
+type Described = {
+    functions: Array<WithProblems & {
+        id: string;
+        file?: string;
+    }>;
+    routes: Array<WithProblems & {
+        path: string;
+    }>;
+    workflows?: Array<WithProblems & {
+        id: string;
+        file: string;
+    }>;
+};
+/** Every problem in a description, one line each, named by its rule. Any of them fails the build. */
+export declare function descriptionProblems(description: Described): string[];
+export {};

package/dist/esm/start/problems.js

@@ -0,0 +1,8 @@
+/** Every problem in a description, one line each, named by its rule. Any of them fails the build. */
+export function descriptionProblems(description) {
+    return [
+        ...description.functions.flatMap((f) => f.problems.map((p) => `function ${f.id}${f.file ? ` (${f.file})` : ""}: ${p}`)),
+        ...description.routes.flatMap((r) => r.problems.map((p) => `route ${r.path}: ${p}`)),
+        ...(description.workflows ?? []).flatMap((w) => w.problems.map((p) => `workflow ${w.id} (${w.file}): ${p}`)),
+    ];
+}

package/dist/esm/start/runLog.d.ts

@@ -0,0 +1,5 @@
+export declare const preview: (value: unknown) => string | undefined;
+export declare const errorOf: (error: unknown) => {
+    code: string;
+    message: string;
+};

package/dist/esm/start/runLog.js

@@ -0,0 +1,18 @@
+import { ZiteError } from "./index.js";
+const PREVIEW_LIMIT = 8_000;
+export const preview = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "object" && value !== null && Symbol.asyncIterator in value)
+        return "[stream]";
+    try {
+        const json = JSON.stringify(value);
+        return json && json.length > PREVIEW_LIMIT ? `${json.slice(0, PREVIEW_LIMIT)}…` : json;
+    }
+    catch {
+        return "[unserializable]";
+    }
+};
+export const errorOf = (error) => error instanceof ZiteError
+    ? { code: error.code, message: error.message }
+    : { code: "INTERNAL_ERROR", message: error instanceof Error ? error.message : String(error) };

package/dist/esm/start/server.d.ts

@@ -31,6 +31,8 @@ export declare function installPlatformTransport(call: (input: PlatformCallInput
 export declare function hostContextFromRequest(request: Request): ZiteRequestContext;
 /** Every server function TanStack compiled, written in by `zite()` at build. Empty in dev, where TanStack doesn't call its id hook. */
 export declare const builtFunctionIds: () => string[];
+/** Each server function's `description` option, written in by `zite()` at build. */
+export declare const builtFunctionDescriptions: () => Record<string, string>;
 type Fetch = (request: Request, ...rest: unknown[]) => Promise<Response> | Response;
 /**
  * The fetch handler of a Start app's server entry. Describe calls get the app's

package/dist/esm/start/server.js

@@ -1,5 +1,7 @@
 import { describeApp } from "./describe.js";
+import { preview } from "./runLog.js";
 import { getHost, requireScope, runWithHost } from "./scope.js";
+import { loadWorkflows, loggedInput, runWorkflow } from "./workflowRun.js";
 export { runWithHost } from "./scope.js";
 export { describeApp } from "./describe.js";
 /**
@@ -38,6 +40,16 @@ export function hostContextFromRequest(request) {
 }
 /** Every server function TanStack compiled, written in by `zite()` at build. Empty in dev, where TanStack doesn't call its id hook. */
 export const builtFunctionIds = () => "__ZITE_FN_IDS__".split(",").filter((id) => id && !id.startsWith("__ZITE"));
+const parseDescriptions = (json) => {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+};
+/** Each server function's `description` option, written in by `zite()` at build. */
+export const builtFunctionDescriptions = () => parseDescriptions("__ZITE_FN_DESCRIPTIONS__");
 // Server functions also run while a streamed page renders, so the run log is
 // complete only once the body has been read to the end.
 const onBodyEnd = (response, done) => {
@@ -47,6 +59,30 @@ const onBodyEnd = (response, done) => {
     }
     return new Response(response.body.pipeThrough(new TransformStream({ flush: done })), response);
 };
+const INVOKE_PATH = "/_zite/invoke";
+// The host sends `{ input }`; a platform-fired run's input carries the runner's
+// `__cron`, `__poll` or `__webhook` state, exactly as for classic endpoints.
+async function invokeWorkflow(request, host, workflows) {
+    if (request.method !== "POST" || new URL(request.url).pathname !== INVOKE_PATH)
+        return new Response("Not found", { status: 404 });
+    const name = host.invoke?.name;
+    const found = workflows.find((w) => w.id === name);
+    if (!found)
+        return Response.json({ ok: false, error: { code: "NOT_FOUND", message: `No workflow named ${name}` } }, { status: 404 });
+    const input = (await request.json().catch(() => ({})))?.input;
+    const startedAt = Date.now();
+    const result = await runWorkflow(found.workflow, input);
+    host.runs.push({
+        fn: `workflow:${found.id}`,
+        name: found.id,
+        nested: false,
+        startedAt,
+        durationMs: Date.now() - startedAt,
+        input: preview(loggedInput(input)),
+        ...(result.ok ? { output: preview(result.output) } : { error: result.error }),
+    });
+    return Response.json(result, { status: result.ok ? 200 : 500 });
+}
 /**
  * The fetch handler of a Start app's server entry. Describe calls get the app's
  * description; everything else runs TanStack with the host's identity in
@@ -62,13 +98,22 @@ export function createZiteFetch(options) {
         return binding;
     };
     installPlatformTransport((call) => platform().call(call));
+    // Loaded on first use, so a page request never pays for importing workflow modules.
+    let workflows;
+    const loadedWorkflows = () => (workflows ??= loadWorkflows());
     return async (request, ...rest) => {
         binding ??= rest[0]?.ZITE;
         if (request.headers.get("x-zite-invoke") === "describe") {
-            return Response.json(await describeApp({ fnIds: builtFunctionIds(), getRouter: options.getRouter, request }));
+            return Response.json(await describeApp({
+                fnIds: builtFunctionIds(),
+                descriptions: builtFunctionDescriptions(),
+                getRouter: options.getRouter,
+                request,
+                workflows: await loadedWorkflows(),
+            }));
         }
         const host = hostContextFromRequest(request);
-        const response = await runWithHost(host, () => options.handler.fetch(request));
+        const response = await runWithHost(host, async () => host.invoke?.kind === "workflow" ? invokeWorkflow(request, host, await loadedWorkflows()) : options.handler.fetch(request));
         return onBodyEnd(response, () => {
             if (!host.runs.length || !binding)
                 return;

package/dist/esm/start/vite.js

@@ -2,9 +2,13 @@ import path from "node:path";
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
 import viteReact from "@vitejs/plugin-react";
 import { ziteId } from "../vite/index.js";
-import { hasAppStart, renderStartInstance, renderStartServerEntry, START_INSTANCE_ENTRY, START_SERVER_ENTRY, writeIfChanged, } from "./entries.js";
-// Must match the literal in ./server.ts, which the build rewrites.
+import { factoryDescriptions } from "./descriptions.js";
+import { hasAppStart, renderStartInstance, renderStartServerEntry, renderWorkflowModules, START_INSTANCE_ENTRY, START_SERVER_ENTRY, workflowFiles, writeIfChanged, } from "./entries.js";
+// Must match the literals in ./server.ts, which the build rewrites.
 const FN_IDS_TOKEN = "__ZITE_FN_IDS__";
+const FN_DESCRIPTIONS_LITERAL = /(["'`])__ZITE_FN_DESCRIPTIONS__\1/;
+// zitejs's empty registry, which the build replaces with the app's.
+const WORKFLOW_REGISTRY = /[\\/]zitejs[\\/]dist[\\/]esm[\\/]start[\\/]workflowModules\.js$/;
 // Platform-pinned Worker settings. The deploy uses its own fixed template, so
 // these only have to match it; apps don't carry a wrangler config.
 const WORKER_COMPATIBILITY_DATE = "2026-09-25";
@@ -63,17 +67,38 @@ export function zite(options = {}) {
             };
         },
     };
+    // Each server function's `description` option, by name, for the editor.
+    const descriptions = new Map();
+    const srcDir = `${path.join(appDir, "src")}${path.sep}`;
     const functionIds = {
         name: "zite:function-ids",
         apply: "build",
+        transform(code, id) {
+            if (this.environment?.config.consumer !== "server" || !id.startsWith(srcDir) || !code.includes("description"))
+                return;
+            try {
+                for (const [name, text] of factoryDescriptions(this.parse(code)))
+                    descriptions.set(name, text);
+            }
+            catch {
+                // Display-only: an unreadable module just shows no descriptions.
+            }
+        },
         generateBundle(_, bundle) {
+            const described = Object.fromEntries([...descriptions].filter(([name]) => ids.has(name)));
             for (const chunk of Object.values(bundle)) {
-                if (chunk.type === "chunk" && chunk.code.includes(FN_IDS_TOKEN)) {
+                if (chunk.type !== "chunk")
+                    continue;
+                if (chunk.code.includes(FN_IDS_TOKEN))
                     chunk.code = chunk.code.replace(FN_IDS_TOKEN, [...ids.keys()].join(","));
-                }
+                chunk.code = chunk.code.replace(FN_DESCRIPTIONS_LITERAL, () => JSON.stringify(JSON.stringify(described)));
             }
         },
     };
+    const workflowRegistry = {
+        name: "zite:workflow-registry",
+        load: (id) => (WORKFLOW_REGISTRY.test(id.split("?")[0]) ? renderWorkflowModules(appDir, workflowFiles(appDir)) : undefined),
+    };
     return [
         tanstackStart({
             // TanStack resolves these from `src/`.
@@ -110,5 +135,6 @@ export function zite(options = {}) {
         ziteId(),
         compileZitejs,
         functionIds,
+        workflowRegistry,
     ];
 }

package/dist/esm/start/workflow.d.ts

@@ -0,0 +1,36 @@
+import type { ZiteTrigger, ZiteTriggerContext } from "../backend/index.js";
+import type { ZiteSchedule } from "../schedules/index.js";
+declare const WORKFLOW: unique symbol;
+export type WorkflowConfig = {
+    /** What this workflow does, in a sentence. Shown in the editor. */
+    description?: string;
+} & ({
+    schedule: ZiteSchedule;
+    trigger?: never;
+} | {
+    trigger: ZiteTrigger;
+    schedule?: never;
+});
+/** What a workflow's handler gets. A trigger adds `trigger`, typed by the kind it declares. */
+export type WorkflowArgs<TConfig extends WorkflowConfig> = {
+    input: unknown;
+} & (TConfig extends {
+    trigger: infer T;
+} ? {
+    trigger: ZiteTriggerContext<T>;
+} : unknown);
+export type Workflow<TConfig extends WorkflowConfig = WorkflowConfig> = {
+    readonly [WORKFLOW]: true;
+    readonly config: TConfig;
+    readonly handler: (args: WorkflowArgs<TConfig>) => unknown;
+};
+/**
+ * Scheduled or triggered work, in a `*.server.ts` file:
+ * `export const nightly = createWorkflow({ schedule }).handler(async () => { ... })`.
+ * Only the platform runs it. It has no user and no URL, and reads data like a server function does.
+ */
+export declare function createWorkflow<const TConfig extends WorkflowConfig>(config: TConfig): {
+    handler: (fn: (args: WorkflowArgs<TConfig>) => unknown) => Workflow<TConfig>;
+};
+export declare const isWorkflow: (value: unknown) => value is Workflow;
+export {};

package/dist/esm/start/workflow.js

@@ -0,0 +1,13 @@
+// Shared across copies of zitejs in one bundle, like the access scope.
+const WORKFLOW = Symbol.for("zitejs:workflow");
+/**
+ * Scheduled or triggered work, in a `*.server.ts` file:
+ * `export const nightly = createWorkflow({ schedule }).handler(async () => { ... })`.
+ * Only the platform runs it. It has no user and no URL, and reads data like a server function does.
+ */
+export function createWorkflow(config) {
+    return {
+        handler: (fn) => ({ [WORKFLOW]: true, config, handler: fn }),
+    };
+}
+export const isWorkflow = (value) => typeof value === "object" && value !== null && value[WORKFLOW] === true;

package/dist/esm/start/workflow.test-d.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/start/workflow.test-d.js

@@ -0,0 +1,24 @@
+import { describe, expectTypeOf, it } from "vitest";
+import { createWorkflow } from "./workflow.js";
+describe("createWorkflow handler args", () => {
+    it("gives a schedule no trigger", () => {
+        createWorkflow({ schedule: { scheduleType: "oneTime", fireAt: "2026-10-10T03:00:00Z", timezone: "UTC" } }).handler((args) => {
+            expectTypeOf(args).toEqualTypeOf();
+        });
+    });
+    it("types the trigger by the kind it declares", () => {
+        createWorkflow({ trigger: { every: "5m" } }).handler(({ trigger }) => {
+            expectTypeOf(trigger).toEqualTypeOf();
+        });
+        createWorkflow({ trigger: { integration: "slack", events: ["message.channels"] } }).handler(({ trigger }) => {
+            expectTypeOf(trigger).toEqualTypeOf();
+        });
+        createWorkflow({ trigger: { integration: "asana" } }).handler(({ trigger }) => {
+            expectTypeOf(trigger).toEqualTypeOf();
+        });
+    });
+    it("takes a schedule or a trigger, not both", () => {
+        // @ts-expect-error a workflow runs on one or the other
+        createWorkflow({ schedule: { scheduleType: "oneTime", fireAt: "x", timezone: "UTC" }, trigger: { every: "5m" } });
+    });
+});

package/dist/esm/start/workflowModules.d.ts

@@ -0,0 +1 @@
+export declare const workflowModules: Record<string, () => Promise<Record<string, unknown>>>;

package/dist/esm/start/workflowModules.js

@@ -0,0 +1,3 @@
+// Replaced at build by zite() with a lazy import of every app module that
+// mentions createWorkflow. Empty wherever the plugin didn't build the app.
+export const workflowModules = {};

package/dist/esm/start/workflowRun.d.ts

@@ -0,0 +1,80 @@
+import { type Workflow } from "./workflow.js";
+export type TriggerReport = {
+    handled: string[];
+    cursor?: string;
+};
+export type WorkflowRunResult = {
+    ok: true;
+    output: unknown;
+    trigger?: TriggerReport;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    trigger?: TriggerReport;
+};
+/**
+ * Splits the platform's state out of the input. A poll or a provider delivery
+ * with a cursor gets `seen`, `handled` and `advance`. Handled ids are reported
+ * whether or not the run throws, so an item acted on is never acted on again;
+ * the staged cursor only on success. Only ids the incoming `seen` lacked are
+ * reported: billing reads an empty list as a run that found nothing new.
+ */
+export declare function triggerContext(workflow: Workflow, rawInput: unknown): {
+    input: unknown;
+    trigger?: undefined;
+    report?: undefined;
+} | {
+    input: {
+        [x: string]: unknown;
+    };
+    trigger: {
+        provider: string;
+        deliveryId?: string | undefined;
+        headers: Record<string, unknown>;
+    } | {
+        headers?: undefined;
+    } | {
+        headers: {};
+    };
+    report?: undefined;
+} | {
+    input: {
+        [x: string]: unknown;
+    };
+    trigger: {
+        provider: string;
+        deliveryId?: string | undefined;
+        headers: Record<string, unknown>;
+        cursor: string | null;
+        seen: (id: string) => boolean;
+        handled: (id: string) => void;
+        advance: (cursor: string) => void;
+    } | {
+        headers?: undefined;
+        cursor: string | null;
+        seen: (id: string) => boolean;
+        handled: (id: string) => void;
+        advance: (cursor: string) => void;
+    } | {
+        headers: {};
+        cursor: string | null;
+        seen: (id: string) => boolean;
+        handled: (id: string) => void;
+        advance: (cursor: string) => void;
+    };
+    report: (succeeded: boolean) => TriggerReport;
+};
+/** Runs the handler in a workflow access scope: no user, and data calls allowed. */
+export declare function runWorkflow(workflow: Workflow, rawInput: unknown): Promise<WorkflowRunResult>;
+export type LoadedWorkflow = {
+    id: string;
+    file: string;
+    workflow: Workflow;
+};
+/** Every exported workflow in the app, by export name. */
+export declare function loadWorkflows(modules?: Record<string, () => Promise<Record<string, unknown>>>): Promise<LoadedWorkflow[]>;
+/** The input as the run log keeps it: a trigger's `seen` list can hold thousands of ids. */
+export declare const loggedInput: (rawInput: unknown) => unknown;

package/dist/esm/start/workflowRun.js

@@ -0,0 +1,107 @@
+// Server-only: runs a workflow the host invoked. Takes the same platform input
+// as classic triggered endpoints (`__cron`, `__poll`, `__webhook`), so the
+// runner's schedules, polls and provider deliveries work unchanged.
+import { errorOf } from "./runLog.js";
+import { runInScope } from "./scope.js";
+import { isWorkflow } from "./workflow.js";
+import { workflowModules } from "./workflowModules.js";
+const asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+const idOf = (id) => {
+    if (typeof id !== "string" && typeof id !== "number")
+        throw new TypeError(`trigger ids must be strings, got ${typeof id}`);
+    const value = String(id);
+    if (value.length === 0 || value.length > 512)
+        throw new TypeError("trigger ids must be 1 to 512 characters");
+    return value;
+};
+/**
+ * Splits the platform's state out of the input. A poll or a provider delivery
+ * with a cursor gets `seen`, `handled` and `advance`. Handled ids are reported
+ * whether or not the run throws, so an item acted on is never acted on again;
+ * the staged cursor only on success. Only ids the incoming `seen` lacked are
+ * reported: billing reads an empty list as a run that found nothing new.
+ */
+export function triggerContext(workflow, rawInput) {
+    const raw = asRecord(rawInput);
+    const { __cron, __poll, __webhook, ...input } = raw ?? {};
+    const declared = workflow.config.trigger;
+    if (!declared)
+        return { input: raw ? input : rawInput };
+    const poll = asRecord(__poll);
+    const webhook = asRecord(__webhook);
+    const delivery = typeof webhook?.provider === "string" ? webhook : null;
+    // A run with no trigger state, such as a manual one, still gets a trigger: an empty one.
+    const info = delivery
+        ? {
+            headers: asRecord(delivery.headers) ?? {},
+            ...(typeof delivery.deliveryId === "string" ? { deliveryId: delivery.deliveryId } : {}),
+            provider: delivery.provider,
+        }
+        : declared.every
+            ? {}
+            : { headers: {} };
+    if (!poll && declared.events)
+        return { input, trigger: info };
+    const state = poll ?? delivery ?? {};
+    const known = new Set(Array.isArray(state.seen) ? state.seen.map(String) : []);
+    const handled = [];
+    let staged;
+    const trigger = {
+        cursor: typeof state.cursor === "string" ? state.cursor : null,
+        seen: (id) => known.has(String(id)),
+        handled: (id) => {
+            const value = idOf(id);
+            if (known.has(value))
+                return;
+            known.add(value);
+            handled.push(value);
+        },
+        advance: (cursor) => {
+            if (typeof cursor !== "string" || cursor.length > 4096) {
+                throw new TypeError("trigger.advance takes a string of at most 4096 characters");
+            }
+            staged = cursor;
+        },
+        ...info,
+    };
+    const report = (succeeded) => ({
+        handled: handled.slice(-2000),
+        ...(succeeded && staged !== undefined ? { cursor: staged } : {}),
+    });
+    return { input, trigger, report };
+}
+/** Runs the handler in a workflow access scope: no user, and data calls allowed. */
+export async function runWorkflow(workflow, rawInput) {
+    const { input, trigger, report } = triggerContext(workflow, rawInput);
+    const args = { input, ...(trigger ? { trigger } : {}) };
+    try {
+        const output = await runInScope({ kind: "workflow", user: null }, () => workflow.handler(args));
+        return { ok: true, output, ...(report ? { trigger: report(true) } : {}) };
+    }
+    catch (error) {
+        return { ok: false, error: errorOf(error), ...(report ? { trigger: report(false) } : {}) };
+    }
+}
+/** Every exported workflow in the app, by export name. */
+export async function loadWorkflows(modules = workflowModules) {
+    const found = [];
+    for (const [file, load] of Object.entries(modules)) {
+        for (const [id, value] of Object.entries(await load()))
+            if (isWorkflow(value))
+                found.push({ id, file, workflow: value });
+    }
+    return found;
+}
+/** The input as the run log keeps it: a trigger's `seen` list can hold thousands of ids. */
+export const loggedInput = (rawInput) => {
+    const raw = asRecord(rawInput);
+    if (!raw)
+        return rawInput;
+    const out = { ...raw };
+    for (const key of ["__poll", "__webhook"]) {
+        const state = asRecord(raw[key]);
+        if (state && Array.isArray(state.seen))
+            out[key] = { ...state, seen: `[${state.seen.length} ids]` };
+    }
+    return out;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zitejs",
-  "version": "0.10.0-start.1",
+  "version": "0.10.0-start.2",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "sideEffects": false,