zitejs 0.9.140 → 0.9.142

package/dist/cjs/integrations/rules.d.ts

@@ -38,12 +38,14 @@ declare const FIELDS_BY_TYPE: {
     jira: readonly string[];
     typeform: readonly string[];
     apollo: readonly string[];
+    clay: readonly string[];
     attio: readonly string[];
     granola: readonly string[];
     clickup: readonly string[];
     dropbox: readonly string[];
     amazonS3: readonly string[];
     snowflake: readonly string[];
+    databricks: readonly string[];
     smartsuite: readonly string[];
 };
 /** A service type `integrations.get` serves: one used through its npm package with a token. */

package/dist/cjs/integrations/rules.js

@@ -47,6 +47,7 @@ const FIELDS_BY_TYPE = {
     jira: extras("cloudId", "siteUrl"),
     typeform: extras(),
     apollo: extras(),
+    clay: extras(),
     attio: extras(),
     granola: extras(),
     clickup: extras(),
@@ -57,6 +58,9 @@ const FIELDS_BY_TYPE = {
     // The SQL API lives on each account's own host, and the token is pinned to
     // one role; the warehouse is optional and falls back to the user's default.
     snowflake: extras("accountUrl", "role", "warehouse"),
+    // A statement is addressed by workspace host and SQL warehouse, and the token
+    // derives neither.
+    databricks: extras("host", "warehouseId"),
     // Every request names the workspace in an Account-Id header beside the key.
     smartsuite: extras("workspaceId"),
 };

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

@@ -0,0 +1,3 @@
+/** Describes a built Start app from its `dist/server`: a Workers build in workerd, a Node build in-process. */
+export declare function describeBuiltApp(appDir: string): Promise<unknown>;
+export declare function runDescribe(): Promise<void>;

package/dist/cjs/start/describeBuilt.js

@@ -0,0 +1,106 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeBuiltApp = describeBuiltApp;
+exports.runDescribe = runDescribe;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_net_1 = require("node:net");
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+// Only the host can set x-zite-* in production: the front strips them from public traffic.
+const DESCRIBE_HEADERS = { "x-zite-invoke": "describe" };
+// Not "localhost": it can resolve to ::1 for vite's listen and to 127.0.0.1 for fetch.
+const HOST = "127.0.0.1";
+const freePort = () => new Promise((resolve, reject) => {
+    const server = (0, node_net_1.createServer)();
+    server.once("error", reject);
+    server.listen(0, HOST, () => {
+        const { port } = server.address();
+        server.close(() => resolve(port));
+    });
+});
+// A Workers build runs where it will run: workerd, through the app's own
+// `vite preview`, so it uses the same Cloudflare plugin and config as the build.
+async function describeInWorkerd(appDir) {
+    const port = await freePort();
+    // Its own process group, so stopping it also stops vite and workerd under npx.
+    const preview = (0, node_child_process_1.spawn)("npx", ["--no-install", "vite", "preview", "--host", HOST, "--port", String(port), "--strictPort"], {
+        cwd: appDir,
+        stdio: ["ignore", "ignore", "pipe"],
+        detached: true,
+    });
+    let stderr = "";
+    preview.stderr.on("data", (chunk) => (stderr += chunk));
+    try {
+        const deadline = Date.now() + 60_000;
+        while (true) {
+            try {
+                const response = await fetch(`http://${HOST}:${port}/`, { headers: DESCRIBE_HEADERS });
+                // Right after start, preview can answer before the Worker does; only the
+                // app's own describe answer is JSON.
+                if (response.ok && response.headers.get("content-type")?.includes("application/json")) {
+                    return await response.json();
+                }
+            }
+            catch { }
+            if (preview.exitCode !== null || Date.now() > deadline) {
+                throw new Error(`vite preview didn't serve the app: ${stderr.trim().slice(-500)}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+    }
+    finally {
+        try {
+            process.kill(-preview.pid, "SIGTERM");
+        }
+        catch { }
+    }
+}
+/** Describes a built Start app from its `dist/server`: a Workers build in workerd, a Node build in-process. */
+async function describeBuiltApp(appDir) {
+    const serverDir = node_path_1.default.join(appDir, "dist/server");
+    if ((0, node_fs_1.existsSync)(node_path_1.default.join(serverDir, "wrangler.json")))
+        return describeInWorkerd(appDir);
+    const { default: server } = await Promise.resolve(`${(0, node_url_1.pathToFileURL)(node_path_1.default.join(serverDir, "server.js")).href}`).then(s => __importStar(require(s)));
+    return (await server.fetch(new Request("http://describe.local/", { headers: DESCRIBE_HEADERS }))).json();
+}
+async function runDescribe() {
+    const appDir = node_path_1.default.resolve(process.argv[3] ?? ".");
+    process.stdout.write(`${JSON.stringify(await describeBuiltApp(appDir), null, 2)}\n`);
+}

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

@@ -0,0 +1,20 @@
+import type { SourceDir } from "../sourceRoots.js";
+export declare const START_SERVER_ENTRY = ".zite/server.ts";
+export declare const START_INSTANCE_ENTRY = ".zite/start.ts";
+export type StartTarget = "cloudflare" | "node";
+/**
+ * The server entry every Start app builds with. Platform-owned: regenerated,
+ * never edited. On Workers it's an entrypoint the host can also call over RPC.
+ */
+export declare const renderStartServerEntry: (target?: StartTarget) => string;
+/** The start instance: the platform's middleware, then the app's own `src/start.ts` when it has one. */
+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

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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";
+exports.START_INSTANCE_ENTRY = ".zite/start.ts";
+const APP_START_FILES = ["src/start.ts", "src/start.tsx"];
+/**
+ * The server entry every Start app builds with. Platform-owned: regenerated,
+ * never edited. On Workers it's an entrypoint the host can also call over RPC.
+ */
+const renderStartServerEntry = (target = "cloudflare") => target === "cloudflare"
+    ? `// Generated by zitejs for TanStack Start apps. The platform owns this file.
+import handler from '@tanstack/react-start/server-entry';
+import { createZiteWorker } from 'zitejs/start/worker';
+import { getRouter } from '../src/router';
+
+export default createZiteWorker({ handler, getRouter });
+`
+    : `// Generated by zitejs for TanStack Start apps. The platform owns this file.
+import handler, { createServerEntry } from '@tanstack/react-start/server-entry';
+import { createZiteFetch } from 'zitejs/start/server';
+import { getRouter } from '../src/router';
+
+export default createServerEntry({ fetch: createZiteFetch({ handler, getRouter }) });
+`;
+exports.renderStartServerEntry = renderStartServerEntry;
+/** The start instance: the platform's middleware, then the app's own `src/start.ts` when it has one. */
+const renderStartInstance = (hasAppStart) => hasAppStart
+    ? `// Generated by zitejs for TanStack Start apps. The platform owns this file.
+import { createZiteStart } from 'zitejs/start/instance';
+import { startInstance as app } from '../src/start';
+
+export const startInstance = createZiteStart(app);
+`
+    : `// Generated by zitejs for TanStack Start apps. The platform owns this file.
+import { createZiteStart } from 'zitejs/start/instance';
+
+export const startInstance = createZiteStart();
+`;
+exports.renderStartInstance = renderStartInstance;
+const hasAppStart = (appDir) => APP_START_FILES.some((file) => (0, node_fs_1.existsSync)((0, node_path_1.join)(appDir, file)));
+exports.hasAppStart = hasAppStart;
+/** Writes `file` under `appDir` when its content differs. Returns whether it wrote. */
+const writeIfChanged = (appDir, file, content) => {
+    const target = (0, node_path_1.join)(appDir, file);
+    if ((0, node_fs_1.existsSync)(target) && (0, node_fs_1.readFileSync)(target, "utf-8") === content)
+        return false;
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
+    (0, node_fs_1.writeFileSync)(target, content);
+    return true;
+};
+exports.writeIfChanged = writeIfChanged;
+const isStartAppDir = (appPath) => {
+    try {
+        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;
+    const entries = [
+        [exports.START_SERVER_ENTRY, (0, exports.renderStartServerEntry)()],
+        [exports.START_INSTANCE_ENTRY, (0, exports.renderStartInstance)((0, exports.hasAppStart)(app.path))],
+    ];
+    for (const [file, content] of entries) {
+        if ((0, exports.writeIfChanged)(app.path, file, content))
+            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/integrations/rules.d.ts

@@ -38,12 +38,14 @@ declare const FIELDS_BY_TYPE: {
     jira: readonly string[];
     typeform: readonly string[];
     apollo: readonly string[];
+    clay: readonly string[];
     attio: readonly string[];
     granola: readonly string[];
     clickup: readonly string[];
     dropbox: readonly string[];
     amazonS3: readonly string[];
     snowflake: readonly string[];
+    databricks: readonly string[];
     smartsuite: readonly string[];
 };
 /** A service type `integrations.get` serves: one used through its npm package with a token. */

package/dist/esm/integrations/rules.js

@@ -44,6 +44,7 @@ const FIELDS_BY_TYPE = {
     jira: extras("cloudId", "siteUrl"),
     typeform: extras(),
     apollo: extras(),
+    clay: extras(),
     attio: extras(),
     granola: extras(),
     clickup: extras(),
@@ -54,6 +55,9 @@ const FIELDS_BY_TYPE = {
     // The SQL API lives on each account's own host, and the token is pinned to
     // one role; the warehouse is optional and falls back to the user's default.
     snowflake: extras("accountUrl", "role", "warehouse"),
+    // A statement is addressed by workspace host and SQL warehouse, and the token
+    // derives neither.
+    databricks: extras("host", "warehouseId"),
     // Every request names the workspace in an Account-Id header beside the key.
     smartsuite: extras("workspaceId"),
 };

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

@@ -0,0 +1,64 @@
+import type { ZiteTrigger } from "../backend/index.js";
+import type { LoadedWorkflow } from "./workflowRun.js";
+import type { WorkflowConfig } from "./workflow.js";
+export type Access = {
+    kind: "signedIn" | "anyone" | "webhook" | "none";
+    roles: string[];
+    paused?: true;
+};
+export type DescribedFunction = {
+    id: string;
+    name?: string;
+    file?: string;
+    method?: string;
+    /** From the factory's `description` option; display-only. */
+    description?: string;
+    access: Access;
+    input?: unknown;
+    problems: string[];
+};
+export type DescribedRoute = {
+    path: string;
+    methods: Record<string, Access>;
+    problems: string[];
+};
+export type DescribedWorkflow = {
+    id: string;
+    file: string;
+    description?: string;
+    schedule?: WorkflowConfig["schedule"];
+    /** As declared, without a provider trigger's `subscribe` and `unsubscribe`. */
+    trigger?: ZiteTrigger;
+    /** A provider trigger's: whether it can be taken down, and a hash of both functions' code, so publish registers it again when they change. */
+    registration?: {
+        unsubscribe: boolean;
+        hash: string;
+    };
+    problems: string[];
+};
+export type Description = {
+    functions: DescribedFunction[];
+    routes: DescribedRoute[];
+    workflows: DescribedWorkflow[];
+};
+export declare function describeFunction(id: string, request: Request): Promise<DescribedFunction>;
+type RouteLike = {
+    fullPath: string;
+    parentRoute?: RouteLike;
+    options?: {
+        server?: {
+            middleware?: unknown[];
+            handlers?: unknown;
+        };
+    };
+};
+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

@@ -0,0 +1,176 @@
+// Describes a built app by loading it, not by reading its source: each server
+// function's real middleware chain, each server route's, and input schemas.
+import { createMiddleware, flattenMiddlewares } from "@tanstack/react-start";
+import { createSsrRpc } from "@tanstack/react-start/ssr-rpc";
+import { runWithStartContext } from "@tanstack/start-storage-context";
+import { z } from "zod";
+import { ziteMiddlewareKind } from "./index.js";
+const accessOf = (chain, problems) => {
+    const kinds = chain.map(ziteMiddlewareKind).filter((k) => !!k);
+    const roles = kinds.flatMap((k) => (k.kind === "role" ? [k.role] : []));
+    const base = [...new Set(kinds.flatMap((k) => (k.kind === "signedIn" || k.kind === "anyone" || k.kind === "webhook" ? [k.kind] : [])))];
+    if (base.length === 0) {
+        problems.push("access-missing: no signedIn, anyone or webhook middleware in its chain");
+        return { kind: "none", roles };
+    }
+    if (base.length > 1)
+        problems.push(`access-conflict: ${base.join(" + ")}`);
+    const kind = base.includes("webhook") ? "webhook" : base.includes("signedIn") ? "signedIn" : "anyone";
+    const paused = kinds.some((k) => k.kind === "webhook" && k.paused === true);
+    return paused ? { kind, roles, paused } : { kind, roles };
+};
+const jsonSchemaOf = (validator) => {
+    if (validator && typeof validator === "object" && "_zod" in validator) {
+        try {
+            return z.toJSONSchema(validator);
+        }
+        catch {
+            return { unrepresentable: true };
+        }
+    }
+    return validator ? { opaque: true } : undefined;
+};
+// Describe walks functions one at a time, so one probe slot is enough.
+let probe = null;
+// The only global function middleware while describing: it records what it was
+// handed and ends the call, so no app middleware or handler runs.
+const describeProbe = createMiddleware({ type: "function" }).server(({ serverFnMeta, method }) => {
+    if (probe)
+        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 = [];
+    probe = { reached: false };
+    // Before running a chain, TanStack asks this set about every middleware in it.
+    // Recording the questions gives the exact chain it would have run.
+    const executedRequestMiddlewares = {
+        has: (middleware) => {
+            seen.push(middleware);
+            return false;
+        },
+    };
+    const startContext = {
+        request,
+        startOptions: { functionMiddleware: [describeProbe] },
+        executedRequestMiddlewares,
+        contextAfterGlobalMiddlewares: {},
+        handlerType: "serverFn",
+        getRouter: () => {
+            throw new Error("describe has no router");
+        },
+    };
+    try {
+        await runWithStartContext(startContext, () => createSsrRpc(id)({ data: undefined, context: {} }));
+    }
+    catch (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;
+    // Fails closed: if TanStack stops asking, or stops running globals first, every
+    // function reports a problem and the build stops.
+    if (!state.reached || seen[0] !== describeProbe)
+        problems.push("probe-not-first: chain could not be read");
+    const chain = seen.filter((m) => m !== describeProbe);
+    if (!chain.some((m) => ziteMiddlewareKind(m)?.kind === "factory")) {
+        problems.push("raw-server-fn: define it with signedInFn or publicFn from zitejs/start");
+    }
+    // TanStack keeps the validator under `inputValidator` up to 1.168 and `validator` from 1.169 (Start 1.0).
+    const handlerStep = chain.at(-1);
+    return {
+        id,
+        name: state.meta?.name,
+        file: state.meta?.filename,
+        method: state.method,
+        access: accessOf(chain, problems),
+        input: jsonSchemaOf(handlerStep?.options?.validator ?? handlerStep?.options?.inputValidator),
+        problems,
+    };
+}
+export function describeRoutes(routesById) {
+    const out = [];
+    for (const route of Object.values(routesById)) {
+        const server = route.options?.server;
+        if (!server?.handlers)
+            continue;
+        const problems = [];
+        const ancestry = [];
+        for (let r = route; r; r = r.parentRoute)
+            ancestry.unshift(r);
+        const routeMiddleware = ancestry.flatMap((r) => r.options?.server?.middleware ?? []);
+        const handlers = (typeof server.handlers === "function"
+            ? server.handlers({ createHandlers: (d) => d })
+            : server.handlers);
+        const methods = {};
+        for (const [method, handler] of Object.entries(handlers)) {
+            const own = typeof handler === "function" ? [] : (handler.middleware ?? []);
+            const chain = flattenMiddlewares([...routeMiddleware, ...own]);
+            const methodProblems = [];
+            methods[method] = accessOf(chain, methodProblems);
+            problems.push(...methodProblems.map((p) => `${method}: ${p}`));
+        }
+        out.push({ path: route.fullPath, methods, problems });
+    }
+    return out;
+}
+// cyrb53: enough to tell when the code changed, which is all publish asks.
+const sourceHash = (text) => {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(16).padStart(14, "0");
+};
+// 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;
+        if (schedule)
+            return { id, file, description, schedule, problems };
+        if (!trigger || trigger.every !== undefined || trigger.events !== undefined) {
+            return { id, file, description, trigger, problems };
+        }
+        const { subscribe, unsubscribe, ...declared } = trigger;
+        if (typeof subscribe !== "function") {
+            problems.push("workflow-trigger-unregistered: a provider trigger needs `subscribe` to register it with the provider");
+            return { id, file, description, trigger: declared, problems };
+        }
+        const registration = {
+            unsubscribe: typeof unsubscribe === "function",
+            hash: sourceHash(`${String(subscribe)}\n${typeof unsubscribe === "function" ? String(unsubscribe) : ""}`),
+        };
+        return { id, file, description, trigger: declared, registration, problems };
+    });
+}
+export async function describeApp(opts) {
+    const functions = [];
+    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), workflows: describeWorkflows(opts.workflows ?? []) };
+}

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

@@ -0,0 +1,3 @@
+/** Describes a built Start app from its `dist/server`: a Workers build in workerd, a Node build in-process. */
+export declare function describeBuiltApp(appDir: string): Promise<unknown>;
+export declare function runDescribe(): Promise<void>;

package/dist/esm/start/describeBuilt.js

@@ -0,0 +1,66 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createServer } from "node:net";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+// Only the host can set x-zite-* in production: the front strips them from public traffic.
+const DESCRIBE_HEADERS = { "x-zite-invoke": "describe" };
+// Not "localhost": it can resolve to ::1 for vite's listen and to 127.0.0.1 for fetch.
+const HOST = "127.0.0.1";
+const freePort = () => new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, HOST, () => {
+        const { port } = server.address();
+        server.close(() => resolve(port));
+    });
+});
+// A Workers build runs where it will run: workerd, through the app's own
+// `vite preview`, so it uses the same Cloudflare plugin and config as the build.
+async function describeInWorkerd(appDir) {
+    const port = await freePort();
+    // Its own process group, so stopping it also stops vite and workerd under npx.
+    const preview = spawn("npx", ["--no-install", "vite", "preview", "--host", HOST, "--port", String(port), "--strictPort"], {
+        cwd: appDir,
+        stdio: ["ignore", "ignore", "pipe"],
+        detached: true,
+    });
+    let stderr = "";
+    preview.stderr.on("data", (chunk) => (stderr += chunk));
+    try {
+        const deadline = Date.now() + 60_000;
+        while (true) {
+            try {
+                const response = await fetch(`http://${HOST}:${port}/`, { headers: DESCRIBE_HEADERS });
+                // Right after start, preview can answer before the Worker does; only the
+                // app's own describe answer is JSON.
+                if (response.ok && response.headers.get("content-type")?.includes("application/json")) {
+                    return await response.json();
+                }
+            }
+            catch { }
+            if (preview.exitCode !== null || Date.now() > deadline) {
+                throw new Error(`vite preview didn't serve the app: ${stderr.trim().slice(-500)}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+    }
+    finally {
+        try {
+            process.kill(-preview.pid, "SIGTERM");
+        }
+        catch { }
+    }
+}
+/** Describes a built Start app from its `dist/server`: a Workers build in workerd, a Node build in-process. */
+export async function describeBuiltApp(appDir) {
+    const serverDir = path.join(appDir, "dist/server");
+    if (existsSync(path.join(serverDir, "wrangler.json")))
+        return describeInWorkerd(appDir);
+    const { default: server } = await import(pathToFileURL(path.join(serverDir, "server.js")).href);
+    return (await server.fetch(new Request("http://describe.local/", { headers: DESCRIBE_HEADERS }))).json();
+}
+export async function runDescribe() {
+    const appDir = path.resolve(process.argv[3] ?? ".");
+    process.stdout.write(`${JSON.stringify(await describeBuiltApp(appDir), null, 2)}\n`);
+}

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>;