@tailorkit/app 0.1.0-beta.2 → 0.1.0-beta.20

package/LICENSE.md

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,184 @@
+# @tailorkit/app
+
+Apache-2.0 app SDK. The implementation lives here; `tailorkit/client` reexports the browser API and `tailorkit/server` reexports backend definitions. The package root also exports `defineServer`. Define SQLite tables, synchronous queries/mutations and async actions with Zod arguments. Drizzle and oRPC v2 run underneath; app code uses this package's APIs.
+
+```ts
+import { defineServer, table, text, tk } from "tailorkit/server";
+import { z } from "zod";
+
+const notes = table("notes", { id: text().primaryKey(), title: text().notNull() });
+const functions = {
+  list: tk.query.handler(({ db }) => db.select().from(notes).all()),
+  add: tk.mutation
+    .input(z.object({ title: z.string().min(1) }))
+    .handler(({ db, input }) =>
+      db.insert(notes).values({ id: crypto.randomUUID(), title: input.title }).returning().all(),
+    ),
+};
+export default defineServer(functions);
+```
+
+Use `tk.query`, `tk.mutation` and `tk.action` with `.handler(fn)`. Both `.input(schema)` and `.output(schema)` are optional and can be chained in either order. Without `.input()`, handler `input` is `undefined` and callers omit the input; supplying a value is rejected. Without `.output()`, return values are allowed and their types are inferred from the handler, including awaited action results. There is no default output schema. When supplied, `.output()` constrains handler returns in TypeScript and validates them at runtime; nonconforming results throw `Invalid function result`. Output transformations determine the types returned to clients and action callbacks. Builders are immutable. The original object-form `query`, `mutation` and `action` helpers remain supported.
+
+Chained handlers receive validated `input`, `db`, and verified `identity` (`userId`, `projectId`, `appId`, `installationId`, `deploymentId`, `expiresAt`). Queries expose selection builders; mutations additionally expose insert/update/delete. Use synchronous `.all()`, `.get()` and `.run()`. Async query/mutation handlers are rejected: writes, output validation and the accepted-write receipt commit in one synchronous transaction. `.output(schema)` validates the output before commit. Throw `AppError` for an intentional public error; unexpected errors are hidden.
+
+Schema exports include `table`, `text`, `integer`, `real`, `boolean` and common comparison/order operators. This is a small supported surface. Apps can import Drizzle for advanced configurations, but those features are not guaranteed to work with tracking or this driver.
+
+## Queries, mutations and actions
+
+| Type     | Database access                         | External calls | Automatic query reruns                      |
+| -------- | --------------------------------------- | -------------- | ------------------------------------------- |
+| Query    | Read only                               | Blocked        | When subscribed                             |
+| Mutation | Read/write in one atomic transaction    | Blocked        | Invalidates affected queries after commit   |
+| Action   | Through `ctx.queries` / `ctx.mutations` | Async HTTPS    | One-off calls; no subscription invalidation |
+
+Use `tk.action` for external API calls. Action handlers receive validated `input`, verified `identity`, an abort `signal`, and typed `ctx.queries.<name>(args)` / `ctx.mutations.<name>(args)` methods. They have no `db` handle. Actions can be synchronous or async; query/mutation handlers remain synchronous.
+
+Pass a shared query/mutation collection to `.functions(functions)`, and register that same collection under the same names in `defineServer`. The namespaces expose only the declared queries and mutations; their argument and result types are inferred from the definitions. No generated client references are needed on the server. Actions with no database calls can omit `.functions()`.
+
+To extend the example above, add this action and include it in the app:
+
+```ts
+const importNote = tk.action
+  .functions(functions)
+  .input(z.object({ url: z.url() }))
+  .handler(async (ctx) => {
+    await ctx.queries.list();
+    const response = await fetch(ctx.input.url, { signal: ctx.signal });
+    const data = z.object({ title: z.string() }).parse(await response.json());
+    return ctx.mutations.add({ title: data.title });
+  });
+export default defineServer({ ...functions, importNote });
+```
+
+Clients call `await client.action(api.importNote, { url })`. Actions are one-shot calls, never subscriptions, and are not automatically retried. Every query/mutation call executes separately; the action as a whole is not a transaction. An earlier mutation stays committed if later external work or result validation fails. Combine related database writes into one mutation when they must be atomic. External writes need the provider's idempotency mechanism before retrying an action. Mutation methods accept an optional second argument `{ requestId }`, for example `ctx.mutations.add({ title }, { requestId })`, to reuse the normal mutation receipt when explicitly retrying a database step.
+
+Cloudflare runs queries, mutations and actions in one dynamic SQLite facet. The server runtime installs an ALS-backed global fetch guard before importing app modules. Ordinary fetch works in actions, including SDKs that capture fetch at import time; queries and mutations reject it. This is a DX guard, not a security boundary between handlers. Actions call queries and mutations directly in the same facet, with fresh database contexts and no application call-count limit. A scoped RPC capability handles outbound HTTP and reports committed tables to refresh subscriptions before the action continues. Platform credentials remain trusted, native networking stays disabled, and external I/O does not hold the database queue. Actions share module state with other handlers.
+
+Cloudflare CPU and subrequest limits still apply (10 ms CPU and 64 worker subrequests). Local database calls do not consume RPC subrequests. There are no application concurrency or call-count quotas or separate action timeout; token expiry bounds action lifetime. The SDK stops its database methods after completion or cancellation, and database execution checks token expiry. Publication is checked when admitting external calls; deployment replacement cancels active actions. Already committed writes and accepted external effects remain committed. Actions are not durable jobs. Nested action calls, scheduling, internal-only functions and app-secret management are deferred.
+
+## Source layout
+
+App projects keep UI views in `src/views/`, backend implementations in `src/functions/`, and database tables in `src/schema.ts`. `src/server.ts` imports functions and registers them with `defineServer`; `src/client.ts` registers views and configures the root provider. `tailorkit init` generates this layout, a sample query, and the provider setup. With the umbrella package, import backend definitions from `tailorkit/server` and Preact hooks from `tailorkit/client`.
+
+Export the function type from `src/server.ts`:
+
+```ts
+const app = defineServer({ ...functions, importNote });
+export default app;
+```
+
+The shared `#tailorkit` module exposes a browser API inferred from that type:
+
+```ts
+import { createApi } from "tailorkit/client";
+import type app from "./server";
+
+export const api = createApi<typeof app.functions>();
+```
+
+Views import `api` from `#tailorkit`. Adding functions or changing their input/output schemas updates types immediately through the type-only import: no backend type generation or build is needed. `createApi` creates references by function name without importing or evaluating server implementations. Init sets up this link. Host schema generation includes it when the configured server entry exists (default `src/server.ts`), including default detection with no server configuration. It resolves the import relative to the generated file, including custom output paths. Missing server files omit the backend API export. Enable backend builds with `server: {}` in config. Client and server entry points default to `src/client.ts` and `src/server.ts`. Configure `client.entry` and `server.entry` in `tailorkit.config.ts` to change them; paths are relative to that config file. API type generation and browser import protection follow the configured server entry. CLI entry overrides are unsupported.
+
+The SDK itself uses these directories:
+
+- `src/database/`: SQLite schema builders, database types and the tracked Drizzle driver.
+- `src/server/`: query/mutation/action definitions, atomic database execution, async action execution, realtime coordination and server RPC transport. Tests live beside the implementation.
+- `src/client/`: browser WebSocket connection, typed references and session fetching/caching in `session.ts`.
+- `src/auth/`: shared token policy, signing/verification, public-key validation and trusted platform key fetching/caching. Change token lifetime and renewal timing in `policy.ts`.
+
+The root `index.ts`, `client.ts`, `server.ts` and `protocol.ts` files expose the public entry points. `views.ts` implements remote views and `preact.ts` implements the provider and hooks. `errors.ts` is shared by the client and server. Private execution and Cloudflare hosting live in `apps/apps-worker`; JWT helpers live in the private `@tailorkit/api-utils/app-auth` module.
+
+Auth signing and verification use Effect v4. `issueAppTokenEffect`, `appTokenVerifierEffect` and `createAppRuntimeVerifierEffect` compose with `Effect.gen`; their Promise counterparts run those programs at the caller boundary. The runtime verifier takes configured public JWKS via `publicKeys` and never fetches signing keys. The Cloudflare adapter supplies its `APP_RUNTIME_PUBLIC_KEYS` variable. Signing and verification share Effect's clock, including JWT expiry checks.
+
+## Build and upload
+
+Add `server: {}` to `tailorkit.config.ts` to build the backend from `src/server.ts`. The client builds from `src/client.ts` by default. `client.entry` and `server.entry` override these source entry points while output filenames stay the same. `tailorkit build` emits `.tailorkit/client/client.js` and `.tailorkit/server/server.js`, and copies committed Drizzle migration files into `.tailorkit/migrations/`. Intermediate server entries are created under the output root’s `tmp/` directory and removed after builds or when the watcher closes; `server/` contains the upload artifact. The server exports the application definition and embedded migrations; Cloudflare bootstrap code belongs to the runtime worker. The builder writes no backend reference source files. The browser builder rejects server implementation imports. `build.outDir` and `--out-dir` change the common output root for all artifacts; preview serves only its `client/` directory.
+
+`tailorkit deploy` gzips the client and private server artifacts before uploading them through platform-issued blob upload URLs. Checksums and content lengths describe the compressed bytes stored in R2. The runtime verifies and decompresses server code before loading it; client delivery serves gzip to browsers that accept it. The platform checks that decoded client bundles fit within 3 MiB before publication, and decoded delivery streams enforce the same limit. Existing uncompressed deployments remain supported. Apps need no Cloudflare credentials. R2 stores them under separate `client/` and `server/` prefixes; only client assets are public. Client-only apps continue to build without a server artifact. Watch mode watches both builds.
+
+The legacy `app-storage` SDK, `storage` config and storage CLI commands have been removed. Use `server` config and this SDK. The host session endpoint `/backend/session` uses the existing host `authenticate` callback. The platform verifies scope access and resolves the installation and runtime URL automatically; no extra host backend configuration is required.
+
+## Preact hooks
+
+Configure the provider once in `src/client.ts`:
+
+```ts
+import { ClientProvider, defineClient } from "tailorkit/client";
+import defaultView from "./views/default";
+
+export default defineClient({
+  component: ClientProvider,
+  slots: { panel: { "/": defaultView } },
+});
+```
+
+Views use `useQuery(api.list)`, `useMutation(api.add)` and `useAction(api.importNote)` from `tailorkit/client`. Queries return `data`, `error`, `status`, `isLoading`, `isPending`, `isSuccess` and `isError`. TanStack Store manages query and call state, with selectors keeping unrelated query updates from rerendering other observers. Matching active queries share one live subscription; inline input objects do not cause resubscription when their values are unchanged. Changing inputs clears stale data, fresh snapshots clear subscription errors, and unmounting the last consumer unsubscribes. `{ enabled: false }` as the third argument disables a query.
+
+Mutations expose `mutate(input)` and `mutateAsync(input)`; actions expose `execute(input)` and `executeAsync(input)`. Both expose `data`, `error`, `status`, `isPending`, `isSuccess`, `isError` and `reset()`, and accept `{ onSuccess, onError }` callbacks. Calls start only when invoked. The latest invocation determines the displayed state, and late responses cannot overwrite a newer invocation or a reset. Fire-and-forget methods capture errors in hook state; async methods additionally reject for caller-controlled workflows. Mutations automatically retry connection failures and temporary backend unavailability with exponential backoff from one second up to thirty seconds, retaining their request ID and original arguments. They stay pending during retries and stop when the client closes or a permanent error occurs. Rejected authentication triggers one session refresh before failing. Actions are never automatically retried.
+
+`ClientProvider` creates and closes its client automatically. A custom wrapper can pass a caller-owned `client` and/or a global `onError` callback; caller-owned clients remain open when the provider unmounts. The root `component` stays mounted when the host switches views and unmounts when the app root is cleared. No manual client creation, subscriptions or effect cleanup is needed in views.
+
+## Imperative client
+
+```ts
+import { createClient } from "tailorkit/client";
+import { api } from "#tailorkit";
+
+const client = createClient();
+const stop = client.subscribe(api.list, undefined, (notes) => render(notes));
+await client.mutate(api.add, { title: "Shared with every active client" });
+stop(); // Abort this query stream and unregister its subscription.
+client.close(); // Close the client's connection when it is no longer needed.
+```
+
+Shared oRPC fetch procedures carry one-off calls; an oRPC WebSocket carries full query snapshots. The SDK derives its client types from the public oRPC contract in `@tailorkit/app/protocol`. Iterator cancellation unregisters subscriptions. The sandbox bridge supplies scoped JWTs only; backend traffic connects directly to the host-authorized runtime origin. Platform-issued tokens last five minutes. The host SDK caches sessions until one minute before expiry. The socket reconnects one minute before expiry, resubscribes active queries and receives fresh snapshots. No subscription pings or per-query expiry leases are required. A broken connection drops server subscriptions; reconnect creates new subscriptions. Inactive/unsubscribed queries receive no updates.
+
+Automatic mutation retries reuse the original UUID. The atomic receipt returns the original result without writing or invalidating again. For explicit retries across separate `client.mutate` calls, retain a UUID and pass `{ requestId }` to each call. Reusing that UUID with different arguments or identity is rejected. Retry delays can be configured through `createClient({ retryDelayMs })`; query subscriptions use this delay too.
+
+## Reactivity and provider boundary
+
+The Drizzle driver records tables read by each query, including empty selections and joins, and tables changed by successful writes. Only committed writes invalidate. The supervisor reruns affected active queries as their original verified users and replaces each dependency set. Initial subscription registration and mutations share a queue, avoiding an initial-snapshot race. Slow consumers retain the latest complete pending snapshot.
+
+The host provides the `/rpc` base URL. `client.query`, `client.mutate` and `client.action` POST to `/rpc/queries`, `/rpc/mutations` and `/rpc/actions` respectively, with the session JWT in the Authorization header. `client.subscribe` opens `/rpc/queries` as a WebSocket and reconnects before token expiry. The trusted installation Durable Object owns subscriptions and invalidates them after both client and action mutations. The isolated SQLite facet returns a serializable response, touched tables and commit status over direct RPC, including table metadata on errors. Rebuild existing clients alongside server bundles when adopting these routes.
+
+Nested groups are supported in `defineServer({ todos: { list, add }, tasks: { importTodos } })` and inferred by `createApi<typeof app.functions>()`. Calls such as `client.query(api.todos.list)` preserve the wire name `todos.list`. An action declaring `.functions({ todos: { list, add } })` receives `ctx.queries.todos.list()` and `ctx.mutations.todos.add(...)`.
+
+`@tailorkit/app/protocol` defines the public oRPC contract and application migration input types. The private BUSL-1.1 worker in `apps/apps-worker` owns execution, ALS and the fetch guard, database transactions and receipts, authentication, subscriptions and Cloudflare hosting. The public Apache-2.0 SDK contains app definitions, schema helpers, clients, hooks and build tooling. App authors and browser clients do not need Effect.
+
+## Local validation and current limits
+
+```sh
+pnpm --filter @tailorkit/app build
+pnpm --filter tailorkit build
+pnpm --filter backend-todo build
+pnpm --filter @tailorkit/app test
+pnpm --filter @tailorkit/apps-worker test
+```
+
+The runtime test runs disposable local Wrangler/workerd/R2 state and two clients against the example's real backend, including an external API action and writes continuing while it waits. It checks persistent writes, atomic replay protection, realtime snapshots, JWT renewal and recovery after restart. It needs no Cloudflare account and deploys nothing. See `examples/apps/backend-todo` and the runtime README.
+
+## Database migrations
+
+Generate app migrations with Drizzle Kit v1 and commit the generated files. `table()` defines a Drizzle-compatible schema; schema changes take effect through these migrations.
+
+```sh
+pnpm db:generate
+# Or run directly, with an optional migration name:
+pnpm exec tailorkit db generate --name add_notes
+```
+
+Run `pnpm db:generate` after changing `src/schema.ts`, review and commit the generated migrations, then build and deploy normally. Init and the todo examples include matching Drizzle v1 development dependencies and this script. No `drizzle.config.ts` is needed: generation uses SQLite, `src/schema.ts`, and root `migrations/` by default. `tailorkit.config.ts` is the only framework config; `server.migrations` changes the directory for both generation and builds. No database connection is needed to generate migrations. Drizzle handles generation and rename prompts; TailorKit supplies the paths.
+
+The builder reads Drizzle v1's `migrations/<timestamp>_<name>/migration.sql` folders, splits their statement breakpoints and embeds the SQL with SHA-256 checksums in the private server artifact. To use another directory, set `server.migrations` in `tailorkit.config.ts`. An explicitly configured directory must exist. An absent default `./migrations` directory is allowed only when there are no schema tables to migrate. Older `_journal.json` migration layouts are unsupported.
+
+Before bundling, the builder uses Drizzle Kit to generate a fresh snapshot of `src/schema.ts` in a temporary directory and compares its schema entities with the latest committed migration snapshot. Missing or stale migrations fail the build with a `tailorkit db generate` instruction. This check does not write to migration history, connect to a database, or check deployed database state. Generating migrations stays an explicit step so SQL can be reviewed. The builder watches the schema and migration files in watch mode.
+
+When an installation's SQLite facet starts, the framework synchronously checks its `tailorkit_migrations` journal and applies missing migrations before exposing queries or mutations. The entire pending upgrade and its journal entries run in one storage transaction. Failed upgrades roll back and prevent that facet from serving database calls. Each installation upgrades independently when accessed, including installations created after deployment. Actions that call queries or mutations use this same initialized facet.
+
+Migration history is append-only: never edit, delete or insert migrations before already applied entries. Their IDs and checksums must match the stored history. Republishing code with an older migration history is rejected; automatic database downgrades are unsupported. Keep migrations small enough for the runtime's existing 10 ms CPU limit; large backfills need a separate workflow. Existing databases created outside this migration flow are not automatically adopted.
+
+Subscriptions use oRPC with Durable Object hibernation. The trusted installation persists query registrations and dependencies, restores them after wake-up, and uses durable alarms for token expiry. Each installation serializes database calls and query reruns in its trusted realtime coordinator; action database calls pass through the trusted bridge into that same coordinator, with limits of 128 connections and 256 active queries. CPU/subrequest limits apply to isolated app code; installation quotas and receipt retention remain future work. It supports one live deployment per installation, full snapshots and table-level tracking. Offline sync, optimistic updates, middleware, Redis notification delivery and advanced dependency tracking are deferred.
+
+Application bundles export a `runtimeManifest` alongside the default application definition and migrations. The SDK builder emits `{ apiVersion: 1, requires: ["database", "actions"] }`. The facet validates the exports, API version and required features before touching SQLite. Unsupported bundles fail with `INCOMPATIBLE_VERSION`. Breaking handler/module changes increment `apiVersion`; additive capabilities can be named in `requires`. Bundles only require a runtime upgrade when their declared interface or required features are unsupported. The shared `ApplicationModule` and `RuntimeManifest` types are exported by `@tailorkit/app/server`.
+
+Server builds inline dynamic imports into the single uploaded `server/server.js` file. Deployment type checking covers both configured client and server entries. Existing mounted clients reconnect after server updates without losing their UI state; server changes must remain compatible with those clients.

