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); }