TML-3103: derive error docsUrl from docsUrlFor per-code anchors

The CliStructuredError factories in @prisma-next/errors and the CLI init
errors hardcoded prisma-next.dev command-page URLs predating docsUrlFor.
All 23 docsUrl fields now derive from docsUrlFor(code), so every code links
to its own anchor on the canonical error-reference page and the at-RC
DOCS_ERRORS_VERSION flip covers the whole product in one edit. The two
telemetry help-text prose mentions stay until a docs-site telemetry page
exists.

Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>

Author: wmadden-electric

packages/1-framework/1-core/errors/src/control.ts

@@ -1,5 +1,6 @@
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { StructuredError } from '@prisma-next/utils/structured-error';
+import { docsUrlFor } from '@prisma-next/utils/structured-error';
 
 /**
  * CLI error envelope for output formatting.
@@ -125,7 +126,7 @@ export function errorConfigFileNotFound(
   return new CliStructuredError('CONFIG.FILE_NOT_FOUND', 'Config file not found', {
     ...(options?.why ? { why: options.why } : { why: 'Config file not found' }),
     fix: "Run 'prisma-next init' to create a config file",
-    docsUrl: 'https://prisma-next.dev/docs/cli/config',
+    docsUrl: docsUrlFor('CONFIG.FILE_NOT_FOUND'),
     ...(configPath ? { where: { path: configPath } } : {}),
   });
 }
@@ -139,7 +140,7 @@ export function errorContractConfigMissing(options?: {
   return new CliStructuredError('CONFIG.CONTRACT_MISSING', 'Contract configuration missing', {
     why: options?.why ?? 'The contract configuration is required for emit',
     fix: 'Add contract configuration to your prisma-next.config.ts',
-    docsUrl: 'https://prisma-next.dev/docs/cli/contract-emit',
+    docsUrl: docsUrlFor('CONFIG.CONTRACT_MISSING'),
   });
 }
 
@@ -155,7 +156,7 @@ export function errorContractValidationFailed(
   return new CliStructuredError('CONTRACT.VALIDATION_FAILED', 'Contract validation failed', {
     why: reason,
     fix: 'Re-run `prisma-next contract emit`, or fix the contract file and try again',
-    docsUrl: 'https://prisma-next.dev/docs/contracts',
+    docsUrl: docsUrlFor('CONTRACT.VALIDATION_FAILED'),
     ...(options?.where ? { where: options.where } : {}),
   });
 }
@@ -218,7 +219,7 @@ export function errorQueryRunnerFactoryRequired(options?: {
     {
       why: options?.why ?? 'Config.db.queryRunnerFactory is required for db verify',
       fix: 'Add db.queryRunnerFactory to prisma-next.config.ts',
-      docsUrl: 'https://prisma-next.dev/docs/cli/db-verify',
+      docsUrl: docsUrlFor('CONFIG.QUERY_RUNNER_FACTORY_REQUIRED'),
     },
   );
 }
@@ -235,7 +236,7 @@ export function errorFamilyReadMarkerSqlRequired(options?: {
     {
       why: options?.why ?? 'Family verify.readMarker is required for db verify',
       fix: 'Ensure family.verify.readMarker() is exported by your family package',
-      docsUrl: 'https://prisma-next.dev/docs/cli/db-verify',
+      docsUrl: docsUrlFor('CONFIG.FAMILY_READ_MARKER_REQUIRED'),
     },
   );
 }
@@ -269,7 +270,7 @@ export function errorDriverRequired(options?: { readonly why?: string }): CliStr
     {
       why: options?.why ?? 'Config.driver is required for DB-connected commands',
       fix: 'Add a control-plane driver to prisma-next.config.ts (e.g. import a driver descriptor and set `driver: postgresDriver`)',
-      docsUrl: 'https://prisma-next.dev/docs/cli/config',
+      docsUrl: docsUrlFor('CONFIG.DRIVER_REQUIRED'),
     },
   );
 }
@@ -291,7 +292,7 @@ export function errorContractMissingExtensions(options: {
           ? `Contract requires extension pack '${missing[0]}', but CLI config does not provide a matching descriptor.`
           : `Contract requires extension packs ${missing.map((p) => `'${p}'`).join(', ')}, but CLI config does not provide matching descriptors.`,
       fix: 'Add the missing extension descriptors to `extensions` in prisma-next.config.ts',
-      docsUrl: 'https://prisma-next.dev/docs/cli/config',
+      docsUrl: docsUrlFor('CONFIG.MISSING_EXTENSION_PACKS'),
       meta: {
         missingExtensions: missing,
         providedComponentIds: [...options.providedComponentIds].sort(),
@@ -322,7 +323,7 @@ export function errorMigrationPlanningFailed(options: {
     why: computedWhy,
     fix: computedFix,
     meta: { conflicts: options.conflicts },
-    docsUrl: 'https://prisma-next.dev/docs/cli/db-init',
+    docsUrl: docsUrlFor('MIGRATION.PLANNING_FAILED'),
   });
 }
 
@@ -338,7 +339,7 @@ export function errorTargetMigrationNotSupported(options?: {
     {
       why: options?.why ?? 'The configured target does not provide migration planner/runner',
       fix: 'Select a target that provides migrations (it must export `target.migrations` for db init)',
-      docsUrl: 'https://prisma-next.dev/docs/cli/db-init',
+      docsUrl: docsUrlFor('MIGRATION.TARGET_UNSUPPORTED'),
     },
   );
 }
@@ -425,7 +426,7 @@ export function errorConfigValidation(
   return new CliStructuredError('CONFIG.VALIDATION_FAILED', 'Config validation error', {
     why: options?.why ?? `Config must have a "${field}" field`,
     fix: 'Check your prisma-next.config.ts and ensure all required fields are provided',
-    docsUrl: 'https://prisma-next.dev/docs/cli/config',
+    docsUrl: docsUrlFor('CONFIG.VALIDATION_FAILED'),
   });
 }
 

packages/1-framework/1-core/errors/test/control.test.ts

@@ -1,3 +1,4 @@
+import { docsUrlFor } from '@prisma-next/utils/structured-error';
 import { describe, expect, it } from 'vitest';
 import {
   CliStructuredError,
@@ -144,6 +145,11 @@ describe('Config Errors', () => {
     expect(error.where?.path).toBe('/path/to/config.ts');
   });
 
+  it('errorConfigFileNotFound links the canonical error-reference anchor for its code', () => {
+    const error = errorConfigFileNotFound();
+    expect(error.docsUrl).toBe(docsUrlFor('CONFIG.FILE_NOT_FOUND'));
+  });
+
   it('errorConfigFileNotFound with custom why', () => {
     const error = errorConfigFileNotFound('/path/to/config.ts', { why: 'Custom reason' });
     expect(error.why).toBe('Custom reason');

packages/1-framework/3-tooling/cli/src/commands/init/errors.ts

@@ -1,3 +1,4 @@
+import { docsUrlFor } from '@prisma-next/utils/structured-error';
 import { CliStructuredError } from '../../utils/cli-errors';
 
 /**
@@ -9,7 +10,7 @@ export function errorInitReinitNeedsForce(): CliStructuredError {
   return new CliStructuredError('CLI.INIT_REINIT_NEEDS_FORCE', 'Project is already initialized', {
     why: 'A `prisma-next.config.ts` already exists in this directory. Re-running `init` would overwrite the scaffolded files; in non-interactive mode `init` will not do that without `--force`.',
     fix: 'Pass `--force` to overwrite the existing scaffold, or run `init` interactively to confirm.',
-    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    docsUrl: docsUrlFor('CLI.INIT_REINIT_NEEDS_FORCE'),
   });
 }
 
@@ -44,7 +45,7 @@ export function errorInitMissingFlags(options: {
   return new CliStructuredError('CLI.INIT_MISSING_FLAGS', 'Missing required flags', {
     why: `${options.why} Missing required flag(s): ${flagList}.`,
     fix: `Re-run with the missing flag(s) supplied, e.g. \`prisma-next init --yes ${fixList}\`. Use \`prisma-next init --help\` to see every flag.`,
-    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    docsUrl: docsUrlFor('CLI.INIT_MISSING_FLAGS'),
     meta: { missingFlags: options.missing },
   });
 }
@@ -64,7 +65,7 @@ export function errorInitInvalidFlagValue(options: {
     {
       why: `\`--${options.flag} ${options.value}\` is not one of: ${options.allowed.join(', ')}.`,
       fix: `Use one of: ${options.allowed.map((v) => `--${options.flag} ${v}`).join(', ')}.`,
-      docsUrl: 'https://prisma-next.dev/docs/cli/init',
+      docsUrl: docsUrlFor('CLI.INIT_INVALID_FLAG_VALUE'),
       meta: { flag: options.flag, value: options.value, allowed: options.allowed },
     },
   );
@@ -93,7 +94,7 @@ export function errorInitAuthoringSchemaPathMismatch(options: {
         `Use a matching pair, for example \`--authoring ${expectedAuthoring} --schema-path <path>${options.expectedExtension}\`, ` +
         'or change `--authoring` to match the path you supplied. ' +
         'You can also omit `--schema-path` to use the default for the chosen authoring.',
-      docsUrl: 'https://prisma-next.dev/docs/cli/init',
+      docsUrl: docsUrlFor('CLI.INIT_AUTHORING_SCHEMA_PATH_MISMATCH'),
       meta: {
         authoring: options.authoring,
         schemaPath: options.schemaPath,
@@ -134,7 +135,7 @@ export function errorInitStrictProbeWithoutProbe(): CliStructuredError {
     {
       why: '`--strict-probe` only changes how a *failed* probe is reported; without `--probe-db` no probe is attempted in the first place. (`init` is offline-by-default — it never opens a connection to your database without explicit consent.)',
       fix: 'Add `--probe-db` to opt in to the probe, or drop `--strict-probe` if you do not need the version check.',
-      docsUrl: 'https://prisma-next.dev/docs/cli/init',
+      docsUrl: docsUrlFor('CLI.INIT_STRICT_PROBE_WITHOUT_PROBE'),
     },
   );
 }
@@ -161,7 +162,7 @@ export function errorInitInstallFailed(options: {
   return new CliStructuredError('CLI.INIT_INSTALL_FAILED', 'Failed to install dependencies', {
     why,
     fix: `Install manually:\n  ${options.addCommand}\n  ${options.addDevCommand}\nThen run \`${options.emitCommand}\` to emit the contract.`,
-    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    docsUrl: docsUrlFor('CLI.INIT_INSTALL_FAILED'),
     meta: {
       filesWritten: options.filesWritten,
       stderr: trimmed,
@@ -187,7 +188,7 @@ export function errorInitInvalidManifest(options: {
   return new CliStructuredError('CLI.INIT_INVALID_MANIFEST', `Failed to parse ${options.path}`, {
     why: `\`${options.path}\` is not valid JSON: ${options.cause}`,
     fix: `Fix the JSON syntax in \`${options.path}\` (a missing comma or unbalanced brace is the most common cause), then re-run \`prisma-next init\`.`,
-    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    docsUrl: docsUrlFor('CLI.INIT_INVALID_MANIFEST'),
     meta: { path: options.path, cause: options.cause },
   });
 }
@@ -213,7 +214,7 @@ export function errorInitInvalidTsconfig(options: {
   return new CliStructuredError('CLI.INIT_INVALID_TSCONFIG', `Failed to parse ${options.path}`, {
     why: `\`${options.path}\` is not valid JSON or JSONC: ${options.cause}`,
     fix: `Fix the syntax in \`${options.path}\` and re-run \`prisma-next init\`. \`init\` accepts JSONC (comments and trailing commas) but cannot recover from unbalanced braces or missing commas.`,
-    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    docsUrl: docsUrlFor('CLI.INIT_INVALID_TSCONFIG'),
     meta: { path: options.path, cause: options.cause },
   });
 }
@@ -239,7 +240,7 @@ export function errorInitProbeFailed(options: {
   return new CliStructuredError('CLI.INIT_PROBE_FAILED', 'Database probe failed', {
     why: `\`--probe-db\` could not complete and \`--strict-probe\` was set: ${options.cause}`,
     fix: 'Confirm `DATABASE_URL` points at a reachable server, or drop `--strict-probe` to treat probe failures as warnings.',
-    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    docsUrl: docsUrlFor('CLI.INIT_PROBE_FAILED'),
     meta: {
       filesWritten: options.filesWritten,
       cause: options.cause,
@@ -261,7 +262,7 @@ export function errorInitEmitFailed(options: {
   return new CliStructuredError('CLI.INIT_EMIT_FAILED', 'Failed to emit contract', {
     why: `\`prisma-next contract emit\` failed: ${options.cause}`,
     fix: `Inspect your contract file, fix the underlying issue, then re-run \`${options.emitCommand}\`. Pass \`-v\` for the full error envelope.`,
-    docsUrl: 'https://prisma-next.dev/docs/cli/contract-emit',
+    docsUrl: docsUrlFor('CLI.INIT_EMIT_FAILED'),
     meta: {
       filesWritten: options.filesWritten,
       cause: options.cause,
@@ -294,7 +295,7 @@ export function errorInitSkillInstallFailed(options: {
         'Either:\n' +
         `  - Re-run \`prisma-next init --no-skill${options.filesWritten.length > 0 ? ' --force' : ''}\` to skip the skill install for this run, or\n` +
         `  - Fix the underlying issue (network, npm registry, \`npx skills\` on PATH) and install manually:\n      ${options.skillInstallCommand}`,
-      docsUrl: 'https://prisma-next.dev/docs/cli/init#skills',
+      docsUrl: docsUrlFor('CLI.INIT_SKILL_INSTALL_FAILED'),
       meta: {
         filesWritten: options.filesWritten,
         skillInstallCommand: options.skillInstallCommand,

packages/1-framework/3-tooling/cli/src/commands/init/init.ts

@@ -2,6 +2,7 @@ import { execFile } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { promisify } from 'node:util';
 import * as clack from '@clack/prompts';
+import { docsUrlFor } from '@prisma-next/utils/structured-error';
 import { basename, dirname, isAbsolute, join } from 'pathe';
 import { CliStructuredError } from '../../utils/cli-errors';
 import { formatErrorJson, formatErrorOutput } from '../../utils/formatters/errors';
@@ -546,7 +547,7 @@ export async function runInit(
         {
           why: `The success document failed schema validation: ${String(validated)}`,
           fix: 'This is a bug in prisma-next. Please report it with the full `-v` output.',
-          docsUrl: 'https://prisma-next.dev/docs/cli/init',
+          docsUrl: docsUrlFor('CLI.INIT_INVALID_OUTPUT_DOCUMENT'),
         },
       ),
     );

packages/1-framework/3-tooling/cli/test/cli-errors.test.ts

@@ -1,3 +1,4 @@
+import { docsUrlFor } from '@prisma-next/utils/structured-error';
 import { describe, expect, it } from 'vitest';
 import {
   buildNeverPlannedFailure,
@@ -22,7 +23,7 @@ describe('CliStructuredError.toEnvelope()', () => {
     expect(envelope.fix).toBe(
       'Add a control-plane driver to prisma-next.config.ts (e.g. import a driver descriptor and set `driver: postgresDriver`)',
     );
-    expect(envelope.docsUrl).toBe('https://prisma-next.dev/docs/cli/config');
+    expect(envelope.docsUrl).toBe(docsUrlFor('CONFIG.DRIVER_REQUIRED'));
   });
 
   it('converts readMarker error to envelope with CONFIG.FAMILY_READ_MARKER_REQUIRED', () => {
@@ -34,7 +35,7 @@ describe('CliStructuredError.toEnvelope()', () => {
     expect(envelope.fix).toBe(
       'Ensure family.verify.readMarker() is exported by your family package',
     );
-    expect(envelope.docsUrl).toBe('https://prisma-next.dev/docs/cli/db-verify');
+    expect(envelope.docsUrl).toBe(docsUrlFor('CONFIG.FAMILY_READ_MARKER_REQUIRED'));
   });
 });
 

packages/1-framework/3-tooling/cli/test/commands/init/errors.test.ts

@@ -0,0 +1,10 @@
+import { docsUrlFor } from '@prisma-next/utils/structured-error';
+import { describe, expect, it } from 'vitest';
+import { errorInitReinitNeedsForce } from '../../../src/commands/init/errors';
+
+describe('init errors', () => {
+  it('errorInitReinitNeedsForce links the canonical error-reference anchor for its code', () => {
+    const error = errorInitReinitNeedsForce();
+    expect(error.docsUrl).toBe(docsUrlFor('CLI.INIT_REINIT_NEEDS_FORCE'));
+  });
+});

packages/1-framework/3-tooling/cli/test/errors.mapping.test.ts

@@ -1,3 +1,4 @@
+import { docsUrlFor } from '@prisma-next/utils/structured-error';
 import { describe, expect, it } from 'vitest';
 import { errorDriverRequired, errorFamilyReadMarkerSqlRequired } from '../src/utils/cli-errors';
 
@@ -10,7 +11,7 @@ describe('CliStructuredError.toEnvelope()', () => {
       code: 'CONFIG.DRIVER_REQUIRED',
       summary: 'Driver is required for DB-connected commands',
       fix: 'Add a control-plane driver to prisma-next.config.ts (e.g. import a driver descriptor and set `driver: postgresDriver`)',
-      docsUrl: 'https://prisma-next.dev/docs/cli/config',
+      docsUrl: docsUrlFor('CONFIG.DRIVER_REQUIRED'),
     });
   });
 
@@ -22,7 +23,7 @@ describe('CliStructuredError.toEnvelope()', () => {
       code: 'CONFIG.FAMILY_READ_MARKER_REQUIRED',
       summary: 'Family readMarker() is required',
       fix: 'Ensure family.verify.readMarker() is exported by your family package',
-      docsUrl: 'https://prisma-next.dev/docs/cli/db-verify',
+      docsUrl: docsUrlFor('CONFIG.FAMILY_READ_MARKER_REQUIRED'),
     });
   });
 });