create-prisma 0.4.2-next.37.82.1 → 0.4.2-next.37.84.1

package/README.md

@@ -14,7 +14,7 @@ Scaffold a new app with Prisma Next already wired up.
 - adds `contract:emit`, `db:init`, `db:update`, `db:verify`, `db:seed`, `migration:plan`, `migration:apply`, `migration:status`, and `migration:show` scripts
 - adds `db:up` / `db:down` and `docker-compose.yml` for default MongoDB projects
 - creates or updates `.env` with `DATABASE_URL`
-- writes `.env.example`, `prisma-next.md`, and `.agents/skills/prisma-next/SKILL.md`
+- writes `.env.example`, appends a Prisma Next reference to `README.md`, and scaffolds `.agents/skills/prisma-next/SKILL.md`
 - can install dependencies and run `prisma-next contract emit`
 
 `db:init`, migrations, and seeding are never run automatically. PostgreSQL projects show

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import "./create-BpEvye82.mjs";
+import "./create-Bn4nsBxN.mjs";
 import { createCreatePrismaCli } from "./index.mjs";
 
 //#region src/cli.ts

package/dist/{create-BpEvye82.mjs → create-Bn4nsBxN.mjs}

@@ -40,7 +40,7 @@ async function getAnonymousId() {
 }
 function getCommonProperties() {
 	return {
-		"cli-version": "0.4.2-next.37.82.1",
+		"cli-version": "0.4.2-next.37.84.1",
 		"node-version": process.version,
 		platform: process.platform,
 		arch: process.arch
@@ -867,6 +867,7 @@ const minimumServerVersion = {
 	postgres: "14",
 	mongo: "6.0"
 };
+const readmeSectionMarker = "<!-- prisma-next-reference -->";
 const requiredPrismaFileGroups = [
 	[
 		"prisma/contract.prisma",
@@ -910,6 +911,18 @@ async function writeFileIfMissing(filePath, content) {
 	if (await fs.pathExists(filePath)) return;
 	await fs.outputFile(filePath, content.endsWith("\n") ? content : `${content}\n`, "utf8");
 }
+async function appendReadmeSectionIfMissing(projectDir, content) {
+	const readmePath = path.join(projectDir, "README.md");
+	const section = `${readmeSectionMarker}\n${content.trim()}\n`;
+	if (!await fs.pathExists(readmePath)) {
+		await fs.outputFile(readmePath, `# Prisma Next\n\n${section}`, "utf8");
+		return;
+	}
+	const existingContent = await fs.readFile(readmePath, "utf8");
+	if (existingContent.includes(readmeSectionMarker)) return;
+	const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+	await fs.writeFile(readmePath, `${existingContent}${separator}${section}`, "utf8");
+}
 function getEnvExampleContent(provider) {
 	const label = getDatabaseLabel(provider);
 	const minVersion = minimumServerVersion[provider];
@@ -924,7 +937,7 @@ function getEnvExampleContent(provider) {
 function formatCommandListItem(packageManager, scriptName, description) {
 	return `- \`${getRunScriptCommand(packageManager, scriptName)}\` - ${description}`;
 }
-function getPrismaNextQuickReferenceContent(options) {
+function getPrismaNextReadmeSectionContent(options) {
 	const { provider, authoring, schemaPreset, packageManager, schemaPath, dbImportPath, scripts, rootScripts } = options;
 	const label = getDatabaseLabel(provider);
 	const minVersion = minimumServerVersion[provider];
@@ -947,12 +960,12 @@ function getPrismaNextQuickReferenceContent(options) {
 		"2. Run `contract:emit` after editing the contract.",
 		"3. Run `migration:plan` and review the generated migration.",
 		"4. Run `migration:apply` to apply pending migrations.",
-		"5. Run `db:seed` if you want the starter sample data."
+		...schemaPreset === "basic" ? ["5. Run `db:seed` if you want the starter sample data."] : []
 	] : [
 		"1. Run `contract:emit` after editing the contract.",
 		"2. For first-time setup, run `db:init` to create and sign the database state.",
 		"3. For later contract changes, run `migration:plan` and `migration:apply`.",
-		"4. Run `db:seed` if you want the starter sample data."
+		...schemaPreset === "basic" ? ["4. Run `db:seed` if you want the starter sample data."] : []
 	];
 	const queryExample = provider === "mongo" ? [
 		"```ts",
@@ -974,7 +987,7 @@ function getPrismaNextQuickReferenceContent(options) {
 		"PostgreSQL models use their contract model names, so the starter `User` model is queried through `db.orm.User`. Prefer `db.orm` for application queries and use raw SQL only when the ORM does not cover the operation."
 	];
 	return [
-		"# Prisma Next",
+		"## Prisma Next Reference",
 		"",
 		`This project uses Prisma Next with ${label}. The contract is authored in ${authoring === "typescript" ? "TypeScript" : "PSL"} at \`${schemaPath}\`.`,
 		"",
@@ -1010,6 +1023,8 @@ function getPrismaNextQuickReferenceContent(options) {
 function getPrismaNextAgentSkillContent(options) {
 	const { provider, authoring, schemaPreset, packageManager, schemaPath, dbImportPath, scripts, rootScripts } = options;
 	const label = getDatabaseLabel(provider);
+	const runtimePackage = provider === "mongo" ? "@prisma-next/mongo" : "@prisma-next/postgres";
+	const descriptionDetails = provider === "mongo" ? "MongoDB queries, DATABASE_URL, db init/update/verify, migrations, seeding, local MongoDB Docker setup, replica sets, typed aggregations, or mongoClient escape hatches." : "PostgreSQL queries, DATABASE_URL, db init/update/verify, migrations, seeding, PostgreSQL setup, or raw SQL escape hatches.";
 	const hasWorkspaceRootDbUp = typeof scripts["db:up"] !== "string" && typeof rootScripts["db:up"] === "string";
 	const hasDbUp = typeof scripts["db:up"] === "string" || hasWorkspaceRootDbUp;
 	const commands = [
@@ -1025,40 +1040,87 @@ function getPrismaNextAgentSkillContent(options) {
 		...schemaPreset === "basic" ? [formatCommandListItem(packageManager, "db:seed", "insert starter sample data")] : []
 	];
 	const queryGuidance = provider === "mongo" ? [
-		"- Use `db.orm.users` / `db.orm.posts`; Mongo accessors follow emitted collection names.",
-		"- `.all()` returns an async iterable result, so `for await` is always safe.",
-		"- Use `db.query` for typed aggregation pipelines.",
-		"- The Mongo client connects lazily; scripts should call `await db.close()` in `finally`.",
-		"- Local MongoDB should run as a replica set for migration workflows."
+		"- Use `db.orm`. Mongo root accessors are lowercased plural collection names emitted by `contract:emit`, for example `db.orm.users` and `db.orm.posts`.",
+		"- `.all()` returns an async iterable result. Consume it with `for await` or await it to materialize an array.",
+		"- Use `db.query` for typed aggregation pipelines when the ORM cannot express a query.",
+		"- For direct MongoDB driver control, construct your own `MongoClient` and pass it through the `mongoClient` binding; keep that raw client reference for sessions, transactions, and change streams.",
+		"- Do not use `db.runtime()` as a raw driver escape hatch. It returns Prisma Next's internal executor, not a `mongodb` `MongoClient` or `Db`.",
+		"- The Mongo client connects lazily on the first query. Short-lived scripts should call `await db.close()` in `finally`.",
+		"- Multi-document transactions and change streams require MongoDB to run as a replica set. The generated local Docker setup does this."
 	] : [
-		"- Use `db.orm.User` / `db.orm.Post`; PostgreSQL accessors follow contract model names.",
-		"- Prefer `db.orm` for application queries.",
-		"- Use raw SQL only when the ORM cannot express the operation.",
-		"- Close script runtimes with `await db.runtime().close()` when needed."
+		"- Use `db.orm`. PostgreSQL root accessors follow contract model names, for example `db.orm.User` and `db.orm.Post`.",
+		"- Prefer `db.orm` for application queries. Use raw SQL only when the ORM cannot express the operation or the user explicitly asks for it.",
+		"- `.where(...)`, `.select(...)`, `.orderBy(...)`, `.take(...)`, `.all()`, `.first()`, and `.include(...)` are the primary ORM query methods.",
+		"- Short-lived scripts should close the runtime with `await db.runtime().close()` when needed."
 	];
-	return [
-		"# Prisma Next Project Skill",
+	const queryExamples = provider === "mongo" ? [
+		"```ts",
+		`import { db } from "${dbImportPath}";`,
 		"",
-		`This project uses Prisma Next with ${label}. The contract is \`${schemaPath}\` using ${authoring === "typescript" ? "TypeScript" : "PSL"} authoring.`,
+		"const user = await db.orm.users.where({ email: \"alice@example.com\" }).first();",
 		"",
-		"## Files",
+		"for await (const user of db.orm.users.select(\"_id\", \"email\").take(10).all()) {",
+		"  console.log(user.email);",
+		"}",
 		"",
-		`- Contract: \`${schemaPath}\``,
-		"- Config: `prisma-next.config.ts`",
-		`- Database helper: import \`db\` from \`${dbImportPath}\``,
-		"- Generated files: `prisma/contract.json` and `prisma/contract.d.ts`",
+		"const usersWithPosts = await db.orm.users",
+		"  .select(\"_id\", \"email\")",
+		"  .include(\"posts\")",
+		"  .take(10)",
+		"  .all();",
+		"```"
+	] : [
+		"```ts",
+		`import { db } from "${dbImportPath}";`,
 		"",
-		"## Rules",
+		"const user = await db.orm.User",
+		"  .where((user) => user.email.eq(\"alice@example.com\"))",
+		"  .first();",
 		"",
-		"- Never edit generated contract artifacts by hand.",
-		"- Run `contract:emit` after contract edits before relying on new types.",
-		"- Do not auto-run `db:init`, migrations, or seed commands.",
-		...queryGuidance,
+		"const users = await db.orm.User.select(\"id\", \"email\").take(10).all();",
+		"",
+		"const usersWithPosts = await db.orm.User",
+		"  .select(\"id\", \"email\")",
+		"  .include(\"posts\", (post) => post.select(\"id\", \"title\").take(5))",
+		"  .take(10)",
+		"  .all();",
+		"```"
+	];
+	return [
+		"---",
+		"name: prisma-next",
+		"description: >-",
+		`  Prisma Next project workflow for this generated ${label} app. Use whenever working in this repository on Prisma Next contracts, generated contract artifacts, database helpers, ${descriptionDetails}`,
+		"---",
+		"",
+		"# Prisma Next - Project Skill",
+		"",
+		`This project uses **Prisma Next** with **${label}** via \`${runtimePackage}\`. The contract is \`${schemaPath}\` using ${authoring === "typescript" ? "TypeScript" : "PSL"} authoring.`,
+		"",
+		"## Files",
+		"",
+		`- **Contract**: \`${schemaPath}\` - edit this to add or change models.`,
+		"- **Config**: `prisma-next.config.ts` - tells the CLI where the contract is and how to connect to the database.",
+		`- **Database helper**: import \`db\` from \`${dbImportPath}\`. This is the entry point for queries.`,
+		"- **Generated files**: `prisma/contract.json` and `prisma/contract.d.ts`. Do not edit these by hand.",
 		"",
 		"## Commands",
 		"",
 		...commands,
 		"",
+		"## How To Write Queries",
+		"",
+		...queryExamples,
+		"",
+		"## Rules",
+		"",
+		"- Never hand-edit `contract.json` or `contract.d.ts`. Regenerate them with `contract:emit`.",
+		"- Always run `contract:emit` after changing the contract before writing code that depends on the changed models.",
+		"- Do not auto-run `db:init`, migrations, or seed commands. These are manual project-owner actions.",
+		"- Do not restructure the generated database helper unless the user explicitly asks.",
+		"- `DATABASE_URL` lives in `.env`; `.env.example` documents the expected shape and minimum server version.",
+		...queryGuidance,
+		"",
 		"## Common Workflow",
 		"",
 		"- Edit the contract.",
@@ -1082,7 +1144,7 @@ async function writePrismaNextProjectDocs(options) {
 	const scripts = await readPackageScripts(prismaProjectDir);
 	const rootScripts = await readPackageScripts(options.projectDir);
 	await writeFileIfMissing(path.join(prismaProjectDir, ".env.example"), getEnvExampleContent(options.provider));
-	await writeFileIfMissing(path.join(prismaProjectDir, "prisma-next.md"), getPrismaNextQuickReferenceContent({
+	await appendReadmeSectionIfMissing(prismaProjectDir, getPrismaNextReadmeSectionContent({
 		provider: options.provider,
 		authoring: options.authoring,
 		schemaPreset: options.schemaPreset,

package/dist/index.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { a as DatabaseProviderSchema, c as SchemaPresetSchema, i as CreateTemplateSchema, n as AuthoringStyleSchema, o as DatabaseUrlSchema, r as CreateCommandInputSchema, s as PackageManagerSchema, t as runCreateCommand } from "./create-BpEvye82.mjs";
+import { a as DatabaseProviderSchema, c as SchemaPresetSchema, i as CreateTemplateSchema, n as AuthoringStyleSchema, o as DatabaseUrlSchema, r as CreateCommandInputSchema, s as PackageManagerSchema, t as runCreateCommand } from "./create-Bn4nsBxN.mjs";
 import { os } from "@orpc/server";
 import { createCli } from "trpc-cli";
 
 //#region src/index.ts
-const CLI_VERSION = "0.4.2-next.37.82.1";
+const CLI_VERSION = "0.4.2-next.37.84.1";
 const router = os.router({ create: os.meta({
 	description: "Create a new project with Prisma setup",
 	default: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-prisma",
-  "version": "0.4.2-next.37.82.1",
+  "version": "0.4.2-next.37.84.1",
   "private": false,
   "description": "Create Prisma Next projects with first-party templates and great DX.",
   "homepage": "https://github.com/prisma/create-prisma",

package/templates/create/astro/README.md.hbs

@@ -36,7 +36,7 @@ Database helper scripts are added to `package.json`:
 - `{{runScriptCommand packageManager "db:seed"}}` - insert sample users manually
 {{/if}}
 
-See `prisma-next.md` and `.agents/skills/prisma-next/SKILL.md` for provider-specific Prisma Next workflow notes.
+This README includes provider-specific Prisma Next reference notes below. Agent-specific project guidance is scaffolded in `.agents/skills/prisma-next/SKILL.md`.
 
 Node-based Prisma Next projects expect Node.js 24 LTS or newer.
 {{#if (eq schemaPreset "basic")}}

package/templates/create/elysia/README.md.hbs

@@ -34,7 +34,7 @@ Database helper scripts are added to `package.json`:
 - `{{runScriptCommand packageManager "db:seed"}}` - insert sample users manually
 {{/if}}
 
-See `prisma-next.md` and `.agents/skills/prisma-next/SKILL.md` for provider-specific Prisma Next workflow notes.
+This README includes provider-specific Prisma Next reference notes below. Agent-specific project guidance is scaffolded in `.agents/skills/prisma-next/SKILL.md`.
 
 Node-based Prisma Next projects expect Node.js 24 LTS or newer.
 {{#if (eq schemaPreset "basic")}}

package/templates/create/hono/README.md.hbs

@@ -34,7 +34,7 @@ Database helper scripts are added to `package.json`:
 - `{{runScriptCommand packageManager "db:seed"}}` - insert sample users manually
 {{/if}}
 
-See `prisma-next.md` and `.agents/skills/prisma-next/SKILL.md` for provider-specific Prisma Next workflow notes.
+This README includes provider-specific Prisma Next reference notes below. Agent-specific project guidance is scaffolded in `.agents/skills/prisma-next/SKILL.md`.
 
 Node-based Prisma Next projects expect Node.js 24 LTS or newer.
 {{#if (eq schemaPreset "basic")}}

package/templates/create/nest/README.md.hbs

@@ -35,7 +35,7 @@ Database helper scripts are added to `package.json`:
 - `{{runScriptCommand packageManager "db:seed"}}` - insert sample users manually
 {{/if}}
 
-See `prisma-next.md` and `.agents/skills/prisma-next/SKILL.md` for provider-specific Prisma Next workflow notes.
+This README includes provider-specific Prisma Next reference notes below. Agent-specific project guidance is scaffolded in `.agents/skills/prisma-next/SKILL.md`.
 
 Node-based Prisma Next projects expect Node.js 24 LTS or newer.
 {{#if (eq schemaPreset "basic")}}

package/templates/create/next/README.md.hbs

@@ -34,7 +34,7 @@ Database helper scripts are added to `package.json`:
 - `{{runScriptCommand packageManager "db:seed"}}` - insert sample users manually
 {{/if}}
 
-See `prisma-next.md` and `.agents/skills/prisma-next/SKILL.md` for provider-specific Prisma Next workflow notes.
+This README includes provider-specific Prisma Next reference notes below. Agent-specific project guidance is scaffolded in `.agents/skills/prisma-next/SKILL.md`.
 
 Node-based Prisma Next projects expect Node.js 24 LTS or newer.
 {{#if (eq schemaPreset "basic")}}

package/templates/create/nuxt/README.md.hbs

@@ -36,7 +36,7 @@ Database helper scripts are added to `package.json`:
 - `{{runScriptCommand packageManager "db:seed"}}` - insert sample users manually
 {{/if}}
 
-See `prisma-next.md` and `.agents/skills/prisma-next/SKILL.md` for provider-specific Prisma Next workflow notes.
+This README includes provider-specific Prisma Next reference notes below. Agent-specific project guidance is scaffolded in `.agents/skills/prisma-next/SKILL.md`.
 
 Node-based Prisma Next projects expect Node.js 24 LTS or newer.
 {{#if (eq schemaPreset "basic")}}

package/templates/create/svelte/README.md.hbs

@@ -35,7 +35,7 @@ Database helper scripts are added to `package.json`:
 - `{{runScriptCommand packageManager "db:seed"}}` - insert sample users manually
 {{/if}}
 
-See `prisma-next.md` and `.agents/skills/prisma-next/SKILL.md` for provider-specific Prisma Next workflow notes.
+This README includes provider-specific Prisma Next reference notes below. Agent-specific project guidance is scaffolded in `.agents/skills/prisma-next/SKILL.md`.
 
 Node-based Prisma Next projects expect Node.js 24 LTS or newer.
 {{#if (eq schemaPreset "basic")}}

package/templates/create/tanstack-start/README.md.hbs

@@ -35,7 +35,7 @@ Database helper scripts are added to `package.json`:
 - `{{runScriptCommand packageManager "db:seed"}}` - insert sample users manually
 {{/if}}
 
-See `prisma-next.md` and `.agents/skills/prisma-next/SKILL.md` for provider-specific Prisma Next workflow notes.
+This README includes provider-specific Prisma Next reference notes below. Agent-specific project guidance is scaffolded in `.agents/skills/prisma-next/SKILL.md`.
 
 Node-based Prisma Next projects expect Node.js 24 LTS or newer.
 {{#if (eq schemaPreset "basic")}}

package/templates/create/turborepo/README.md.hbs

@@ -27,7 +27,7 @@ Generated by `create-prisma` with the Turborepo template.
 - `{{runScriptCommand packageManager "db:seed"}}` - insert sample users manually in `packages/db`
 {{/if}}
 
-See `packages/db/prisma-next.md` and `packages/db/.agents/skills/prisma-next/SKILL.md` for provider-specific Prisma Next workflow notes.
+See `packages/db/README.md` for provider-specific Prisma Next reference notes. Agent-specific project guidance is scaffolded in `packages/db/.agents/skills/prisma-next/SKILL.md`.
 
 ## Prisma Next