Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/reference/error-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,6 +248,14 @@ The `prisma telemetry status|enable|disable` commands could not resolve the user

The typed path routed to no command (stricli's route failure, mapped at the adapter boundary) and no redirect claims it; next actions carry up to three "did you mean" suggestions ranked by edit distance over command paths and their prefixes, plus a pointer to `--help`. Exits 2. Meta: none.

### 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 <path>` 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.

### 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 "`--<flag>` on `prisma <command>` 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.

## CONFIG

These codes come from Composer, the command family behind `prisma dev` and `prisma deploy`. They report a problem with the `composer` section of `prisma.config.ts`, or with what its `config` and `secrets` adapters return, and are raised before Composer starts the app.
Expand Down
2 changes: 1 addition & 1 deletion packages/cli-engine/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@prisma/cli-engine",
"version": "0.9.0",
"version": "0.10.0",
"description": "The execution engine of the unified Prisma CLI.",
"type": "module",
"exports": {
Expand Down
40 changes: 28 additions & 12 deletions packages/cli-engine/src/command-family.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,9 @@ import type { AnyCommand } from "./commands";
import type { ConfigSection } from "./config-section";

/**
* A retired invocation and the invocation that replaced it. Redirects
* are metadata, never commands: they stay out of help and out of the
* command tree, and are consulted only when an invocation fails to
* resolve.
* A retired invocation. Redirects are metadata, never commands: they
* stay out of help and out of the command tree, and are consulted only
* when an invocation fails to resolve.
*/
export interface RedirectSpec {
/**
Expand All @@ -21,22 +20,25 @@ export interface RedirectSpec {
* (rendered --kebab-case, as flag declarations are).
*/
readonly flag?: string;
/**
* The replacement invocation, written the way help examples are
* written: no binary name, `{bin}` available when the name has to sit
* mid-string. Placeholder arguments use angle brackets (`<ref>`).
*/
readonly replacement: string;
readonly replacement?: string | readonly string[];
/** One sentence of context, surfaced as the error's `why`. */
readonly reason?: string;
readonly code?: `${string}.${string}`;
readonly summary?: string;
readonly help?: string;
readonly docsUrl?: string;
}

/** The normalized redirect a command family carries. */
export interface CommandRedirect {
readonly from: string;
readonly flag: string | undefined;
readonly replacement: string;
readonly replacement: readonly string[];
readonly reason: string | undefined;
readonly code: `${string}.${string}` | undefined;
readonly summary: string | undefined;
readonly help: string | undefined;
readonly docsUrl: string | undefined;
}

/**
Expand Down Expand Up @@ -64,12 +66,26 @@ function normalizePath(from: string): string {
return from.trim().replace(/\s+/g, " ");
}

function replacementSteps(replacement: RedirectSpec["replacement"]): string[] {
if (replacement === undefined) {
return [];
}
if (typeof replacement === "string") {
return [replacement];
}
return [...replacement];
}

function normalizeRedirect(spec: RedirectSpec): CommandRedirect {
return Object.freeze({
from: normalizePath(spec.from),
flag: spec.flag,
replacement: spec.replacement,
replacement: Object.freeze(replacementSteps(spec.replacement)),
reason: spec.reason,
code: spec.code,
summary: spec.summary,
help: spec.help,
docsUrl: spec.docsUrl,
});
}

Expand Down
15 changes: 15 additions & 0 deletions packages/cli-engine/src/execution/command-tree.ts
Original file line number Diff line number Diff line change
Expand Up @@ -392,6 +392,12 @@ function addFlagRedirect(
table.set(key, redirect);
}

function describeRedirect(redirect: CommandRedirect): string {
return redirect.flag === undefined
? `redirect '${redirect.from}'`
: `redirect for flag '${redirect.flag}' on '${redirect.from}'`;
}

export function buildRedirectTable(spec: EngineSpec): RedirectTable {
const byPath = new Map<string, CommandRedirect>();
const byFlag = new Map<string, CommandRedirect>();
Expand All @@ -402,6 +408,15 @@ export function buildRedirectTable(spec: EngineSpec): RedirectTable {
"redirect declares an empty path, so no invocation can produce it",
);
}
if (
redirect.replacement.length === 0 &&
redirect.help === undefined &&
redirect.docsUrl === undefined
) {
throw constructionError(
`${describeRedirect(redirect)} names no replacement, help, or docs URL, so it gives the user nowhere to go`,
);
}
if (redirect.flag === undefined) {
addVerbRedirect(spec, byPath, redirect);
} else {
Expand Down
4 changes: 1 addition & 3 deletions packages/cli-engine/src/execution/engine.ts
Original file line number Diff line number Diff line change
Expand Up @@ -567,9 +567,7 @@ export class EngineImpl implements Engine {
: undefined;
}

/** stricli routed or parsed nothing runnable. When the redirect table
* claims the invocation the user typed, the run names its
* replacement; otherwise it settles as the usage error it is. */
/** stricli routed or parsed nothing runnable. */
private settleRouting(
invocation: Invocation,
stricliExitCode: number | string | null | undefined,
Expand Down
51 changes: 39 additions & 12 deletions packages/cli-engine/src/execution/settlement.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ import { emitFrame } from "./reporting";
import {
OWN_COMMAND_ROUTE,
resolveExample,
substituteBinName,
usageErrorCode,
} from "./stricli-adapter";

Expand Down Expand Up @@ -455,9 +456,36 @@ function retiredInvocation(redirect: CommandRedirect): string {
return `\`--${kebabCase(redirect.flag)}\` on \`${redirect.from}\``;
}

/** A retired invocation the redirect table claims: the run names its
* replacement instead of failing as an unknown command or flag. A
* retired flag can name a server command, whose stdout belongs to a
function redirectNextActions(
redirect: CommandRedirect,
cliName: string,
): NextAction[] {
const steps: NextAction[] = redirect.replacement.map((step, index) => ({
kind: "run-command",
label:
redirect.replacement.length === 1
? "Use the replacement"
: `Step ${index + 1}`,
command: resolveExample(step, cliName),
}));
const help: NextAction[] =
redirect.help === undefined
? []
: [
{
kind: "run-command",
label: "Read its help",
command: resolveExample(`${redirect.help} --help`, cliName),
},
];
const docs: NextAction[] =
redirect.docsUrl === undefined
? []
: [{ kind: "open-url", label: "Read the docs", url: redirect.docsUrl }];
return [...steps, ...help, ...docs];
}

/** A retired flag can name a server command, whose stdout belongs to a
* foreign client — so this settlement renders to stderr for the same
* reason settleUnhandled does. */
export function settleCommandMoved(
Expand All @@ -469,23 +497,22 @@ export function settleCommandMoved(
if (spec.commands[redirect.from]?.kind === "server-command") {
invocation.state.format = "human";
}
const useReplacement: NextAction = {
kind: "run-command",
label: "Use the replacement",
command: resolveExample(redirect.replacement, spec.name),
};
const nextActions = redirectNextActions(redirect, spec.name);
emitErrored(invocation, {
ok: false,
commandId,
error: {
code: "CLI.COMMAND_MOVED",
code: redirect.code ?? "CLI.COMMAND_MOVED",
severity: "error",
summary: `${retiredInvocation(redirect)} has been replaced`,
summary:
redirect.summary === undefined
? `${retiredInvocation(redirect)} has been replaced`
: substituteBinName(redirect.summary, spec.name),
...(redirect.reason === undefined ? {} : { why: redirect.reason }),
nextActions: [useReplacement],
nextActions,
},
diagnostics: [],
nextActions: [useReplacement],
nextActions,
});
return 2;
}
Expand Down
12 changes: 10 additions & 2 deletions packages/cli-engine/tests/engine.type-test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -393,8 +393,16 @@ export const normalizedRedirectFlag: string | undefined =
familyWithRedirects.redirects[0].flag;
export const normalizedRedirectReason: string | undefined =
familyWithRedirects.redirects[0].reason;
// @ts-expect-error a redirect spec needs a replacement
export const redirectWithoutReplacement: RedirectSpec = { from: "migration" };
export const redirectWithoutReplacement: RedirectSpec = {
from: "migration",
help: "migrate",
};
export const redirectWithSteps: RedirectSpec = {
from: "migration",
replacement: ["migrate plan", "migrate apply"],
};
export const normalizedRedirectReplacement: readonly string[] =
familyWithRedirects.redirects[0].replacement;

// Normalized definitions: every field is always present
export const normalizedHelp: MutuallyAssignable<
Expand Down
Loading
Loading