zitejs 0.9.136 → 0.9.138

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/backend/index.d.ts

@@ -216,6 +216,14 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
     validatesInput?: boolean;
     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 when a
+         * failed run is resumed, completed steps return their saved results
+         * instead of re-running their side effects. Names must be unique within
+         * a run, and results must be plain JSON data under 256KB.
+         */
+        step: ZiteStep;
         context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;
     } & (TStream extends true ? {
         stream: ZiteStreamInterface;
@@ -223,6 +231,17 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
         trigger?: ZiteTriggerContext<TTrigger>;
     } : {})) => Promise<TOutput> | TOutput;
 }
+/**
+ * Durable steps, provided by the platform inside `execute`. Wrap each unit of
+ * work with side effects — a provider call, a message send, a batch write —
+ * so a retry of a failed run resumes at the failure instead of redoing
+ * completed work. Steps run at least once — a crash between the side effect
+ * and the save re-runs the step — so make a step idempotent where repeating
+ * it would matter, and give a step inside a loop the item's id in its name.
+ */
+export interface ZiteStep {
+    run<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+}
 /**
  * Create an endpoint definition, parsing `input` against `inputSchema` before
  * `execute` runs. Nothing downstream parses it — the worker calls `execute` on

package/dist/cjs/backend/index.test.js

@@ -5,6 +5,10 @@ const zod_1 = require("zod");
 const index_js_1 = require("./index.js");
 const index_js_2 = require("../runtime/index.js");
 const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
+// Direct execute() calls need the step surface the runtime always provides.
+const stepStub = {
+    run: async (_name, fn) => await fn(),
+};
 (0, vitest_1.afterEach)(() => {
     vitest_1.vi.unstubAllGlobals();
 });
@@ -15,7 +19,11 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             inputSchema: zod_1.z.object({ token: zod_1.z.string().min(10) }),
             execute,
         });
-        await (0, vitest_1.expect)(endpoint.execute({ input: {}, context: requestContext })).rejects.toBeInstanceOf(index_js_1.ZiteError);
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: {},
+            context: requestContext,
+            step: stepStub,
+        })).rejects.toBeInstanceOf(index_js_1.ZiteError);
         (0, vitest_1.expect)(execute).not.toHaveBeenCalled();
     });
     (0, vitest_1.it)("surfaces the failure as BAD_REQUEST and names the offending field", async () => {
@@ -23,7 +31,11 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             inputSchema: zod_1.z.object({ token: zod_1.z.string().min(10) }),
             execute: async () => "unreachable",
         });
-        await (0, vitest_1.expect)(endpoint.execute({ input: {}, context: requestContext })).rejects.toMatchObject({
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: {},
+            context: requestContext,
+            step: stepStub,
+        })).rejects.toMatchObject({
             code: "BAD_REQUEST",
             message: vitest_1.expect.stringContaining("token"),
         });
@@ -35,6 +47,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             execute,
         });
         await (0, vitest_1.expect)(endpoint.execute({
+            step: stepStub,
             input: undefined,
             context: requestContext,
         })).rejects.toMatchObject({ code: "BAD_REQUEST" });
@@ -49,6 +62,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             execute: async ({ input }) => input,
         });
         await (0, vitest_1.expect)(endpoint.execute({
+            step: stepStub,
             input: { token: "abc" },
             context: requestContext,
         })).resolves.toEqual({ token: "abc", limit: 10 });
@@ -62,6 +76,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             execute: async ({ input }) => input.action,
         });
         await (0, vitest_1.expect)(endpoint.execute({
+            step: stepStub,
             input: { token: "b69779ae-eeea", action: "load" },
             context: requestContext,
         })).resolves.toBe("load");
@@ -80,6 +95,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             execute: async ({ input }) => input,
         });
         await (0, vitest_1.expect)(endpoint.execute({
+            step: stepStub,
             input: { anything: true },
             context: requestContext,
         })).resolves.toEqual({ anything: true });
@@ -92,6 +108,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             execute: async (params) => params.stream === stream,
         });
         await (0, vitest_1.expect)(endpoint.execute({
+            step: stepStub,
             input: { prompt: "hi" },
             context: requestContext,
             stream,
@@ -110,6 +127,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             execute: async ({ input }) => input,
         });
         await (0, vitest_1.expect)(endpoint.execute({
+            step: stepStub,
             input: { __cron: { scheduleId: "s1" } },
             context: { user: null },
         })).resolves.toEqual({ __cron: { scheduleId: "s1" } });
@@ -124,14 +142,22 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             },
             execute: async ({ input }) => input ?? "(no input)",
         });
-        await (0, vitest_1.expect)(endpoint.execute({ input: undefined, context: { user: null } })).resolves.toBe("(no input)");
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: undefined,
+            context: { user: null },
+            step: stepStub,
+        })).resolves.toBe("(no input)");
     });
     (0, vitest_1.it)("still validates an ordinary endpoint called with no input", async () => {
         const endpoint = (0, index_js_1.createEndpoint)({
             inputSchema: zod_1.z.string(),
             execute: async ({ input }) => input,
         });
-        await (0, vitest_1.expect)(endpoint.execute({ input: undefined, context: requestContext })).rejects.toMatchObject({ code: "BAD_REQUEST" });
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: undefined,
+            context: requestContext,
+            step: stepStub,
+        })).rejects.toMatchObject({ code: "BAD_REQUEST" });
     });
     (0, vitest_1.it)("hands a poll a typed trigger and skips the input schema for it", async () => {
         const handled = [];
@@ -150,6 +176,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
         });
         const seen = new Set(["a"]);
         await (0, vitest_1.expect)(endpoint.execute({
+            step: stepStub,
             input: {},
             context: { user: null },
             trigger: {
@@ -218,6 +245,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             }),
         });
         await (0, vitest_1.expect)(endpoint.execute({
+            step: stepStub,
             input: { kind: "sync" },
             context: { user: null },
             trigger: {
@@ -228,7 +256,11 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
                 headers: {},
                 deliveryId: "chan:2",
             },
-        })).resolves.toEqual({ body: { kind: "sync" }, cursor: "sync1", delivery: "chan:2" });
+        })).resolves.toEqual({
+            body: { kind: "sync" },
+            cursor: "sync1",
+            delivery: "chan:2",
+        });
     });
     (0, vitest_1.it)("refuses events on a trigger that also polls", () => {
         (0, index_js_1.createEndpoint)({
@@ -245,6 +277,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
             execute: async ({ input }) => input,
         });
         await (0, vitest_1.expect)(endpoint.execute({
+            step: stepStub,
             input: { __webhook: { headers: {} }, id: 7 },
             context: { user: null },
         })).resolves.toEqual({ __webhook: { headers: {} }, id: 7 });
@@ -283,6 +316,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
         await (0, vitest_1.expect)(buildEndpoint((nom) => matched.push(nom)).execute({
             input: {},
             context: requestContext,
+            step: stepStub,
         })).rejects.toMatchObject({ code: "BAD_REQUEST" });
         (0, vitest_1.expect)(dispatched).toEqual([]);
         (0, vitest_1.expect)(matched).toEqual([]);

package/dist/cjs/dev/index.js

@@ -178,6 +178,13 @@ async function runGenerate() {
     // The backend writes the schema/lock files to the sandbox before
     // calling this. Use `zitejs sync` separately for local dev (fetches
     // metadata from the backend API).
+    // Everything below reads relative paths, so run from an app dir this would
+    // find no source roots, write nothing, and still print "Done!".
+    const workspaceRoot = (0, sourceRoots_js_1.findWorkspaceRoot)();
+    if (workspaceRoot && workspaceRoot !== (0, path_1.resolve)(".")) {
+        console.log(`Running from the workspace root: ${workspaceRoot}`);
+        process.chdir(workspaceRoot);
+    }
     // 1. Generate root .zite/db.ts from zite.schema.json
     try {
         if ((0, fs_2.existsSync)("zite.schema.json")) {

package/dist/cjs/sourceRoots.d.ts

@@ -15,6 +15,13 @@ export interface SourceDir {
 }
 /** Every source dir under every root, in root order then name order. */
 export declare function listSourceDirs(cwd?: string): SourceDir[];
