@prisma/composer 0.16.0 → 0.17.0

package/skills/prisma-composer/SKILL.md

@@ -1,805 +0,0 @@
----
-name: prisma-composer
-metadata:
-  library: "@prisma/composer"
-  library_version: "0.16.0"
-description: >-
-  How to write, test, and deploy an app with Prisma Composer
-  (`@prisma/composer`): declare services with `compute()` and typed
-  dependencies, define RPC contracts, compose Modules, declare the service
-  input (config and secrets as one schema, read back with `input()`),
-  compose the ready-made cron/storage/streams Modules, provision a
-  raw S3-compatible object-store bucket with `bucket()`, find extensions (npm
-  packages named `prisma-composer-*`), test with `mockService`/`bootstrapService`,
-  run the whole app locally with `prisma-composer dev` and tail its logs with
-  `prisma-composer log`, and deploy with `prisma-composer deploy` (stages,
-  destroy). Use when building a Prisma App, wiring a service dependency, adding
-  a Postgres database, adding scheduled jobs / blob storage / event streams / a
-  raw bucket, writing tests for composed services, running an app locally,
-  reading its logs, or deploying/tearing down an environment. Triggers on
-  "prisma composer", "@prisma/composer", "prisma app", "compute()",
-  "service.load()", "module()", "contract()", "mockService",
-  "bootstrapService", "prisma-composer dev", "prisma-composer log",
-  "prisma-composer deploy", "--stage", "--fresh", "--tail",
-  "prisma-composer destroy", "prisma-composer-", "bucket()".
----
-
-# Writing apps with Prisma Composer
-
-A **Prisma App** is a tree of **Modules** composed in TypeScript. The leaves
-are **services** (`compute()`) and **resources** (`rawPostgres()`); the root
-module wires them together by their typed ports. Your code receives everything
-from exactly one place — the service node:
-
-- `service.load()` — dependencies (typed RPC clients, database bindings)
-- `service.input()` — the service's whole input, one schema-validated typed
-  object; credentials in it are redacting `SecretString` boxes
-- `service.port()` — the reserved port to bind (default 3000), typed; never
-  `process.env`
-
-The framework never bundles or transforms your code. You build your app with
-whatever bundler you like (`bun build`, `next build`); `prisma-composer deploy`
-assembles the built output and provisions it on Prisma Cloud (Compute + Prisma
-Postgres).
-
-Two things make building here fast and hard to get wrong — lean on both:
-
-- **Compose before you write.** Reach for an existing Module (below) before
-  implementing a capability yourself; wiring one in is a couple of lines.
-- **The compiler checks the wiring.** A dependency wired to the wrong
-  producer, a missing RPC handler, a config value of the wrong shape — all of
-  it fails `tsc`, not the deploy. Typecheck, then build, then deploy; don't
-  reach for the cloud to find out whether the app is correct.
-
-Two packages, and only two, appear in your `package.json`:
-
-| Package | Provides |
-| --- | --- |
-| `@prisma/composer` | Core authoring: `module`, `secret`, `isSecretString`, `/arktype` (the `secretString()` schema leaf), `/rpc`, `/node`, `/nextjs`, `/config`, `/testing`, the `prisma-composer` CLI |
-| `@prisma/composer-prisma-cloud` | The Prisma Cloud target: `compute`, `postgres`, `envSecret`, `envParam`, `/control`, `/testing`, and the shared `/cron`, `/storage`, `/streams`, `/orm` modules |
-
-## tsconfig and import specifiers
-
-Within the entry graph (everything reachable from `module.ts`) relative
-imports may use `./service.js` or extensionless `./service`. The CLI maps
-`.js` and extensionless specifiers to the matching `.ts` source under Node;
-Bun does this natively.
-
-A minimal tsconfig:
-
-```jsonc
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "Preserve",
-    "moduleResolution": "bundler",
-    "noEmit": true,
-    "strict": true,
-    "skipLibCheck": true,
-    "types": ["bun"]
-  },
-  "include": ["module.ts", "src"]
-}
-```
-
-## Anatomy of a service
-
-A service is four small files. Worked example: an `auth` service that owns a
-Postgres database and serves an RPC contract, consumed by a `storefront`
-Next.js app.
-
-**The contract** lives with the service that owns it. Any Standard Schema
-validator types the messages; arktype is the house choice:
-
-```ts
-// auth/src/contract.ts
-import { contract, rpc } from '@prisma/composer/service-rpc';
-import { type } from 'arktype';
-
-export const authContract = contract({
-  verify: rpc({ input: type({ token: 'string' }), output: type({ ok: 'boolean' }) }),
-});
-```
-
-**The service declaration** is pure data — name, dependencies, build, exposed
-ports. No behavior, no platform keys:
-
-```ts
-// auth/src/service.ts
-import node from '@prisma/composer/node';
-import { compute, postgres } from '@prisma/composer-prisma-cloud';
-import { authContract } from './contract.ts';
-
-export default compute({
-  name: 'auth',
-  deps: { db: rawPostgres() },
-  build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
-  expose: { rpc: authContract },
-});
-```
-
-**The server entry** is what your build produces and the platform boots. It
-reads its dependencies through `load()` and serves the contract with
-`serve()` — the handler map is keyed by the expose port's name and is
-exhaustive at compile time:
-
-```ts
-// auth/src/server.ts
-import { serve } from '@prisma/composer/service-rpc';
-import { SQL } from 'bun';
-import service from './service.ts';
-
-const { db } = service.load(); // { url } — you build your own client
-const port = service.port();   // the reserved port, resolved (default 3000)
-
-const sql = new SQL({ url: db.url, max: 1, idleTimeout: 10 });
-
-const handler = serve(service, {
-  rpc: {
-    verify: async ({ token }) => ({ ok: token.length > 0 }),
-  },
-});
-export default handler;
-
-// Bind all interfaces — Compute routes external HTTP to the VM; a
-// loopback-only listener is unreachable.
-Bun.serve({ port, hostname: '0.0.0.0', fetch: handler });
-```
-
-**The consumer** declares the dependency as `rpc(contract)` and gets a typed
-client back from `load()`:
-
-```ts
-// storefront/src/service.ts
-import nextjs from '@prisma/composer/nextjs';
-import { rpc } from '@prisma/composer/service-rpc';
-import { compute } from '@prisma/composer-prisma-cloud';
-import { authContract } from '@my-app/auth/contract';
-
-export default compute({
-  name: 'storefront',
-  deps: { auth: rpc(authContract) },
-  build: nextjs({ module: import.meta.url, appDir: '..' }),
-});
-```
-
-```tsx
-// storefront/app/page.tsx
-import service from '../src/service.ts';
-
-// load() reads the runtime environment, which doesn't exist at build time —
-// render per request instead of prerendering.
-export const dynamic = 'force-dynamic';
-
-export default async function Home() {
-  const { auth } = service.load();
-  const { ok } = await auth.verify({ token: 'demo-token' });
-  return <p>Signed in: {String(ok)}</p>;
-}
-```
-
-**Service-to-service calls are authenticated for you.** At deploy the
-framework mints a distinct, unguessable **service key** per consumer→provider
-binding: the consumer's client sends it on every call, and `serve()` returns
-`401` to anything else *before* the handler runs. Nothing declares it — no key
-in the contract, the service, the module, or the app's code.
-
-Two rules follow for you specifically: **don't build your own
-service-to-service auth** on top of this, and **don't tell a user to `curl` a
-deployed `/rpc/<method>` to check it works** — an unwired caller always gets
-`401`, which looks like a broken deploy and isn't. Debug through a consumer,
-or locally.
-
-**Calls carry an idempotency key and retry safely for you.** Every call the
-generated client makes carries an `Idempotency-Key`; a call dropped while the
-target cold-starts is retried with a backoff, and `serve()` runs one call per
-key — a retry that arrives after the first completed replays that answer
-instead of re-running the handler. So every method is safely retryable and no
-contract declares anything about it (do not add an "is this idempotent" flag —
-the framework does not have one). Two consequences for you: a handler may take
-an **optional third argument** `(input, deps, ctx)` and read `ctx.idempotencyKey`
-(`string | undefined` — it's absent for a keyless caller) if it needs exactly-once
-beyond one instance's memory (most don't); and a request without the header is
-served once without deduplication rather than rejected, so a hand-rolled probe
-works but gets no retry safety.
-
-| | |
-| --- | --- |
-| Locally / in tests | nothing is provisioned, so `serve()` passes every call through — never supply a key in `inputs` |
-| Per binding | two consumers of one provider hold different keys, so one leaking can't impersonate the other |
-| Scope | service-level — any valid key reaches every method that service exposes; split into two services to gate separately |
-| Rotation | remove the binding (or destroy the stack) and redeploy — a plain redeploy is a no-op, not a rotation |
-| Storage | `COMPOSER_*` variables the deploy owns and rewrites; never hand-edit one |
-
-It's a capability token ("I'm a service this app wired to you"), not a secret,
-and its value lives in deploy state — deliberately unlike `secret()`, whose
-value the framework never holds. `docs/design/90-decisions/ADR-0030…` in the
-prisma/composer repo carries the reasoning.
-
-## The root module
-
-The root module provisions the pieces and wires exposed ports into dependency
-slots. It is the app — `prisma-composer deploy` loads its default export:
-
-```ts
-// module.ts
-import { module } from '@prisma/composer';
-import authModule from '@my-app/auth';
-import storefrontService from '@my-app/storefront';
-
-export default module('my-app', ({ provision }) => {
-  const auth = provision(authModule);
-  provision(storefrontService, { deps: { auth: auth.rpc } });
-});
-```
-
-`provision(node, opts?)` accepts `id` (defaults to the node's own name),
-`deps` (wire each declared dependency to a provisioned ref or exposed port),
-`input` (the service's input binding — required exactly when it declares an
-input schema, see § Service input), and `secrets` (bind a module boundary's
-forwarded secret needs).
-
-## Builds are yours
-
-The framework assembles only what you built — users build, the framework
-assembles. For a plain server process, `entry` must point at a single
-self-contained ESM file: everything inlined except runtime built-ins (`bun`,
-`bun:*`, `node:*`), which the deploy VM provides. Deploy copies that one file
-and never ships `node_modules`, so anything left un-inlined fails at boot. Any
-bundler that produces such a file works. With bun:
-
-```sh
-bun build src/server.ts --target=bun --outfile dist/server.mjs
-```
-
-Two services in one package means two separate builds, one per entry — not one
-multi-entry build, which would split shared code into a chunk neither output
-contains.
-
-If the build emits a directory rather than one file — a server plus the client
-bundle, CSS and images it serves, as Bun's HTML import produces — name the
-directory with `dir` and the booting file inside it with `entry`:
-
-```ts
-build: node({ module: import.meta.url, dir: '../dist/server', entry: 'server.js' })
-```
-
-`dir` resolves relative to the service module; `entry` resolves inside `dir`
-and may be nested. Deploy copies the tree verbatim and boots the named file,
-so the server must resolve its siblings against `import.meta.url`, not the
-working directory. Nothing is inferred, and two rules bite: the tree must
-contain no symlinks (the packager rejects them — assembly fails and names the
-link), and `entry` must be a file inside `dir` (`../` is an error, not an
-escape). Omit `dir` for the single-file form.
-
-For Next.js, `next build` with `output: 'standalone'` is the whole build;
-`nextjs({ module, appDir })` tells the deploy where the app root is.
-
-Always build before deploying — `prisma-composer deploy` does not build for
-you.
-
-## Deploy config
-
-`prisma-composer.config.ts` usually sits next to `module.ts`, but it may live in
-any ancestor directory: the CLI searches the entry's directory first, then each
-parent, and uses the nearest one. It is read only by `prisma-composer
-deploy`/`destroy`, never imported by app code. A plain-JavaScript project can
-name it `prisma-composer.config.mjs` or `.js` to keep it out of its TypeScript
-build (a build with `allowJs` still needs an explicit `exclude`); `.mts` is the
-TypeScript ES-module spelling. Within one directory `.ts` wins, then `.mts`,
-`.mjs`, `.js`:
-
-```ts
-// prisma-composer.config.ts
-import { defineConfig } from '@prisma/composer/config';
-import { nodeBuild } from '@prisma/composer/node/control';
-import { prismaCloud, prismaState } from '@prisma/composer-prisma-cloud/control';
-
-export default defineConfig({
-  extensions: [prismaCloud(), nodeBuild()],
-  state: () => prismaState(), // deploy state, in its own database on the stage's branch
-});
-```
-
-Add `nextjsBuild()` from `@prisma/composer/nextjs/control` to `extensions`
-when the app contains a Next.js service.
-
-## Databases
-
-Two kinds of Postgres dependency:
-
-**`rawPostgres()`** — the binding is `{ url }` and the app owns its client.
-Construct it in your server entry, as in the auth example above.
-
-**`postgres(...)`** — a Prisma-ORM-typed database: `load()`
-returns the typed client the framework constructs from your data contract, so
-queries like `db.orm.public.Product.all()` are compile-time checked. The
-contract is emitted from `contract.prisma` by `prisma contract emit` and
-wrapped once, referenced by both ends:
-
-```ts
-// src/data.ts — the ONE value both ends reference
-import { dataContract } from '@prisma/composer-prisma-cloud/orm';
-import type { Contract } from '../contract.d.ts';
-import contractJson from '../contract.json' with { type: 'json' };
-
-export const catalogData = dataContract<Contract>(contractJson);
-```
-
-The dependency end is `deps: { db: postgres(catalogData) }`. The resource
-end (inside the module that owns the database) also names the
-`prisma.config.ts` path, which the deploy's migration step loads to find
-`migrations/` — committed migrations are replayed at deploy, before the
-service starts:
-
-```ts
-const db = provision(
-  postgres({ name: 'database', contract: catalogData, config: './prisma.config.ts' }),
-);
-```
-
-(`postgres` is both ends: the contract alone is the dependency end; the
-options object is the resource end.)
-
-The deploy is replay-only: it applies the migrations committed under
-`migrations/` and never creates schema itself. Every schema change (including
-the very first schema of a new database) follows the same loop:
-
-1. Edit `contract.prisma`.
-2. `prisma contract emit` — regenerates `contract.json` + `contract.d.ts`.
-3. `prisma migration plan --name <slug>` — authors the migration into
-   `migrations/` (on an empty graph this authors the baseline,
-   empty → your schema).
-4. Commit `migrations/` with the change, then deploy. A fresh database
-   replays the whole path from empty.
-
-If no authored path reaches the target contract, the deploy (and
-`prisma-composer dev` against a stale local database) refuses with
-`MIGRATION_PATH_NOT_FOUND` and names the exits: author the missing migration
-as above, or — when iterating against a local database only — bring it along
-directly with `prisma db update`. Never skip step 3 before a deploy.
-
-See `examples/store/modules/catalog` in the prisma/composer repo for the
-complete pattern.
-
-## Object Storage
-
-`bucket` is a raw S3-compatible object-store bucket, imported alongside `postgres`:
-
-```ts
-import { bucket, compute } from '@prisma/composer-prisma-cloud';
-
-// service.ts — dependency end: receives { url, bucket, accessKeyId, secretAccessKey }
-export default compute({ name: 'uploads', deps: { store: bucket() } });
-
-// module.ts — resource end: provisions the bucket and mints a keypair
-const store = provision(bucket({ name: 'uploads' }));
-provision(uploadsService, { deps: { store } });
-```
-
-Use any S3-compatible client with the binding: the shape matches the standard S3
-config and is also compatible with the `s3()` dependency from `/storage`, so any
-service wired to `s3()` can be rewired to a `bucket` resource without changing
-the service declaration.
-
-## Reusable Modules
-
-A Module is the unit of reuse: it owns its internals (its database, its
-services) and exposes only typed ports. Declare the boundary in the second
-argument; wire internals in the builder; return the exposed ports:
-
-```ts
-// auth/src/module.ts — a Module that owns its own Postgres
-import { module, secret } from '@prisma/composer';
-import { postgres } from '@prisma/composer-prisma-cloud';
-import { authContract } from './contract.ts';
-import authService from './service.ts';
-
-export default module(
-  'auth',
-  { secrets: { signingKey: secret() }, expose: { rpc: authContract } },
-  ({ secrets, provision }) => {
-    const db = provision(rawPostgres({ name: 'database' }));
-    const service = provision(authService, {
-      id: 'service',
-      deps: { db },
-      input: { signingKey: secrets.signingKey }, // forwarded ref as a binding leaf
-    });
-    return { rpc: service.rpc };
-  },
-);
-```
-
-Naming rules that bite: a provision id shorter than 3 characters is rejected
-by the platform (name the database `'database'`, not `'db'`), and a service
-whose name equals its enclosing module's reads as `auth.auth` unless you give
-it an explicit `id`.
-
-A module can also declare boundary `deps` — inputs the parent wires exactly as
-it would wire a service's. The consumer never sees the module's internals.
-
-### The building blocks you can compose
-
-Modules are the building blocks: provision one, wire its exposed port, and
-you're done — you never reimplement what a Module already owns. The
-first-party set ships inside `@prisma/composer-prisma-cloud`. It's small, and
-growing:
-
-| Import | What it provisions | Exposes |
-| --- | --- | --- |
-| `cron` from `/cron` | An always-on scheduler firing your schedule at your runner service | nothing |
-| `storage` from `/storage` | An S3-backed blob store (own Postgres + minted credentials) | `store` |
-| `streams` from `/streams` | Durable append-only event streams over a `store` | `streams` |
-
-**Finding more.** A Composer extension — a package that brings its own
-Modules, resources, or deploy target — is published on npm under the name
-`prisma-composer-*`. That name is the convention, so it's how you look for
-one. The ecosystem is new: today the blocks above plus the app Modules you
-write are the whole set, so don't reach for a `prisma-composer-*` package
-without checking that it actually exists on npm first.
-
-Cron end to end — the schedule is one source of truth; `serveSchedule` is
-exhaustive over its job ids at compile time:
-
-```ts
-// service.ts
-import { defineSchedule, triggerContract } from '@prisma/composer-prisma-cloud/cron';
-export const schedule = defineSchedule({ tick: '60s' });
-// the runner service exposes { trigger: triggerContract }
-
-// server.ts
-import { serveSchedule } from '@prisma/composer-prisma-cloud/cron';
-const handler = serveSchedule(service, schedule, {
-  tick: (deps) => deps.worker.tick({}),
-});
-
-// module.ts — the cron module's boundary deps mirror the runner's own
-provision(cron({ schedule, runner: runnerService }), { deps: { worker: worker.rpc } });
-```
-
-## Service input
-
-Choosing the channel is most of the decision:
-
-| The value is… | Declare | Provide | Read |
-| --- | --- | --- | --- |
-| produced by another node | `deps: { db: rawPostgres() }` | wire at `provision()` | `load()` |
-| anything else — config or credential | one field of the `input` schema | bind at `provision()`: literal, `envParam()`, or `envSecret()` | `input()` |
-
-The service declares its whole incoming configuration — plain values and
-credentials together — as **one
-[Standard Schema](https://standardschema.dev)** (arktype is the house
-choice). A credential is a field typed as the redacting `SecretString` box;
-conditional legality ("no stripe key unless billing is on") is an ordinary
-schema union:
-
-```ts
-// service.ts — the shapes that are legal
-import { secretString } from '@prisma/composer/arktype';
-import { type } from 'arktype';
-
-compute({
-  name: 'scheduler',
-  input: type({
-    jobs: type({ jobId: 'string', every: 'string' }).array(),
-    'region?': 'string',
-    apiKey: secretString(),
-  }),
-  // ...
-});
-
-// module.ts — where each value comes from; the binding mirrors the schema's shape
-import { envParam, envSecret } from '@prisma/composer-prisma-cloud';
-provision(scheduler, {
-  input: {
-    jobs: [{ jobId: 'tick', every: '60s' }],   // a literal
-    region: envParam('REGION'),                 // a per-stage platform variable
-    apiKey: envSecret('SCHEDULER_API_KEY'),     // a credential — name only, never the value
-  },
-});
-
-// server.ts — one call, one validated typed object
-const input = service.input();
-input.apiKey.expose(); // the only way to a secret's value; the box redacts everywhere else
-```
-
-Rules that bite:
-
-- **Secretness is enforced by validation**: a literal bound where the schema
-  expects `SecretString` fails the deploy, and `envSecret` bound to a plain
-  string field fails the same way. Don't put credentials in plain fields.
-- **`envParam` values arrive as raw strings** — bind them to string fields.
-  The stage's platform variable is the store; the deploying shell only seeds
-  it (preflight copies a missing name up from the shell, and fails early,
-  naming the variable, when both lack it). Changing the platform value needs
-  a redeploy.
-- **Absence is the schema's call**: an env-bound field whose variable is
-  unset (or empty) resolves to *key omitted* — legal only if the schema says
-  so (optional field, union arm). The deploy report prints the serialized
-  input document (secret-free: secrets ride as `{"$secret":"VAR"}` pointers)
-  and every key that resolved absent.
-- **The reserved `port` (default 3000) is outside the schema** — read it
-  through `service.port()` (a sibling of `service.origin()`), never
-  `process.env`. The framework also exports `PORT` for Next.js standalone,
-  which binds it itself.
-- A module forwards a secret need without learning the platform name
-  (the auth Module above); the forwarded ref is a binding leaf.
-
-`examples/env-param` and `examples/storefront-auth` in the prisma/composer
-repo are the working versions.
-
-## Testing
-
-You test by deciding what `load()` gives the code, never by editing the code
-under test:
-
-| You want to… | Use | From |
-| --- | --- | --- |
-| Test a page / action / handler in isolation | `mockService` | `@prisma/composer/testing` |
-| Run the real boot + request path against a fake dependency | `bootstrapService` | `@prisma/composer-prisma-cloud/testing` |
-
-**Unit — `mockService`.** Returns a copy of the service whose `load()` yields
-your doubles (type-checked against the declared deps) and whose `input()`
-yields the object you pass under the reserved `input` key, in one flat
-object (required exactly when the service declares an input schema; handed
-over as-is, not validated). Wiring the module substitution is your runner's
-job (`vi.mock` in Vitest, `mock.module` in bun test):
-
-```tsx
-// page.test.tsx
-import { mockService } from '@prisma/composer/testing';
-import realService from '../src/service.ts';
-
-vi.mock('../src/service.ts', () => ({
-  default: mockService(realService, {
-    auth: { verify: async () => ({ ok: true }) }, // wrong shape = compile error
-  }),
-}));
-
-import Page from './page.tsx';
-expect(renderToString(await Page())).toContain('Signed in: true');
-```
-
-**Integration — `bootstrapService`.** Boots the service's real built entry
-in-process against a config you choose, exactly as a deployed boot would;
-drive it over real HTTP. Run under `bun test`:
-
-```ts
-import { bootstrapService } from '@prisma/composer-prisma-cloud/testing';
-import fakeAuth from '@my-app/auth/fake'; // in-memory handler, no db
-import storefront from '../src/service.ts';
-
-const fake = Bun.serve({ port: 0, fetch: fakeAuth });
-
-const app = await bootstrapService(storefront, {
-  service: { port: 4310 },
-  inputs: { auth: { url: fake.url.href } },
-});
-
-const res = await app.fetch(new Request(app.url));
-```
-
-- **`service.port` must be concrete** — the entry self-listens; no OS-assigned
-  port is reported back.
-- **No `close()`** — run each integration-test file in its own process (bun
-  test does).
-- **Next.js services take a third argument**, a boot thunk, because the built
-  entry lives in Next's standalone output — resolve it with
-  `standaloneServerPath` from `@prisma/composer/nextjs/control`.
-  `bootstrapService` exports the resolved port as `process.env.PORT` before
-  booting, which is what Next's standalone server binds.
-- **A service with an input schema takes `input`** in the config — a binding
-  exactly like `provision()`'s, run through the real serialize/read path, so
-  `input()` in the booted entry sees what a deploy would produce.
-
-**The fake you pass.** A dependency's type is its contract, so any value of
-that shape is a valid double: a bare object (fastest), the real client over an
-in-memory handler, or a real local server (what `bootstrapService` drives).
-Ship a dependency's fake from its own package as a `/fake` entry point,
-outside `src/`, so the fake and the real service always share one contract.
-
-## Running locally
-
-`prisma-composer dev module.ts` runs the whole app on this machine — every
-service, its Postgres and buckets, wired as they deploy — with **no cloud
-credentials** (no `PRISMA_*`). It runs the same pipeline as deploy against
-local emulators, so build first, exactly like deploy:
-
-```sh
-turbo run build && prisma-composer dev module.ts
-```
-
-It prints each service's local URL (the "front door"), watches built output
-and restarts a service when its build changes, and runs until Ctrl-C. Ctrl-C
-stops the app's processes but leaves the local databases, buckets, and their
-data up, so the next `dev` is a warm start; `--fresh` wipes this app's local
-instances and data first.
-
-`dev` does **not** print service logs — that would bury the front door once
-several services run. Logs are their own command:
-
-| You want to… | Run |
-| --- | --- |
-| Run the app locally | `prisma-composer dev module.ts` |
-| Start clean (wipe local data) | `prisma-composer dev module.ts --fresh` |
-| Tail every service's logs | `prisma-composer log module.ts` |
-| Tail one service | `prisma-composer log module.ts <address>` |
-| Show more history first | `prisma-composer log module.ts --tail <n>` |
-
-`prisma-composer log` follows the merged logs of the already-running app, each
-line prefixed with its service (`[catalog.service] …`); pass a dotted address
-to narrow to one. It only reads — it never builds, provisions, starts, or
-stops anything. `--tail <n>` sets how much recent history to show before live
-output (default 20; `0` for live-only). An unset secret doesn't block a local
-run: it becomes a placeholder plus a warning, and only the code path that
-spends it fails, at the real external service it calls. Windows isn't
-supported yet.
-
-## Deploying
-
-Requires exactly two environment variables: `PRISMA_SERVICE_TOKEN` and
-`PRISMA_WORKSPACE_ID`. The target environment — a **stage** — is chosen on the
-command line, never in code:
-
-| You want to… | Run |
-| --- | --- |
-| Deploy to production | `prisma-composer deploy module.ts` |
-| Deploy an isolated environment | `prisma-composer deploy module.ts --stage <name>` |
-| Override the app name for one run | `prisma-composer deploy module.ts --name demo-42` |
-| Tear down an isolated environment | `prisma-composer destroy module.ts --stage <name>` |
-| Tear down production's resources | `prisma-composer destroy module.ts --production` |
-
-A Prisma App is one Project; a stage is a Branch of it — its
-own compute, its own empty database, its own configuration. Deploys are
-idempotent: re-deploying a stage updates the resources inside it. A stage name
-must be a valid git ref name; an invalid name is a hard error.
-
-Destroy always requires an explicit target — a bare `prisma-composer destroy`
-is an error, and `--stage` with `--production` is too. Destroying a stage
-deletes its Branch after removing its resources; the production Branch itself
-is never deleted, only the resources inside it. Destroying production also
-deletes the Project itself once it's empty, so hand-run stacks don't leave
-behind empty Projects — but a Project still holding another stage's resources
-is kept. Destroy never creates anything: destroying a never-deployed stage
-fails rather than standing one up.
-
-```sh
-turbo run build && prisma-composer deploy module.ts --stage pr-42
-```
-
-### What a deploy prints
-
-A deploy ends by printing the app's own topology — authored names, the
-platform resource each became, and public URLs. The tree is the module
-structure (`auth.api` is the `api` service inside the `auth` module):
-
-```
-storefront-auth
-├─ auth
-│  └─ api   compute-service cps_abc123
-│           https://xyz.ewr.prisma.build
-├─ db       postgres-database db_def456
-└─ web      compute-service cps_ghi789
-            https://uvw.ewr.prisma.build
-```
-
-Read ids out of this rather than telling the user to go hunting in the
-Console. A URL appears only where the address is genuinely public — a compute
-service prints one, a database never does (it has a connection string, not a
-public endpoint), and a node whose product is secret material (an
-`s3-credentials` keypair) reports no resource line at all. A node that
-published nothing reportable still appears, marked `(no entities reported)`.
-
-Older deploys ended with a raw `{ outputs: {} }` blob from the deploy engine —
-always empty, never about the app. It is gone; nothing configured it and
-nothing consumed it.
-
-### The connection contract is checked at deploy
-
-A connection declares the values it needs by name, and the producer on the
-other end must supply them. A producer that omits one fails the deploy, naming
-the edge, the param, and what the producer did supply:
-
-```
-Connection input "auth.db" declares param "url", but its producer "db" did not
-supply it — the producer's outputs carry [host].
-```
-
-Fix it at whichever end is wrong: add the name to the outputs the producer
-returns from its lowering, or mark the param `optional` on the connection if absent is
-genuinely legal (the consumer then reads `undefined`).
-
-This is a deploy-time refusal, not a broken deploy — and it can appear on an
-app whose code didn't change. The gap used to pass silently: the value reached
-the consumer as `undefined`, went into its environment, and crashed *that*
-service at boot, blaming the reader instead of the supplier. Don't route around
-it by making the param optional unless absent really is valid; that reinstates
-the silent `undefined`.
-
-Only reachable if you authored the connection or the extension on one side —
-every shipped block supplies what it declares.
-
-### Driving deploys from code
-
-`@prisma/composer/control` exposes the CLI's operations in-process: typed
-`deploy`, `destroy`, `dev`, and `log` returning structured results — no argv,
-no CLI rendering, no exit codes (the spawned deploy engine's own inherited
-output can still reach the host terminal). The CLI itself is a renderer over
-them.
-
-```ts
-import { deploy } from '@prisma/composer/control';
-const result = await deploy({ entry: 'module.ts', stage: 'pr-42' });
-// result: { ok: true, value: { summary? } } | { ok: false, failure }
-```
-
-- Failures come back as `{ ok: false, failure }` where `failure` is a
-  structured error: branch on its dotted `failure.code` (e.g.
-  `ASSEMBLE.BUILD_FAILED`, `DEPLOY.ENGINE_FAILED` — ADR-0044's closed
-  registry), with the same fix-naming `message`/`why`/`fix` the CLI renders.
-  An engine failure's `meta.diagnostics` (exit code, reproduce command; read
-  it with the exported `executionDiagnostics(failure)`) describes the current
-  execution mechanism — branch on `code`/`message`/`cause` for anything
-  durable. The effect version conflict is `DEPS.EFFECT_VERSION_CONFLICT`, and
-  importing the module executes nothing until an operation runs. A
-  non-structured rejection out of an operation is a bug in composer, not an
-  expected failure.
-- `destroy` takes `target: { kind: 'production' } | { kind: 'stage', stage }`
-  — explicit, never defaulted.
-- `deploy`'s `summary` (the deployed topology) is best-effort; `undefined` on
-  a successful deploy is normal.
-- The deploy engine's live output still streams to the host process's stdio —
-  the current mechanism; the operations don't capture it.
-- `dev` resolves to `{ ok: true, value: session }` or a failure; the
-  session is `{ endpoints, stop(), closed }` with progress via `onEvent`, and
-  the host owns signal handling. `log` resolves to
-  `{ ok: true, value: { appName, services, lines } }` or a failure, where
-  `lines` is an `AsyncIterable` ended by a caller-owned `AbortSignal` (or by
-  the consumer stopping early); zero running services is a valid result, not
-  an error.
-
-## Production pitfalls
-
-- **Scale-to-zero closes idle database connections.** A persistent client
-  crashes into a 502 restart loop unless you keep the pool small and
-  reconnect-friendly (`new SQL({ url, max: 1, idleTimeout: 10 })` for Bun) and
-  log `uncaughtException`/`unhandledRejection` instead of dying.
-- **Bind `0.0.0.0`**, not loopback — Compute routes external HTTP to the VM.
-- **Next.js pages that call `load()` need `export const dynamic =
-  'force-dynamic'`** — the runtime environment doesn't exist at build time,
-  and Next ignores runtime env for prerendered routes.
-- **A deployed `/rpc/<method>` returns `401` to anything but a wired peer.**
-  Every RPC binding carries an auto-provisioned service key, so a hand-rolled
-  `curl` is never authorized, and a provider with no wired consumers rejects
-  everything. Not a broken deploy — reach it through a consumer, or run it
-  locally where nothing is enforced.
-- **Cold starts reset service-to-service connections.** A call into a
-  scaled-to-zero service can get `ECONNRESET`; retry it.
-- **Every `prisma-composer` command stops at start-up on an `effect` version
-  conflict** (`Dependency conflict: alchemy resolves effect@...`). Another
-  dependency floated a newer `effect` and the package manager hoisted it over
-  Composer's pin. Do what the error says: pin the whole `effect`
-  constellation in the app's `package.json` `overrides` (yarn: `resolutions`;
-  pnpm: `pnpm.overrides`) — `effect` plus `@effect/sql-d1`, `@effect/sql-pg`,
-  `@effect/vitest`, and `@effect/platform-bun`/`-node`/`-node-shared`, all at
-  Composer's exact pin — and reinstall. (A workaround for an upstream alchemy
-  bug: its own effect-family ranges float past what its code supports. The
-  repo's examples carry the block.)
-- **The ingress buffers streaming responses.** An open SSE tail delivers
-  nothing and times out at 60s — don't build on streamed HTTP responses.
-
-## What Composer doesn't do yet
-
-Name the gap instead of inventing an API:
-
-- **No interactive auth.** Deploys authenticate only via a static
-  `PRISMA_SERVICE_TOKEN`; there is no `login` flow.
-- **No in-memory contract bindings.** A dependency can't yet be wired to a
-  co-located handler without HTTP; use `bootstrapService` with a loopback
-  fake.
-- **RPC over HTTP is the only contract kind.** No gRPC, WebSocket, or
-  streaming contracts.
-
-For anything else missing, check the examples and design docs in the
-prisma/composer repo (`examples/`, `docs/design/10-domains/`,
-`docs/design/90-decisions/`), then file an issue there rather than guessing.