zitejs 0.9.137 → 0.10.0-start.0

package/README.md

@@ -23,10 +23,15 @@ const result = await zite.sql({
   query: 'SELECT "id", "email" FROM "ziteUsers"',
 });
 
-// Define API endpoints
+// Define API endpoints. step.run saves each result as it completes, so a
+// failed run resumed from run history skips the steps that already ran.
 import { createEndpoint, ZiteError } from 'zitejs/api';
 export default createEndpoint({
-  execute: async ({ input }) => { ... },
+  execute: async ({ input, step }) => {
+    const order = await step.run('load-order', () => loadOrder(input.id));
+    await step.run('charge', () => charge(order));
+    return { charged: true };
+  },
 });
 
 // Authentication

package/dist/cjs/cli.js

@@ -35,8 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 const dotenv_1 = require("dotenv");
-(0, dotenv_1.config)({ path: '.env.local' });
-(0, dotenv_1.config)({ path: '.env' });
+// Quiet: dotenv 17 prints tips to stdout, which commands like `describe` own.
+(0, dotenv_1.config)({ path: '.env.local', quiet: true });
+(0, dotenv_1.config)({ path: '.env', quiet: true });
 async function main() {
     const command = process.argv[2];
     switch (command) {
@@ -60,6 +61,11 @@ async function main() {
             await runCheck();
             break;
         }
+        case 'describe': {
+            const { runDescribe } = await Promise.resolve().then(() => __importStar(require('./start/describeBuilt.js')));
+            await runDescribe();
+            break;
+        }
         case 'bundle': {
             const { runBundle } = await Promise.resolve().then(() => __importStar(require('./bundle/index.js')));
             await runBundle();
@@ -68,7 +74,7 @@ async function main() {
         default:
             console.error(command
                 ? `Unknown command: ${command}`
-                : 'Usage: zitejs <sync|dev|generate|check|bundle>');
+                : 'Usage: zitejs <sync|dev|generate|check|bundle|describe>');
             console.error('');
             console.error('Commands:');
             console.error('  sync      Generate .zite/db.ts from database schema (single-app)');
@@ -76,6 +82,7 @@ async function main() {
             console.error('  generate  Regenerate every app and automation .zite/ (monorepo)');
             console.error('  check   Run tsc --noEmit (and vite build where there is one) for every app and automation');
             console.error('  bundle  Bundle endpoints (src/api/*.ts, or an automation\'s src/index.ts) for cloudflare-lambda');
+            console.error('  describe  Print what a built TanStack Start app declares: functions, routes, access');
             process.exit(1);
     }
 }

package/dist/cjs/dev/index.js

@@ -7,6 +7,7 @@ const fs_1 = require("fs");
 const fs_2 = require("fs");
 const path_1 = require("path");
 const sourceRoots_js_1 = require("../sourceRoots.js");
+const entries_js_1 = require("../start/entries.js");
 const index_js_1 = require("../sync/index.js");
 const lib_js_1 = require("../sync/lib.js");
 const rules_js_1 = require("../integrations/rules.js");
@@ -205,6 +206,7 @@ async function runGenerate() {
         regenerateAppTypedWrappers(app);
         regenerateAppAirtableSdk(app);
         regenerateAppIntegrationsIndex(app);
+        (0, entries_js_1.regenerateStartEntries)(app);
     }
     console.log("Done!");
 }
@@ -226,6 +228,7 @@ async function runDev() {
         regenerateAppApiTs(app);
         regenerateAppTypedWrappers(app);
         regenerateAppIntegrationsIndex(app);
+        (0, entries_js_1.regenerateStartEntries)(app);
     }
     // 3. Watch each dir's src/api/ for endpoint changes
     let watchingAny = false;

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,104 @@
+"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" };
+const freePort = () => new Promise((resolve, reject) => {
+    const server = (0, node_net_1.createServer)();
+    server.once("error", reject);
+    server.listen(0, () => {
+        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", "--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://localhost:${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,11 @@
+import type { SourceDir } from "../sourceRoots.js";
+export declare const START_SERVER_ENTRY = ".zite/server.ts";
+export declare const START_INSTANCE_ENTRY = ".zite/start.ts";
+/** The server entry every Start app builds with. Platform-owned: regenerated, never edited. */
+export declare const renderStartServerEntry: () => 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 function regenerateStartEntries(app: SourceDir): void;

package/dist/cjs/start/entries.js

@@ -0,0 +1,64 @@
+"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.regenerateStartEntries = regenerateStartEntries;
+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. */
+const renderStartServerEntry = () => `// 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 isStartApp = (app) => {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(app.path, "zite.config.json"), "utf-8"))?.runtime === "start";
+    }
+    catch {
+        return false;
+    }
+};
+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)}`);
+    }
+}

package/dist/cjs/sync/lib.js

@@ -1232,10 +1232,10 @@ function generateBackendWrapperTs(envVarNames = []) {
         "// Auto-generated type-narrowing wrapper. Do not edit manually.",
         "// Re-exports createEndpoint with context.user typed to the app User.",
         "",
-        "import type { ZiteRequestContext as _ZiteRequestContext, ZiteScheduledContext, ZiteErrorCode, ZiteSchedule, ZiteStreamInterface, ZiteTrigger, ZiteTriggerContext, ZiteWebhook } from 'zitejs/backend/base';",
+        "import type { ZiteRequestContext as _ZiteRequestContext, ZiteScheduledContext, ZiteErrorCode, ZiteSchedule, ZiteStep, ZiteStreamInterface, ZiteTrigger, ZiteTriggerContext, ZiteWebhook } from 'zitejs/backend/base';",
         "import type { User } from 'zitejs/auth';",
         "",
-        "export type { ZiteErrorCode, ZiteSchedule, ZiteScheduledContext, ZiteStreamInterface, ZiteTrigger, ZiteWebhook };",
+        "export type { ZiteErrorCode, ZiteSchedule, ZiteScheduledContext, ZiteStep, ZiteStreamInterface, ZiteTrigger, ZiteWebhook };",
         // A trigger's registration exports are typed against these, and they
         // only reach app code through this file.
         "export type { ZiteTriggerContext, ZiteTriggerDeliveryInfo, ZiteTriggerDeliveryRun, ZiteTriggerRun, ZiteTriggerSubscribe, ZiteTriggerSubscribeInput, ZiteTriggerSubscribeResult, ZiteTriggerUnsubscribe, ZiteTriggerUnsubscribeInput } from 'zitejs/backend/base';",
@@ -1331,6 +1331,8 @@ function generateBackendWrapperTs(envVarNames = []) {
         "  execute: (",
         "    params: {",
         "      input: TInput;",
+        "      /** Durable steps: step.run(name, fn) runs fn once per logical run — its result is saved before anything after it executes, and a resumed run replays completed steps from their saved results. Provided by the platform; never define a local stand-in. */",
+        "      step: ZiteStep;",
         "      context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;",
         // Mirrors the base module: a trigger's run gets `trigger`.
         "    } & (TStream extends true ? { stream: ZiteStreamInterface } : {}) & (TTrigger extends ZiteTrigger ? { trigger?: ZiteTriggerContext<TTrigger> } : {}),",

package/dist/esm/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { config } from 'dotenv';
-config({ path: '.env.local' });
-config({ path: '.env' });
+// Quiet: dotenv 17 prints tips to stdout, which commands like `describe` own.
+config({ path: '.env.local', quiet: true });
+config({ path: '.env', quiet: true });
 async function main() {
     const command = process.argv[2];
     switch (command) {
@@ -25,6 +26,11 @@ async function main() {
             await runCheck();
             break;
         }
+        case 'describe': {
+            const { runDescribe } = await import('./start/describeBuilt.js');
+            await runDescribe();
+            break;
+        }
         case 'bundle': {
             const { runBundle } = await import('./bundle/index.js');
             await runBundle();
@@ -33,7 +39,7 @@ async function main() {
         default:
             console.error(command
                 ? `Unknown command: ${command}`
-                : 'Usage: zitejs <sync|dev|generate|check|bundle>');
+                : 'Usage: zitejs <sync|dev|generate|check|bundle|describe>');
             console.error('');
             console.error('Commands:');
             console.error('  sync      Generate .zite/db.ts from database schema (single-app)');
@@ -41,6 +47,7 @@ async function main() {
             console.error('  generate  Regenerate every app and automation .zite/ (monorepo)');
             console.error('  check   Run tsc --noEmit (and vite build where there is one) for every app and automation');
             console.error('  bundle  Bundle endpoints (src/api/*.ts, or an automation\'s src/index.ts) for cloudflare-lambda');
+            console.error('  describe  Print what a built TanStack Start app declares: functions, routes, access');
             process.exit(1);
     }
 }

package/dist/esm/dev/index.js

@@ -2,6 +2,7 @@ import { watch } from "fs";
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, } from "fs";
 import { dirname, join, resolve } from "path";
 import { findWorkspaceRoot, listSourceDirs, } from "../sourceRoots.js";
+import { regenerateStartEntries } from "../start/entries.js";
 import { runSync } from "../sync/index.js";
 import { generateDbTs, generateApiTs, generateBackendWrapperTs, generateAirtableTs, findEmailIntegrationId, generateEmailSdk, generateIntegrationsIndex, } from "../sync/lib.js";
 import { gettableIntegrations, } from "../integrations/rules.js";
@@ -200,6 +201,7 @@ export async function runGenerate() {
         regenerateAppTypedWrappers(app);
         regenerateAppAirtableSdk(app);
         regenerateAppIntegrationsIndex(app);
+        regenerateStartEntries(app);
     }
     console.log("Done!");
 }
@@ -221,6 +223,7 @@ export async function runDev() {
         regenerateAppApiTs(app);
         regenerateAppTypedWrappers(app);
         regenerateAppIntegrationsIndex(app);
+        regenerateStartEntries(app);
     }
     // 3. Watch each dir's src/api/ for endpoint changes
     let watchingAny = false;

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

@@ -0,0 +1,40 @@
+export type Access = {
+    kind: "signedIn" | "anyone" | "webhook" | "none";
+    roles: string[];
+};
+export type DescribedFunction = {
+    id: string;
+    name?: string;
+    file?: string;
+    method?: string;
+    access: Access;
+    input?: unknown;
+    problems: string[];
+};
+export type DescribedRoute = {
+    path: string;
+    methods: Record<string, Access>;
+    problems: string[];
+};
+export type Description = {
+    functions: DescribedFunction[];
+    routes: DescribedRoute[];
+};
+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 describeApp(opts: {
+    fnIds: string[];
+    getRouter: () => unknown;
+    request: Request;
+}): Promise<Description>;
+export {};

package/dist/esm/start/describe.js

@@ -0,0 +1,122 @@
+// 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";
+    return { 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";
+});
+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) {
+        problems.push(`probe-failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    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");
+    }
+    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?.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;
+}
+export async function describeApp(opts) {
+    const functions = [];
+    for (const id of opts.fnIds)
+        functions.push(await describeFunction(id, opts.request));
+    const router = (await opts.getRouter());
+    return { functions, routes: describeRoutes(router.routesById) };
+}

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,64 @@
+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" };
+const freePort = () => new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, () => {
+        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", "--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://localhost:${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/entries.d.ts

@@ -0,0 +1,11 @@
+import type { SourceDir } from "../sourceRoots.js";
+export declare const START_SERVER_ENTRY = ".zite/server.ts";
+export declare const START_INSTANCE_ENTRY = ".zite/start.ts";
+/** The server entry every Start app builds with. Platform-owned: regenerated, never edited. */
+export declare const renderStartServerEntry: () => 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 function regenerateStartEntries(app: SourceDir): void;

package/dist/esm/start/entries.js

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } 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"];
+/** The server entry every Start app builds with. Platform-owned: regenerated, never edited. */
+export const renderStartServerEntry = () => `// 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 }) });
+`;
+/** The start instance: the platform's middleware, then the app's own `src/start.ts` when it has one. */
+export 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();
+`;
+export const hasAppStart = (appDir) => APP_START_FILES.some((file) => existsSync(join(appDir, file)));
+/** Writes `file` under `appDir` when its content differs. Returns whether it wrote. */
+export const writeIfChanged = (appDir, file, content) => {
+    const target = join(appDir, file);
+    if (existsSync(target) && readFileSync(target, "utf-8") === content)
+        return false;
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, content);
+    return true;
+};
+const isStartApp = (app) => {
+    try {
+        return JSON.parse(readFileSync(join(app.path, "zite.config.json"), "utf-8"))?.runtime === "start";
+    }
+    catch {
+        return false;
+    }
+};
+export function regenerateStartEntries(app) {
+    if (!isStartApp(app))
+        return;
+    const entries = [
+        [START_SERVER_ENTRY, renderStartServerEntry()],
+        [START_INSTANCE_ENTRY, renderStartInstance(hasAppStart(app.path))],
+    ];
+    for (const [file, content] of entries) {
+        if (writeIfChanged(app.path, file, content))
+            console.log(`Wrote ${join(app.path, file)}`);
+    }
+}