+/**
+ * The workspace root at or above `cwd`: the nearest directory holding a
+ * `zite.config.json` next to an `apps/` or `automations/` dir. An app dir has
+ * a config of its own but no source root under it, so it never matches.
+ * Undefined outside a monorepo (a single-app project runs where it is).
+ */
+export declare function findWorkspaceRoot(cwd?: string): string | undefined;
 /** The source dir with this bare name, under whichever root holds it. */
 export declare function findSourceDir(name: string, cwd?: string): SourceDir | undefined;
 /**

package/dist/cjs/sourceRoots.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AUTOMATION_ENTRY_FILE = exports.AUTOMATION_ENDPOINT_NAME = exports.SOURCE_ROOTS = void 0;
 exports.listSourceDirs = listSourceDirs;
+exports.findWorkspaceRoot = findWorkspaceRoot;
 exports.findSourceDir = findSourceDir;
 exports.sourceRootOf = sourceRootOf;
 exports.endpointEntryFile = endpointEntryFile;
@@ -30,6 +31,22 @@ function listSourceDirs(cwd = ".") {
     }
     return dirs;
 }
+/**
+ * The workspace root at or above `cwd`: the nearest directory holding a
+ * `zite.config.json` next to an `apps/` or `automations/` dir. An app dir has
+ * a config of its own but no source root under it, so it never matches.
+ * Undefined outside a monorepo (a single-app project runs where it is).
+ */
+function findWorkspaceRoot(cwd = ".") {
+    for (let dir = (0, path_1.resolve)(cwd);; dir = (0, path_1.dirname)(dir)) {
+        if ((0, fs_1.existsSync)((0, path_1.join)(dir, "zite.config.json")) &&
+            exports.SOURCE_ROOTS.some((root) => (0, fs_1.existsSync)((0, path_1.join)(dir, root)))) {
+            return dir;
+        }
+        if ((0, path_1.dirname)(dir) === dir)
+            return undefined;
+    }
+}
 /** The source dir with this bare name, under whichever root holds it. */
 function findSourceDir(name, cwd = ".") {
     return listSourceDirs(cwd).find((d) => d.dir === name);

package/dist/cjs/sourceRoots.test.js

@@ -27,4 +27,19 @@ const sourceRoots_js_1 = require("./sourceRoots.js");
         (0, vitest_1.expect)((0, sourceRoots_js_1.listEndpointNames)("automations", (0, path_1.join)(repo, "automations/digest"))).toEqual(["index"]);
         (0, vitest_1.expect)((0, sourceRoots_js_1.listEndpointNames)("automations", (0, path_1.join)(repo, "automations/empty"))).toEqual([]);
     });
