From 87d83a2ddfb8d7312fa9fb3fbf1ad57a7eab7688 Mon Sep 17 00:00:00 2001 From: Steven McClankerton Date: Fri, 13 Nov 2026 17:41:10 +0000 Subject: [PATCH] End every Prisma 7 command and flag error with how to install and run Prisma 7's CLI v7Command and v7Flag append "To keep using Prisma 7, install its CLI with `npm install --save-dev @prisma/prisma7@7` and run `prisma7 `." to each entry's why. The invocation is the Prisma 7 path, or the command plus the kebab-case flag, followed by a placeholder for every value or argument Prisma 7 requires there, such as `prisma7 complete ` and `prisma7 init --url `. The platform status reason now says that no command reports whether Prisma Data Platform services are up. The tests assert the full why for every entry, and the error reference describes the sentence for CLI.V7_COMMAND and CLI.V7_FLAG. Co-Authored-By: Claude Opus 5.5 --- docs/reference/error-reference.md | 4 +- packages/cli/src/v7-redirects.ts | 55 ++++++++++++++++----- packages/cli/tests/v7-redirects.test.ts | 65 +++++++++++++++++++++++-- 3 files changed, 104 insertions(+), 20 deletions(-) diff --git a/docs/reference/error-reference.md b/docs/reference/error-reference.md index c33fe74d..9c2379d8 100644 --- a/docs/reference/error-reference.md +++ b/docs/reference/error-reference.md @@ -250,11 +250,11 @@ The typed path routed to no command (stricli's route failure, mapped at the adap ### CLI.V7_COMMAND -The user typed a Prisma 7 command path that Prisma 8 does not have, such as `prisma bootstrap` or `prisma postgres link`; instead of failing as unknown, the redirect table settles it with the summary "`prisma ` is a Prisma 7 command and is not available in Prisma 8". `why` says what the suggested Prisma 8 commands do and what they do not cover. Next actions, in order: the replacement commands as run-command actions (labelled "Use the replacement" for one, "Step 1", "Step 2", … for several), a run-command pointing at the suggested command's `--help`, and an open-url action to the CLI docs when Prisma 8 has no equivalent. Each command family declares the Prisma 7 paths that relate to its own commands. Exits 2. Meta: none. +The user typed a Prisma 7 command path that Prisma 8 does not have, such as `prisma bootstrap` or `prisma postgres link`; instead of failing as unknown, the redirect table settles it with the summary "`prisma ` is a Prisma 7 command and is not available in Prisma 8". `why` says what the suggested Prisma 8 commands do and what they do not cover, and ends with how to install and run Prisma 7's CLI: "To keep using Prisma 7, install its CLI with `npm install --save-dev @prisma/prisma7@7` and run `prisma7 `." The `prisma7` command line in that sentence has a placeholder for every argument Prisma 7 requires, such as `prisma7 complete `. Next actions, in order: the replacement commands as run-command actions (labelled "Use the replacement" for one, "Step 1", "Step 2", … for several), a run-command pointing at the suggested command's `--help`, and an open-url action to the CLI docs when Prisma 8 has no equivalent. Each command family declares the Prisma 7 paths that relate to its own commands. Exits 2. Meta: none. ### CLI.V7_FLAG -The user passed a Prisma 7 flag that the same-named Prisma 8 command does not accept, such as `--datasource-provider` on `prisma init`; instead of failing as an unknown flag, the redirect table settles it with the summary "`--` on `prisma ` is a Prisma 7 flag and is not available in Prisma 8". `why` and the next actions follow `CLI.V7_COMMAND`. Exits 2. Meta: none. +The user passed a Prisma 7 flag that the same-named Prisma 8 command does not accept, such as `--datasource-provider` on `prisma init`; instead of failing as an unknown flag, the redirect table settles it with the summary "`--` on `prisma ` is a Prisma 7 flag and is not available in Prisma 8". `why` and the next actions follow `CLI.V7_COMMAND`; the closing install sentence names `prisma7 --`, plus a placeholder when the flag takes a value, such as `prisma7 init --db` or `prisma7 init --url `. Exits 2. Meta: none. ## CONFIG diff --git a/packages/cli/src/v7-redirects.ts b/packages/cli/src/v7-redirects.ts index 3b710838..02be6199 100644 --- a/packages/cli/src/v7-redirects.ts +++ b/packages/cli/src/v7-redirects.ts @@ -5,43 +5,70 @@ import { } from "@prisma/cli-engine"; import { CLI_DOCS_URL } from "./cli-name"; +type V7Entry = Omit & { + readonly reason: string; + readonly placeholder?: string; +}; + +function kebabCase(flag: string): string { + return flag.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`); +} + +function withPrisma7Install(reason: string, invocation: string): string { + return `${reason} To keep using Prisma 7, install its CLI with \`npm install --save-dev @prisma/prisma7@7\` and run \`prisma7 ${invocation}\`.`; +} + +function withPlaceholder(invocation: string, placeholder?: string): string { + return placeholder === undefined + ? invocation + : `${invocation} ${placeholder}`; +} + function v7Command( from: string, - entry: Omit, + { placeholder, ...entry }: V7Entry, ): RedirectSpec { return { from, code: "CLI.V7_COMMAND", summary: `\`{bin} ${from}\` is a Prisma 7 command and is not available in Prisma 8`, ...entry, + reason: withPrisma7Install( + entry.reason, + withPlaceholder(from, placeholder), + ), }; } function v7Flag( command: string, flag: string, - entry: Omit, + { placeholder, ...entry }: V7Entry, ): RedirectSpec { return { from: command, flag, code: "CLI.V7_FLAG", - summary: `\`--${flag.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}\` on \`{bin} ${command}\` is a Prisma 7 flag and is not available in Prisma 8`, + summary: `\`--${kebabCase(flag)}\` on \`{bin} ${command}\` is a Prisma 7 flag and is not available in Prisma 8`, ...entry, + reason: withPrisma7Install( + entry.reason, + withPlaceholder(`${command} --${kebabCase(flag)}`, placeholder), + ), }; } const INIT_SCHEMA_REASON = "`init` prepares this repository for Prisma: it writes prisma.config.ts, adds prisma as a dev dependency and installs the AI-agent skills. It sets up no database schema or client; `orm init` does that."; -const INIT_SCHEMA_FLAGS: readonly string[] = [ - "datasourceProvider", - "generatorProvider", - "previewFeature", - "output", - "url", - "withModel", -]; +const INIT_SCHEMA_FLAGS: Readonly> = { + datasourceProvider: "", + generatorProvider: "", + previewFeature: "", + output: "", + url: "", + withModel: undefined, +}; export const v7CommandFamily: CommandFamily = defineCommandFamily({ commands: {}, @@ -71,6 +98,7 @@ export const v7CommandFamily: CommandFamily = defineCommandFamily({ "No command starts an MCP (Model Context Protocol) server for AI tools.", }), v7Command("complete", { + placeholder: "", docsUrl: CLI_DOCS_URL, reason: "This CLI has no shell completion: no command prints or installs a completion script for your shell.", @@ -78,7 +106,7 @@ export const v7CommandFamily: CommandFamily = defineCommandFamily({ v7Command("platform status", { docsUrl: CLI_DOCS_URL, reason: - "No command reports the status of your Prisma Platform account. The docs list the commands that inspect workspaces, Projects and databases.", + "No command reports whether Prisma Data Platform services are up.", }), v7Command("postgres link", { replacement: [ @@ -101,11 +129,12 @@ export const v7CommandFamily: CommandFamily = defineCommandFamily({ reason: "`--skills=none` skips installing the AI-agent skills and records in prisma.config.ts that none are wanted, so later installs do not add them.", }), - ...INIT_SCHEMA_FLAGS.map((flag) => + ...Object.entries(INIT_SCHEMA_FLAGS).map(([flag, placeholder]) => v7Flag("init", flag, { replacement: "{bin} orm init", help: "orm init", reason: INIT_SCHEMA_REASON, + placeholder, }), ), ], diff --git a/packages/cli/tests/v7-redirects.test.ts b/packages/cli/tests/v7-redirects.test.ts index 9697f6bb..b7890f55 100644 --- a/packages/cli/tests/v7-redirects.test.ts +++ b/packages/cli/tests/v7-redirects.test.ts @@ -13,7 +13,10 @@ const UPPERCASE_LETTER = /[A-Z]/g; const WHY_LINE = /^ {2}why: /; const WHITESPACE = /\s+/; const PRISMA_7 = /Prisma 7|prisma@7/; -const PRISMA_7_PACKAGE = /prisma@7/; +const PRISMA_7_PACKAGE = /prisma@7|prisma7/; +const INSTALL_SENTENCE = + / To keep using Prisma 7, install its CLI with `npm install --save-dev @prisma\/prisma7@7` and run `prisma7 [^`]+`\.$/; +const NPX = /\bnpx\b/; function makeProcess(argv: readonly string[], stdoutIsTty: boolean) { const proc = { @@ -132,6 +135,55 @@ const INIT_FLAGS: Readonly> = { ], }; +function install(invocation: string): string { + return ` To keep using Prisma 7, install its CLI with \`npm install --save-dev @prisma/prisma7@7\` and run \`prisma7 ${invocation}\`.`; +} + +const PATH_WHY: Readonly> = { + bootstrap: + "Setting up a new app takes two commands: `project create` creates a Project, the container for one app's databases and services, and links this directory to it; `postgres create` then adds a Prisma Postgres database to that Project and prints its connection URL once, without writing it to a .env file. Neither sets up a database schema or the code your app queries the database with; `orm init` does that." + + install("bootstrap"), + version: + "`--version` prints only this CLI's version number. It does not report Node.js, operating system or engine details." + + install("version"), + debug: + "No command prints debugging information about this CLI and its environment." + + install("debug"), + mcp: + "No command starts an MCP (Model Context Protocol) server for AI tools." + + install("mcp"), + complete: + "This CLI has no shell completion: no command prints or installs a completion script for your shell." + + install("complete "), + "platform status": + "No command reports whether Prisma Data Platform services are up." + + install("platform status"), + "postgres link": + "Linking and connecting are two commands: `project link` points this directory at an existing Project, so commands run here act on it; `postgres connection create` creates a connection URL for one of its databases. The URL prints once, in that command's output; nothing writes it to a .env file." + + install("postgres link"), +}; + +const INIT_SCHEMA_WHY = + "`init` prepares this repository for Prisma: it writes prisma.config.ts, adds prisma as a dev dependency and installs the AI-agent skills. It sets up no database schema or client; `orm init` does that."; + +const INIT_FLAG_WHY: Readonly> = { + db: + "`init` creates no database. `postgres create` creates a Prisma Postgres database in the Project this directory is linked to." + + install("init --db"), + "datasource-provider": + INIT_SCHEMA_WHY + install("init --datasource-provider "), + "generator-provider": + INIT_SCHEMA_WHY + install("init --generator-provider "), + "preview-feature": + INIT_SCHEMA_WHY + install("init --preview-feature "), + output: INIT_SCHEMA_WHY + install("init --output "), + url: INIT_SCHEMA_WHY + install("init --url "), + "with-model": INIT_SCHEMA_WHY + install("init --with-model"), + "no-skills": + "`--skills=none` skips installing the AI-agent skills and records in prisma.config.ts that none are wanted, so later installs do not add them." + + install("init --no-skills"), +}; + function humanLine(action: NextAction): string { return `→ ${action.label}: ${action.command ?? action.url}`; } @@ -158,7 +210,7 @@ describe("v7 command paths the shell owns", () => { expect(envelope.error.summary).toBe( `\`prisma ${path}\` is a Prisma 7 command and is not available in Prisma 8`, ); - expect(envelope.error.why).toEqual(expect.any(String)); + expect(envelope.error.why).toBe(PATH_WHY[path]); expect(envelope.nextActions).toEqual(nextActions); expect(envelope.error.nextActions).toEqual(nextActions); }); @@ -209,7 +261,7 @@ describe("v7 flags on the shell's init", () => { expect(envelope.error.summary).toBe( `\`--${flag}\` on \`prisma init\` is a Prisma 7 flag and is not available in Prisma 8`, ); - expect(envelope.error.why).toEqual(expect.any(String)); + expect(envelope.error.why).toBe(INIT_FLAG_WHY[flag]); expect(envelope.nextActions).toEqual(nextActions); }); @@ -264,9 +316,12 @@ describe("every suggestion names a mounted command", () => { expect(Object.keys(mountedCommands)).toContain(suggestedPath(suggestion)); }); - it("no entry mentions Prisma 7 outside its summary", () => { + it("no entry mentions Prisma 7 outside its summary and install sentence", () => { for (const redirect of v7CommandFamily.redirects) { - expect(redirect.reason).not.toMatch(PRISMA_7); + const stripped = redirect.reason?.replace(INSTALL_SENTENCE, ""); + expect(stripped).not.toMatch(PRISMA_7); + expect(stripped).not.toMatch(PRISMA_7_PACKAGE); + expect(redirect.reason).not.toMatch(NPX); for (const suggestion of redirect.replacement) { expect(suggestion).not.toMatch(PRISMA_7_PACKAGE); }