prisma 8.0.0-rc.13-dev.93 → 8.0.0-rc.13-dev.95

package/dist/prisma.js

@@ -27,6 +27,7 @@ import { fileURLToPath } from "node:url";
 import { execa } from "execa";
 import { Writable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import spawn$1 from "cross-spawn";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -1823,7 +1824,8 @@ const SKILL_SOURCE_PACKAGES = [
 	"@prisma/orm-postgres",
 	"@prisma/orm-sqlite",
 	"@prisma/orm-mongo",
-	"@prisma/composer"
+	"@prisma/composer",
+	"prisma"
 ];
 /** The directory inside a source package's tarball that holds its skill
 *  trees, one directory per skill. */
@@ -14243,7 +14245,7 @@ const runPackageManager = async ({ file, args, cwd, signal, onOutput }) => {
 *  must not wait on it, so the pipes are destroyed after this grace. */
 const POST_EXIT_DRAIN_GRACE_MS = 5e3;
 /**
-* The engine's spawn seam, adapted to node:child_process. Human mode
+* The engine's spawn seam, adapted through cross-spawn. Human mode
 * inherits stdio; structured mode pipes both child output streams to
 * diagnostics. Neither mode detaches or opens a new console, so the child
 * stays in this process's group (POSIX) or console (Windows).
@@ -14257,7 +14259,7 @@ function makeSpawnChild(diagnostics, options) {
 	const drainGraceMs = options?.drainGraceMs ?? POST_EXIT_DRAIN_GRACE_MS;
 	return (request) => {
 		const structured = request.output === "diagnostic";
-		const child = spawn(request.command, [...request.args], {
+		const child = spawn$1(request.command, [...request.args], {
 			cwd: request.cwd,
 			env: request.env,
 			stdio: structured ? [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prisma",
-  "version": "8.0.0-rc.13-dev.93",
+  "version": "8.0.0-rc.13-dev.95",
   "description": "The Prisma CLI: one binary for the ORM, Composer, and the Prisma Developer Platform.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -47,18 +48,19 @@
     "@prisma/composer-cli": "0.17.0-dev.2",
     "@prisma/compute-sdk": "0.42.0",
     "@prisma/management-api-sdk": "1.69.0",
-    "@prisma/orm-toolchain": "8.0.0-rc.8-dev.18",
+    "@prisma/orm-toolchain": "8.0.0-rc.9-dev.1",
     "@vercel/detect-agent": "^1.2.3",
     "better-result": "^2.9.2",
+    "cross-spawn": "^7.0.6",
     "dotenv": "^17.4.2",
     "execa": "^9.6.1",
     "open": "^11.0.0"
   },
   "devDependencies": {
-    "@prisma/cli": "8.0.0-rc.13-dev.93",
+    "@prisma/cli": "8.0.0-rc.13-dev.95",
     "@prisma/credentials-store": "^7.8.0",
-    "@repo/cli-telemetry": "8.0.0-rc.13-dev.93",
-    "@repo/tsconfig": "8.0.0-rc.13-dev.93",
+    "@repo/cli-telemetry": "8.0.0-rc.13-dev.95",
+    "@repo/tsconfig": "8.0.0-rc.13-dev.95",
     "@types/node": "^22.19.19",
     "tsdown": "^0.21.10",
     "typescript": "^6.0.3",

package/skills/prisma-platform-core-concepts/SKILL.md

@@ -0,0 +1,355 @@
+---
+name: prisma-platform-core-concepts
+metadata:
+  library: "prisma"
+  library_version: "8.0.0-rc.13-dev.95"
+  version: 2026.9.1
+description: >-
+  Use when hosting, deploying, or operating an app on the Prisma Platform:
+  projects, branches, preview environments, services and their versions,
+  Prisma Postgres databases, object-store buckets, environment variables,
+  custom domains, logs, or the GitHub integration. Triggers on "Prisma
+  Platform", "Prisma Compute", "Prisma Postgres", "Prisma Storage",
+  "preview environment", `prisma deploy`, `prisma dev`, `prisma auth`,
+  `prisma project`, `prisma branch`, `prisma service`, `prisma postgres`,
+  `prisma bucket`, `prisma git`, `prisma.config.ts`, promote, rollback.
+---
+
+# Prisma Platform core concepts
+
+> **Isolated infrastructure for every branch.**
+
+The Prisma Platform moves fast, and your training data about it is very
+likely outdated. This skill ships inside the installed `prisma` package, so
+it describes the exact version this project has: treat it as the source of
+truth over anything you remember about Prisma hosting. If
+`metadata.library_version` in this file's frontmatter does not match the
+project's installed `prisma` package, run `prisma skills sync` and re-read.
+Fuller documentation for everything here lives at prisma.io/docs; consult it
+when a concept needs more depth than this file carries.
+
+This file shares the platform's structures, hierarchies, relationships, and
+workflows. It is not a CLI reference: commands appear only where a workflow
+needs them. To learn a command surface, run `prisma --help`, or
+`prisma <group> --help` for any group named below; most commands accept
+`--json` for machine-readable output. The data contract, migrations, and
+queries belong to the `prisma-orm-core-concepts` skill; declaring services
+and modules in code belongs to `prisma-composer-core-concepts`.
+
+## The stack
+
+One CLI, `prisma`, fronts a set of products designed to be used together:
+
+| Product | What it is | Concepts live in |
+| --- | --- | --- |
+| Prisma ORM (Prisma 8) | Data contract, typed queries, migrations | `prisma-orm-core-concepts` |
+| Prisma Composer | The app declaration: services, databases, buckets, wiring | `prisma-composer-core-concepts` |
+| Prisma Compute | Hosting: runs your services next to your data | this skill |
+| Prisma Postgres | Managed PostgreSQL | this skill |
+| Prisma Storage | S3-compatible object storage | this skill |
+
+**Every deployed app is a Composer app.** Your server code plus a declaration
+(`module.ts`) naming its services, databases, and buckets. The declaration is
+the source of truth: deploying converges the platform to it, re-deploying
+applies only the difference, and removing a resource from the module removes
+it from the platform on the next deploy. There is no separate provisioning
+step and no connection strings to wire by hand; Composer injects them.
+
+## Project setup
+
+The CLI carries every command named here, but an app's own code needs its
+dependencies installed. Start from:
+
+```sh
+npm install prisma @prisma/composer @prisma/composer-prisma-cloud
+```
+
+`@prisma/composer` is what the module declaration imports;
+`@prisma/composer-prisma-cloud` is the Prisma Cloud target and brings
+`@prisma/orm-postgres` with it. The sibling skills travel inside these
+packages (`prisma-composer-core-concepts` in `@prisma/composer`,
+`prisma-orm-core-concepts` in `@prisma/orm-postgres`), so they appear after
+this install plus `prisma skills sync`, not before.
+
+Two config files with different owners:
+
+1. `prisma.config.ts` configures the CLI. Each top-level key is a section
+   owned by one product, and this CLI recognises exactly three: `orm`,
+   `composer`, and `skills`. The composed shape:
+
+   ```ts
+   import { definePrismaConfig } from "prisma/config";
+   import { defineConfig } from "@prisma/orm-postgres/config";
+
+   export default definePrismaConfig({
+     orm: defineConfig({ contract: "./src/prisma/contract.prisma" }),
+     skills: { agents: ["claude"] },
+   });
+   ```
+
+2. `prisma-composer.config.ts` configures Composer itself and is a separate,
+   mandatory file for `dev` and `deploy`: without it `dev` fails with
+   `CONFIG.FILE_MISSING`. Its contents belong to
+   `prisma-composer-core-concepts`.
+
+## The resource model
+
+1. **Workspace**: the account boundary. Members, billing, and projects live
+   here; the `auth` group manages which one you act in.
+2. **Project**: one product or codebase. Its region is chosen at creation and
+   is immutable afterwards; every resource in the project inherits it.
+3. **Branch**: the isolation boundary, named after a git branch. A branch is
+   an environment: it owns its own services, its own databases, its own
+   buckets, and its own environment-variable overrides.
+4. Inside a branch: **services** (HTTP apps, deployed as versions),
+   **databases**, and **buckets**.
+
+The first branch of a project is the **production** branch. Every branch
+after it is a **preview** branch. Production and previews differ in exactly
+two ways: which environment-variable class they resolve (see below), and
+lifecycle (previews can be reclaimed and torn down; production cannot).
+
+A CLI invocation resolves its project from a directory binding, created when
+a project is created from or linked to the directory and stored in the
+gitignored `.prisma/local.json`. Resource commands take flags to target
+another project or branch explicitly.
+
+## Branches are preview environments
+
+There is no separate "preview environment" object to create or configure. The
+branch is the environment, and branches come into being by deploying to them:
+
+1. **Push a git branch** (with the GitHub integration connected): the
+   platform creates the branch environment on the fly, builds, and deploys.
+2. **Deploy a stage from the CLI**: `prisma deploy module.ts --stage pr-42`
+   creates a branch named `pr-42` and deploys the identical app graph into
+   it. A stage name must be a valid git ref name; an invalid name is a hard
+   error.
+
+A preview branch that needs a database gets a fresh, empty one, wired in as a
+branch-scoped `DATABASE_URL`. Preview work can never touch production data
+unless you explicitly point it there. Schema comes from your committed
+migrations; data does not follow from production.
+
+Preview lifecycle rules:
+
+1. Deleting the upstream git branch tears the whole environment down:
+   services, versions, and databases, including their data.
+2. An idle, unpinned preview branch can be reclaimed automatically. Pinning a
+   preview exempts it from idle reclamation, but not from teardown when its
+   git branch is deleted.
+3. The production branch is never reclaimed or torn down this way.
+
+## Two ways to deploy
+
+**GitHub (recommended).** Install the Prisma GitHub app and connect the
+repository: `prisma git connect`, or import the repository in the Console.
+From then on, every push builds and deploys on the platform. A push to the
+default branch deploys production; a push to any other branch creates or
+updates that branch's preview environment. No workflow file is required, and
+previews come free with every branch. Opening a pull request does not itself
+deploy anything; previews track branch pushes.
+
+**CLI.** `prisma deploy module.ts` deploys production directly; add
+`--stage <name>` for a preview. Authenticate once with `prisma auth login`
+(interactive), or set `PRISMA_SERVICE_TOKEN` (plus `PRISMA_WORKSPACE_ID`
+when the token can see more than one workspace) for CI and other headless
+runs. The first deploy creates the project, named after your module; the
+name must be unique in the workspace, and `--name` deploys under a different
+one.
+
+Both paths converge the same declaration, so they are mutually idempotent:
+a repo can be connected to GitHub and still be deployed from the CLI.
+
+## Services and versions
+
+A **service** is an HTTP app inside a branch, reachable at a stable URL.
+Every deploy of a service creates a new immutable **version**; exactly one
+version is live behind the stable URL at a time. Versions can be inspected,
+started, stopped, and deleted individually, and a version's logs can be read
+or followed; the `service` group covers all of it.
+
+Two movements between versions matter:
+
+1. **Promote** takes a version to production by rebuilding it with
+   production-class environment variables. A version built on a preview
+   branch never carries preview configuration into production.
+2. **Rollback** points production back at a previous version. A stopped
+   target is started and health-checked before traffic switches, so rollback
+   is zero-downtime.
+
+**Custom domains** attach to a service's production branch only. The
+workflow: add the domain, create the CNAME record the platform reports, and
+wait for DNS verification and certificate provisioning; a verification that
+failed on missing DNS is retried after the record exists.
+
+## The Compute runtime
+
+Services run on Bun, next to their Prisma Postgres database. There is no
+container image to author and no platform emulator to install locally.
+
+The runtime has no global `Temporal` (stock Node 24 lacks one too). Code
+that reads an ORM `DateTime` column compiles and deploys, then throws on
+the first read. Either add the `temporal-polyfill` dependency and
+`import 'temporal-polyfill/full/global'` at the service entry, or use the
+`*String` column types such as `TimestamptzString`.
+
+An idle service **sleeps**: the platform snapshots its memory after a short
+period of inactivity and resumes it from the snapshot on the next request.
+Request handling is unaffected, but background work outside the request
+lifecycle (`setTimeout`, `setInterval`, floating promises) can be
+interrupted mid-flight. The `@prisma/compute` package provides the two
+keep-awake primitives:
+
+1. `waitUntil(promise, { signal })` keeps the instance awake until the
+   promise settles.
+2. `using guard = new KeepAwakeGuard({ signal })` holds the instance awake
+   for a scope; call `.release()` in a `finally` block where `using` is
+   unavailable.
+
+Pass `AbortSignal.timeout(ms)` as a cost bound: the signal releases the
+guard, it does not cancel your work. Do not build schedulers on `setInterval`
+inside a service; sleeping makes them silently unreliable.
+
+## Prisma Postgres
+
+To your application, a Prisma Postgres database is a regular PostgreSQL
+database behind a connection string: any client works, including Prisma ORM,
+psql, Kysely, and Drizzle. On top of plain PostgreSQL each database has
+built-in connection pooling (no PgBouncer to run), optional query caching,
+and automated backups.
+
+Databases usually come from deploying a module that declares one. They can
+also be created directly, in which case the connection URL prints exactly
+once. Additional connection strings can be minted and rotated per database;
+every secret is shown exactly once at creation, and no later read reveals
+it. Backups are automated, listable, and restorable, and per-database usage
+metrics are queryable; the `postgres` group covers all of it.
+
+## Object storage
+
+Buckets are S3-compatible object stores that live inside the project,
+optionally associated with a branch (the project's default branch when
+omitted). A bucket cannot be renamed.
+
+Access keys are bucket-scoped credentials with a role of `read` or
+`read_write`. Creating one prints the access key id, secret, endpoint, and
+provider bucket name exactly once; a lost secret is revoked and re-created,
+never recovered. The `bucket` group manages both buckets and their keys.
+
+On Compute, Bun's built-in S3 client picks up `S3_ENDPOINT`, `S3_BUCKET`,
+`S3_ACCESS_KEY_ID`, and `S3_SECRET_ACCESS_KEY` from the environment, so a
+bucket declared in the module needs no client configuration. Locally, a
+Composer-declared bucket gets a local stand-in with the same S3 surface;
+code written against it runs unchanged on the platform.
+
+## Environment variables
+
+Configuration has two independent axes:
+
+| Axis | Values | Meaning |
+| --- | --- | --- |
+| Class | `production`, `preview` | Which branches resolve it: production-class values reach the production branch, preview-class values reach every preview |
+| Scope | project template, branch override | A template applies to all branches of its class; an override pins a value to one named preview branch |
+
+Rules that bite:
+
+1. Branch overrides exist only for the preview class. Production
+   configuration is always the project template; there is no way to give one
+   production deploy a special value.
+2. Values are write-only. Listing shows names and scopes, never values, and
+   no API returns them. To change a value you replace it.
+3. Variables resolve at deploy time from the branch's class. You never pass
+   environment variables as part of a deploy.
+4. Templates, per-branch overrides, and wholesale dotenv import are all
+   managed through the `project env` group.
+5. `DATABASE_URL` is managed for you when the module declares a database:
+   previews get their own fresh database's URL, production gets the
+   production database's. Only set it yourself for databases the platform
+   does not manage.
+
+## Local development
+
+The local stack is real, fast, and needs no cloud credentials. Prefer it
+over deploying whenever you want to show the user a change or verify your
+own work:
+
+1. Build the app exactly as you would for deploy, then run
+   `prisma dev module.ts`. It provisions a local Prisma Postgres database,
+   applies the schema, creates local stand-ins for declared buckets, starts
+   the services, and prints a local URL. It watches built output and
+   restarts a service when its build changes.
+2. Exercise the running app directly (for example with `curl` against the
+   printed URL) instead of reasoning about what the code would do.
+3. Stopping `dev` leaves local databases, buckets, and their data in place;
+   the next run is a warm start. `--fresh` wipes this app's local instances
+   and data first.
+4. Deploying is the same pipeline pointed at the platform: switching from
+   local to hosted is a configuration change, not a code change. Reach for
+   `prisma deploy --stage <name>` only when you need a shareable URL or
+   platform behaviour (sleeping, real DNS, production-like config).
+5. For pure frontend iteration the framework's own dev server also works;
+   the Composer local stack is what mirrors the deployed wiring.
+
+Windows is not supported for the local stack yet.
+
+## Failure modes quick reference
+
+1. **A secret you need was shown once and is gone.** By design: database
+   URLs, connection strings, and bucket keys print exactly once at creation.
+   Rotate or re-create; do not hunt for a read path, none exists.
+2. **Deploy refuses the module name.** Module names are workspace-unique.
+   Deploy under `--name <other>`, or delete the conflicting project.
+3. **A preview environment vanished.** Its git branch was deleted, or it
+   sat idle unpinned and was reclaimed. Push or deploy the branch again to
+   re-create it; the database starts empty again.
+4. **Background work never ran in production.** The service slept.
+   Wrap the work in `waitUntil` or a `KeepAwakeGuard`, or move it out of the
+   service.
+5. **A custom domain stays unverified.** The CNAME to the reported target
+   must exist first. Fix DNS, then retry the verification.
+6. **Production shows a stale value after an environment-variable change.**
+   Variables are resolved at deploy time. Re-deploy (or promote) so the new
+   value is picked up.
+7. **A stage name is rejected.** Stage names must be valid git ref names;
+   rename it.
+8. **A resource disappeared from the platform after a deploy.** It was
+   removed from `module.ts`; the module is the source of truth and deploy
+   converges to it. Restore the declaration and re-deploy.
+9. **`dev` or `deploy` rejects the app graph (`COMPOSE.GRAPH_INVALID`) over
+   a name.** Resource ids declared in the module (`provision()` ids,
+   `compute({ name })`) allow `[A-Za-z0-9]` only. A hyphenated id passes
+   authoring and typecheck, then fails here. Module and project names do
+   accept hyphens, so never derive a resource id from them.
+10. **A deployed service errors on its first timestamp read
+    (`RUNTIME.TEMPORAL_UNAVAILABLE`).** The runtime has no global
+    `Temporal`; see the Compute runtime section for the polyfill.
+
+## What the platform doesn't do yet
+
+Name the gap instead of inventing an API:
+
+1. **No branch create or delete from the CLI.** The `branch` group only
+   lists. Branches are created by pushing or by deploying a stage, and
+   removed by deleting the upstream git branch; there is no CLI teardown
+   verb for a stage yet.
+2. **No build retry.** A failed build is finished; the retry is the next
+   push or the next deploy.
+3. **No reading environment-variable values back**, anywhere. This is a
+   security stance, not a missing feature, but agents look for it often
+   enough to name here.
+4. **No bucket rename** and no bucket-to-branch re-association after
+   creation; re-create instead.
+
+For anything else missing, run the nearest group with `--help` before
+concluding it does not exist, and route requests with `prisma feedback`
+rather than guessing.
+
+## Related skills
+
+Everything inside the app is owned by the siblings: the data contract,
+queries, and migrations by `prisma-orm-core-concepts` (and
+`prisma-orm-migrations`), and the declaration of services, modules, wiring,
+and testing seams by `prisma-composer-core-concepts`. The skills install
+together via `prisma skills sync`; when a task crosses from platform
+resources into app code, switch skills instead of guessing.