+    (0, vitest_1.it)("finds the workspace root from inside an app dir, and not from an app's own config", () => {
+        const repo = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), "zitejs-root-"));
+        (0, fs_1.writeFileSync)((0, path_1.join)(repo, "zite.config.json"), "{}");
+        (0, fs_1.mkdirSync)((0, path_1.join)(repo, "apps/crm/src/api"), { recursive: true });
+        (0, fs_1.writeFileSync)((0, path_1.join)(repo, "apps/crm/zite.config.json"), "{}");
+        (0, vitest_1.expect)((0, sourceRoots_js_1.findWorkspaceRoot)(repo)).toBe(repo);
+        (0, vitest_1.expect)((0, sourceRoots_js_1.findWorkspaceRoot)((0, path_1.join)(repo, "apps/crm"))).toBe(repo);
+        (0, vitest_1.expect)((0, sourceRoots_js_1.findWorkspaceRoot)((0, path_1.join)(repo, "apps/crm/src/api"))).toBe(repo);
+    });
+    (0, vitest_1.it)("has no root for a single-app project", () => {
+        const app = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), "zitejs-single-"));
+        (0, fs_1.writeFileSync)((0, path_1.join)(app, "zite.config.json"), "{}");
+        (0, fs_1.mkdirSync)((0, path_1.join)(app, "src/api"), { recursive: true });
+        (0, vitest_1.expect)((0, sourceRoots_js_1.findWorkspaceRoot)(app)).toBeUndefined();
+    });
 });

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/backend/index.d.ts