package/dist/builder/client-views.d.ts

@@ -0,0 +1,16 @@
+import type { InstanceRegistration } from "./instances";
+export declare function readClientViews(filename: string): Promise<{
+    slot: string;
+    path: string;
+    instances?: true | undefined;
+    disabled?: true | undefined;
+}[]>;
+export declare function readClientManifest(filename: string): Promise<{
+    views: {
+        slot: string;
+        path: string;
+        instances?: true | undefined;
+        disabled?: true | undefined;
+    }[];
+    instanceResolvers: InstanceRegistration[];
+}>;

package/dist/builder/drizzle.d.ts

@@ -0,0 +1,2 @@
+/** Use the app's Drizzle version with explicit flags; no Drizzle config file is needed. */
+export declare function drizzleGenerateArguments(root: string, output: string, name?: string): Promise<string[]>;

package/dist/builder/generate-migrations.d.ts

@@ -0,0 +1,6 @@
+export interface GenerateAppMigrationsOptions {
+    configPath?: string;
+    cwd?: string;
+    name?: string;
+}
+export declare function generateAppMigrations(options?: GenerateAppMigrationsOptions): Promise<string>;

package/dist/builder/index.d.ts

@@ -1,11 +1,10 @@
 export { createTailorKitUploadManifest, tailorkitUploadManifestSchema, type TailorKitUploadManifest, } from "./upload-manifest";
+export { generateAppMigrations, type GenerateAppMigrationsOptions } from "./generate-migrations";
 export interface BuildAppOptions {
     configPath?: string;
     cwd?: string;
-    entry?: string;
     mode?: string;
     outDir?: string;
     watch?: boolean;
 }
 export declare const buildApp: (options?: BuildAppOptions) => Promise<unknown>;
-//# sourceMappingURL=index.d.ts.map

package/dist/builder/instances.d.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from "vite";
+export interface InstanceModule {
+    filename: string;
+    names: string[];
+}
+export interface InstanceRegistration {
+    slot: string;
+    path: string;
+    resolver: string;
+}
+export declare function extractInstances(filename: string, source: string, root: string, includedNames?: string[]): Promise<{
+    names: string[];
+    server: string;
+    browser: string;
+} | undefined>;
+export declare function instanceExtractionPlugin(root: string, serverConfigured: boolean, modules: Map<string, InstanceModule>): Plugin;
+export declare function instanceServerPlugin(root: string, modules: InstanceModule[]): Plugin;
+export declare function instanceServerImports(modules: InstanceModule[]): string;
+export declare function instanceServerBindings(modules: InstanceModule[], registrations: InstanceRegistration[]): string;

package/dist/builder/migrations.d.ts

@@ -0,0 +1,6 @@
+import type { AppMigration } from "../protocol";
+/** Read the timestamped migration folders produced by the workspace's Drizzle Kit version. */
+export declare function readAppMigrations(directory: string, optional?: boolean): Promise<{
+    migrations: AppMigration[];
+    files: string[];
+}>;