@@ -216,6 +216,14 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
     validatesInput?: boolean;
     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 when a
+         * failed run is resumed, completed steps return their saved results
+         * instead of re-running their side effects. Names must be unique within
+         * a run, and results must be plain JSON data under 256KB.
+         */
+        step: ZiteStep;
         context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;
     } & (TStream extends true ? {
         stream: ZiteStreamInterface;
@@ -223,6 +231,17 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
         trigger?: ZiteTriggerContext<TTrigger>;
     } : {})) => Promise<TOutput> | TOutput;
 }
+/**
+ * Durable steps, provided by the platform inside `execute`. Wrap each unit of
+ * work with side effects — a provider call, a message send, a batch write —
+ * so a retry of a failed run resumes at the failure instead of redoing
+ * completed work. Steps run at least once — a crash between the side effect
+ * and the save re-runs the step — so make a step idempotent where repeating
+ * it would matter, and give a step inside a loop the item's id in its name.
+ */
+export interface ZiteStep {
+    run<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+}
 /**
  * Create an endpoint definition, parsing `input` against `inputSchema` before
  * `execute` runs. Nothing downstream parses it — the worker calls `execute` on

package/dist/esm/backend/index.test.js

@@ -3,6 +3,10 @@ import { z } from "zod";
 import { createEndpoint, ZiteError, } from "./index.js";
 import { createTableClient } from "../runtime/index.js";
 const requestContext = { user: { id: "u1", email: "a@b.c", roles: [] } };
+// Direct execute() calls need the step surface the runtime always provides.
+const stepStub = {
+    run: async (_name, fn) => await fn(),
+};
 afterEach(() => {
     vi.unstubAllGlobals();
 });
@@ -13,7 +17,11 @@ describe("createEndpoint input validation", () => {
             inputSchema: z.object({ token: z.string().min(10) }),
             execute,
         });
-        await expect(endpoint.execute({ input: {}, context: requestContext })).rejects.toBeInstanceOf(ZiteError);
+        await expect(endpoint.execute({
+            input: {},
+            context: requestContext,
+            step: stepStub,
+        })).rejects.toBeInstanceOf(ZiteError);
         expect(execute).not.toHaveBeenCalled();
     });
     it("surfaces the failure as BAD_REQUEST and names the offending field", async () => {
@@ -21,7 +29,11 @@ describe("createEndpoint input validation", () => {
             inputSchema: z.object({ token: z.string().min(10) }),
             execute: async () => "unreachable",
         });
-        await expect(endpoint.execute({ input: {}, context: requestContext })).rejects.toMatchObject({
+        await expect(endpoint.execute({
+            input: {},
+            context: requestContext,
+            step: stepStub,
+        })).rejects.toMatchObject({
             code: "BAD_REQUEST",
             message: expect.stringContaining("token"),
         });
@@ -33,6 +45,7 @@ describe("createEndpoint input validation", () => {
             execute,
         });
         await expect(endpoint.execute({
+            step: stepStub,
             input: undefined,
             context: requestContext,
         })).rejects.toMatchObject({ code: "BAD_REQUEST" });
@@ -47,6 +60,7 @@ describe("createEndpoint input validation", () => {
             execute: async ({ input }) => input,
         });
         await expect(endpoint.execute({
+            step: stepStub,
             input: { token: "abc" },
             context: requestContext,
         })).resolves.toEqual({ token: "abc", limit: 10 });
@@ -60,6 +74,7 @@ describe("createEndpoint input validation", () => {
             execute: async ({ input }) => input.action,
         });
         await expect(endpoint.execute({
+            step: stepStub,
             input: { token: "b69779ae-eeea", action: "load" },
             context: requestContext,
         })).resolves.toBe("load");
@@ -78,6 +93,7 @@ describe("createEndpoint input validation", () => {
             execute: async ({ input }) => input,
         });
         await expect(endpoint.execute({
+            step: stepStub,
             input: { anything: true },
             context: requestContext,
         })).resolves.toEqual({ anything: true });
@@ -90,6 +106,7 @@ describe("createEndpoint input validation", () => {
             execute: async (params) => params.stream === stream,
         });
         await expect(endpoint.execute({
+            step: stepStub,
             input: { prompt: "hi" },
             context: requestContext,
             stream,
@@ -108,6 +125,7 @@ describe("platform-triggered runs", () => {
             execute: async ({ input }) => input,
         });
         await expect(endpoint.execute({
+            step: stepStub,
             input: { __cron: { scheduleId: "s1" } },
             context: { user: null },
         })).resolves.toEqual({ __cron: { scheduleId: "s1" } });
@@ -122,14 +140,22 @@ describe("platform-triggered runs", () => {
             },
             execute: async ({ input }) => input ?? "(no input)",
         });
-        await expect(endpoint.execute({ input: undefined, context: { user: null } })).resolves.toBe("(no input)");
+        await expect(endpoint.execute({
+            input: undefined,
+            context: { user: null },
+            step: stepStub,
+        })).resolves.toBe("(no input)");
     });
     it("still validates an ordinary endpoint called with no input", async () => {
         const endpoint = createEndpoint({
             inputSchema: z.string(),
             execute: async ({ input }) => input,
         });
-        await expect(endpoint.execute({ input: undefined, context: requestContext })).rejects.toMatchObject({ code: "BAD_REQUEST" });
+        await expect(endpoint.execute({
+            input: undefined,
+            context: requestContext,
+            step: stepStub,
+        })).rejects.toMatchObject({ code: "BAD_REQUEST" });
     });
     it("hands a poll a typed trigger and skips the input schema for it", async () => {
         const handled = [];
@@ -148,6 +174,7 @@ describe("platform-triggered runs", () => {
         });
         const seen = new Set(["a"]);
         await expect(endpoint.execute({
+            step: stepStub,
             input: {},
             context: { user: null },
             trigger: {
@@ -216,6 +243,7 @@ describe("platform-triggered runs", () => {
             }),
         });
         await expect(endpoint.execute({
+            step: stepStub,
             input: { kind: "sync" },
             context: { user: null },
             trigger: {
@@ -226,7 +254,11 @@ describe("platform-triggered runs", () => {
                 headers: {},
                 deliveryId: "chan:2",
             },
-        })).resolves.toEqual({ body: { kind: "sync" }, cursor: "sync1", delivery: "chan:2" });
+        })).resolves.toEqual({
+            body: { kind: "sync" },
+            cursor: "sync1",
+            delivery: "chan:2",
+        });
     });
     it("refuses events on a trigger that also polls", () => {
         createEndpoint({
@@ -243,6 +275,7 @@ describe("platform-triggered runs", () => {
             execute: async ({ input }) => input,
         });
         await expect(endpoint.execute({
+            step: stepStub,
             input: { __webhook: { headers: {} }, id: 7 },
             context: { user: null },
         })).resolves.toEqual({ __webhook: { headers: {} }, id: 7 });
@@ -281,6 +314,7 @@ describe("regression: token lookup on an endpoint called without a token", () =>
         await expect(buildEndpoint((nom) => matched.push(nom)).execute({
             input: {},
             context: requestContext,
+            step: stepStub,
         })).rejects.toMatchObject({ code: "BAD_REQUEST" });
         expect(dispatched).toEqual([]);
         expect(matched).toEqual([]);

package/dist/esm/dev/index.js

@@ -1,7 +1,7 @@
 import { watch } from "fs";
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, } from "fs";
 import { dirname, join, resolve } from "path";
-import { listSourceDirs } from "../sourceRoots.js";
+import { findWorkspaceRoot, listSourceDirs, } from "../sourceRoots.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";
@@ -173,6 +173,13 @@ export async function runGenerate() {
     // The backend writes the schema/lock files to the sandbox before
     // calling this. Use `zitejs sync` separately for local dev (fetches
     // metadata from the backend API).
+    // Everything below reads relative paths, so run from an app dir this would
+    // find no source roots, write nothing, and still print "Done!".
+    const workspaceRoot = findWorkspaceRoot();
+    if (workspaceRoot && workspaceRoot !== resolve(".")) {
+        console.log(`Running from the workspace root: ${workspaceRoot}`);
+        process.chdir(workspaceRoot);
+    }
     // 1. Generate root .zite/db.ts from zite.schema.json
     try {
         if (existsSync("zite.schema.json")) {

package/dist/esm/sourceRoots.d.ts

@@ -15,6 +15,13 @@ export interface SourceDir {
 }
 /** Every source dir under every root, in root order then name order. */
 export declare function listSourceDirs(cwd?: string): SourceDir[];
+/**
+ * The workspace root at or above `cwd`: the nearest directory holding a
+ * `zite.config.json` next to an `apps/` or `automations/` dir. An app dir has
+ * a config of its own but no source root under it, so it never matches.
+ * Undefined outside a monorepo (a single-app project runs where it is).
+ */
+export declare function findWorkspaceRoot(cwd?: string): string | undefined;
 /** The source dir with this bare name, under whichever root holds it. */
 export declare function findSourceDir(name: string, cwd?: string): SourceDir | undefined;
 /**

package/dist/esm/sourceRoots.js

@@ -22,6 +22,22 @@ export function listSourceDirs(cwd = ".") {
     }
     return dirs;
 }
+/**
+ * The workspace root at or above `cwd`: the nearest directory holding a
+ * `zite.config.json` next to an `apps/` or `automations/` dir. An app dir has
+ * a config of its own but no source root under it, so it never matches.
+ * Undefined outside a monorepo (a single-app project runs where it is).
+ */
+export function findWorkspaceRoot(cwd = ".") {
+    for (let dir = resolve(cwd);; dir = dirname(dir)) {
+        if (existsSync(join(dir, "zite.config.json")) &&
+            SOURCE_ROOTS.some((root) => existsSync(join(dir, root)))) {
+            return dir;
+        }
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+}
 /** The source dir with this bare name, under whichever root holds it. */
 export function findSourceDir(name, cwd = ".") {
     return listSourceDirs(cwd).find((d) => d.dir === name);

package/dist/esm/sourceRoots.test.js

@@ -2,7 +2,7 @@ import { mkdirSync, mkdtempSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { describe, expect, it } from "vitest";
-import { endpointEntryFile, listEndpointNames, sourceRootOf, } from "./sourceRoots.js";
+import { endpointEntryFile, findWorkspaceRoot, listEndpointNames, sourceRootOf, } from "./sourceRoots.js";
 describe("source roots", () => {
     it("reads the root from the source dir's parent", () => {
         expect(sourceRootOf("/repo/apps/crm")).toBe("apps");
@@ -25,4 +25,19 @@ describe("source roots", () => {
         expect(listEndpointNames("automations", join(repo, "automations/digest"))).toEqual(["index"]);
         expect(listEndpointNames("automations", join(repo, "automations/empty"))).toEqual([]);
     });
+    it("finds the workspace root from inside an app dir, and not from an app's own config", () => {
+        const repo = mkdtempSync(join(tmpdir(), "zitejs-root-"));
+        writeFileSync(join(repo, "zite.config.json"), "{}");
+        mkdirSync(join(repo, "apps/crm/src/api"), { recursive: true });
+        writeFileSync(join(repo, "apps/crm/zite.config.json"), "{}");
+        expect(findWorkspaceRoot(repo)).toBe(repo);
+        expect(findWorkspaceRoot(join(repo, "apps/crm"))).toBe(repo);
+        expect(findWorkspaceRoot(join(repo, "apps/crm/src/api"))).toBe(repo);
+    });
+    it("has no root for a single-app project", () => {
+        const app = mkdtempSync(join(tmpdir(), "zitejs-single-"));
+        writeFileSync(join(app, "zite.config.json"), "{}");
+        mkdirSync(join(app, "src/api"), { recursive: true });
+        expect(findWorkspaceRoot(app)).toBeUndefined();
+    });
 });

package/dist/esm/sync/lib.js

@@ -1217,10 +1217,10 @@ export 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';",
@@ -1316,6 +1316,8 @@ export 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/package.json

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