package/dist/builder/schema-check.d.ts

@@ -0,0 +1,2 @@
+/** Generate a fresh snapshot with Drizzle in disposable storage, leaving committed history unchanged. */
+export declare function checkAppSchema(root: string, migrationsDirectory: string): Promise<void>;

package/dist/builder/server.d.ts

@@ -0,0 +1,6 @@
+import type { LoadedTailorKitConfig } from "../config/loader";
+import type { InstanceModule, InstanceRegistration } from "./instances";
+/** Bundle the private app backend and migrations. */
+export declare function buildServer(loaded: LoadedTailorKitConfig, watch?: boolean, buildOutDir?: string, instances?: InstanceModule[], registrations?: InstanceRegistration[]): Promise<import("@voidzero-dev/vite-plus-core/rolldown").RolldownOutput[] | import("@voidzero-dev/vite-plus-core/rolldown").RolldownOutput | import("@voidzero-dev/vite-plus-core/rolldown").RolldownWatcher | undefined>;
+/** Check before either build can empty an output directory. */
+export declare function validateServerBuildOutput(loaded: LoadedTailorKitConfig, output: string): void;

package/dist/builder/upload-manifest.d.ts

@@ -1,10 +1,20 @@
 import { z } from "zod";
 export declare const tailorkitUploadManifestSchema: z.ZodObject<{
     assets: z.ZodObject<{
-        client: z.ZodLiteral<"client.js">;
+        client: z.ZodLiteral<"client/client.js">;
+        server: z.ZodOptional<z.ZodLiteral<"server/server.js">>;
+        logos: z.ZodOptional<z.ZodObject<{
+            dark: z.ZodOptional<z.ZodString>;
+            light: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
+    views: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        slot: z.ZodString;
+        path: z.ZodString;
+        instances: z.ZodOptional<z.ZodLiteral<true>>;
+        disabled: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strip>>>;
     version: z.ZodLiteral<1>;
 }, z.core.$strip>;
 export type TailorKitUploadManifest = z.output<typeof tailorkitUploadManifestSchema>;
-export declare const createTailorKitUploadManifest: () => TailorKitUploadManifest;
-//# sourceMappingURL=upload-manifest.d.ts.map
+export declare const createTailorKitUploadManifest: (logos?: TailorKitUploadManifest["assets"]["logos"], server?: boolean, views?: TailorKitUploadManifest["views"]) => TailorKitUploadManifest;