@prisma-next/cli 0.5.0-dev.2 → 0.5.0-dev.21

package/src/commands/init/init.ts

@@ -1,8 +1,11 @@
 import { execFile } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { promisify } from 'node:util';
 import * as clack from '@clack/prompts';
-import { dirname, extname, isAbsolute, join, normalize } from 'pathe';
+import { dirname, isAbsolute, join } from 'pathe';
+import { CliStructuredError } from '../../utils/cli-errors';
+import { formatErrorJson, formatErrorOutput } from '../../utils/formatters/errors';
+import type { GlobalFlags } from '../../utils/global-flags';
 import { TerminalUI } from '../../utils/terminal-ui';
 import {
   detectPackageManager,
@@ -10,194 +13,813 @@ import {
   formatAddDevArgs,
   formatRunCommand,
   hasProjectManifest,
+  type PackageManager,
 } from './detect-package-manager';
-import { agentSkillMd } from './templates/agent-skill';
+import { detectPnpmCatalogOverrides, type PnpmCatalogOverride } from './detect-pnpm-catalog';
+import {
+  errorInitEmitFailed,
+  errorInitInstallFailed,
+  errorInitInvalidManifest,
+  errorInitInvalidTsconfig,
+  errorInitMissingManifest,
+  errorInitProbeFailed,
+} from './errors';
 import {
-  type AuthoringId,
-  configFile,
-  dbFile,
-  defaultSchemaPath,
-  starterSchema,
-  type TargetId,
-  targetPackageName,
-} from './templates/code-templates';
+  INIT_EXIT_EMIT_FAILED,
+  INIT_EXIT_INSTALL_FAILED,
+  INIT_EXIT_INTERNAL_ERROR,
+  INIT_EXIT_OK,
+  INIT_EXIT_PRECONDITION,
+  INIT_EXIT_USER_ABORTED,
+} from './exit-codes';
+import { mergeGitattributes, requiredGitattributesLines } from './hygiene-gitattributes';
+import { mergeGitignore } from './hygiene-gitignore';
+import { mergePackageScripts, REQUIRED_SCRIPTS } from './hygiene-package-scripts';
+import { type InitFlagOptions, type ResolvedInitInputs, resolveInitInputs } from './inputs';
+import {
+  buildNextSteps,
+  formatInitJson,
+  type InitOutput,
+  InitOutputSchema,
+  renderInitOutro,
+} from './output';
+import { type ProbeOutcome, type ProbeOverrides, probeServerVersion } from './probe-db';
+import { findStaleArtefacts, removeDependency } from './reinit-cleanup';
+import { agentSkillMd } from './templates/agent-skill';
+import { configFile, dbFile, starterSchema, targetPackageName } from './templates/code-templates';
+import { envExampleContent, envFileContent, MIN_SERVER_VERSION } from './templates/env';
 import { quickReferenceMd } from './templates/quick-reference';
-import { defaultTsConfig, mergeTsConfig } from './templates/tsconfig';
-
-export interface InitOptions {
-  readonly noInstall?: boolean;
-}
+import { defaultTsConfig, mergeTsConfig, TsConfigParseError } from './templates/tsconfig';
 
 interface FileEntry {
   readonly path: string;
   readonly content: string;
+  /**
+   * Optional human-mode message printed *after* the file is written —
+   * matches the legacy `Updated tsconfig.json with required compiler
+   * options.` line emitted when an existing tsconfig is merged. Kept
+   * with the entry so the precondition phase decides what to say and
+   * the write phase remains a dumb loop (FR6.2 atomicity).
+   */
+  readonly logMessage?: string;
+}
+
+interface InstallReport {
+  readonly skipped: boolean;
+  readonly deps: readonly string[];
+  readonly devDeps: readonly string[];
+  readonly warnings: readonly string[];
 }
 
-export async function runInit(baseDir: string, options: InitOptions): Promise<void> {
-  const ui = new TerminalUI();
+/**
+ * Runs the `init` command end-to-end and returns the exit code. Catches
+ * structured CLI errors raised at every phase (input resolution, install,
+ * emit) and renders them via the same UI surface as success output
+ * (`--json` to stdout, human to stderr). Exit codes follow the documented
+ * stable set in `./exit-codes.ts` (FR1.6) and the
+ * [Style Guide § Exit Codes](../../../../../../../docs/CLI%20Style%20Guide.md#exit-codes).
+ *
+ * Layered for testability: the action handler in `./index.ts` is
+ * responsible for parsing flags and constructing `runOptions`; this
+ * function does no flag parsing of its own.
+ */
+export async function runInit(
+  baseDir: string,
+  runOptions: {
+    readonly options: InitFlagOptions;
+    readonly flags: GlobalFlags;
+    /**
+     * Whether `init` may render an interactive prompt. Decoupled from
+     * `flags.interactive` (which gates `TerminalUI` decoration / stdout
+     * mode) — see [Style Guide § Interactivity](../../../../../../../docs/CLI%20Style%20Guide.md#interactivity).
+     */
+    readonly canPrompt: boolean;
+    /**
+     * FR8.3 — test-only seam for the optional database version probe.
+     * Production callers omit this; tests inject stub `probePostgres` /
+     * `probeMongo` functions so the probe contract (env handling,
+     * comparator, message formatting, `--strict-probe` escalation) can
+     * be exercised without a live database. Never read at runtime by a
+     * user invocation of the CLI.
+     */
+    readonly probeOverrides?: ProbeOverrides;
+  },
+): Promise<number> {
+  const { options, flags, canPrompt, probeOverrides } = runOptions;
+  const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+  const warnings: string[] = [];
+  const filesWritten: string[] = [];
+  const filesDeleted: string[] = [];
 
-  clack.intro('prisma-next init', { output: process.stderr });
+  if (!flags.json && !flags.quiet) {
+    clack.intro('prisma-next init', { output: process.stderr });
+  }
 
   if (!hasProjectManifest(baseDir)) {
-    ui.error(
-      'No package.json or deno.json found. Initialize your project first (e.g. npm init or deno init), then re-run prisma-next init.',
-    );
-    process.exit(1);
+    return emitError(ui, flags, errorInitMissingManifest());
+  }
+
+  let inputs: ResolvedInitInputs;
+  try {
+    inputs = await resolveInitInputs({ baseDir, options, flags, canPrompt });
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return emitError(ui, flags, error);
+    }
+    throw error;
   }
 
   const pm = await detectPackageManager(baseDir);
   const pkgRun = formatRunCommand(pm, 'prisma-next', '').trimEnd();
 
-  if (existsSync(join(baseDir, 'prisma-next.config.ts'))) {
-    const reinit = await clack.confirm({
-      message:
-        'This project is already initialized. Re-initialize? This will overwrite all generated files.',
-      initialValue: false,
-      output: process.stderr,
-    });
-    if (clack.isCancel(reinit) || !reinit) {
-      clack.cancel('Init cancelled.', { output: process.stderr });
-      process.exit(0);
-    }
-  }
-
-  const targetResult = await clack.select({
-    message: 'What database are you using?',
-    options: [
-      { value: 'postgres' as TargetId, label: 'PostgreSQL' },
-      { value: 'mongo' as TargetId, label: 'MongoDB' },
-    ],
-    output: process.stderr,
-  });
-  if (clack.isCancel(targetResult)) {
-    clack.cancel('Init cancelled.', { output: process.stderr });
-    process.exit(0);
-  }
-  const target = targetResult as TargetId;
-
-  const authoringResult = await clack.select({
-    message: 'How do you want to write your schema?',
-    options: [
-      { value: 'psl' as AuthoringId, label: 'Prisma Schema Language (.prisma)' },
-      { value: 'typescript' as AuthoringId, label: 'TypeScript (.ts)' },
-    ],
-    output: process.stderr,
-  });
-  if (clack.isCancel(authoringResult)) {
-    clack.cancel('Init cancelled.', { output: process.stderr });
-    process.exit(0);
-  }
-  const authoring = authoringResult as AuthoringId;
-
-  const schemaPathResult = await clack.text({
-    message: 'Where should the schema file go?',
-    initialValue: defaultSchemaPath(authoring),
-    validate(value = '') {
-      const trimmed = value.trim();
-      if (trimmed.length === 0) return 'Path cannot be empty';
-      if (trimmed.endsWith('/') || trimmed.endsWith('\\'))
-        return 'Path must be a file, not a directory';
-      if (!extname(trimmed)) return 'Path must include a file extension (e.g. .prisma or .ts)';
-      return undefined;
+  const schemaDir = dirname(inputs.schemaPath);
+  const configContractPath = isAbsolute(inputs.schemaPath)
+    ? inputs.schemaPath
+    : `./${inputs.schemaPath}`;
+
+  // -----------------------------------------------------------------
+  // Precondition phase (FR6.2 / NFR3 atomicity)
+  //
+  // Read every file we may need to merge with, parse it, compute the
+  // merged content, and accumulate the full set of writes — *before*
+  // touching the filesystem. A failure here (malformed package.json,
+  // unparseable tsconfig.json, …) returns a structured error and the
+  // user's project on disk stays byte-identical to its pre-init state.
+  // -----------------------------------------------------------------
+  const filesToWrite: FileEntry[] = [
+    { path: inputs.schemaPath, content: starterSchema(inputs.target, inputs.authoring) },
+    {
+      path: 'prisma-next.config.ts',
+      content: configFile(inputs.target, configContractPath),
+    },
+    { path: join(schemaDir, 'db.ts'), content: dbFile(inputs.target) },
+    {
+      path: 'prisma-next.md',
+      content: quickReferenceMd(inputs.target, inputs.authoring, inputs.schemaPath, pkgRun),
     },
-    output: process.stderr,
-  });
-  if (clack.isCancel(schemaPathResult)) {
-    clack.cancel('Init cancelled.', { output: process.stderr });
-    process.exit(0);
-  }
-  const schemaPath = normalize((schemaPathResult as string).trim());
-
-  const schemaDir = dirname(schemaPath);
-  const configPath = isAbsolute(schemaPath) ? schemaPath : `./${schemaPath}`;
-
-  const files: FileEntry[] = [
-    { path: schemaPath, content: starterSchema(target, authoring) },
-    { path: 'prisma-next.config.ts', content: configFile(target, configPath) },
-    { path: join(schemaDir, 'db.ts'), content: dbFile(target) },
-    { path: 'prisma-next.md', content: quickReferenceMd(target, schemaPath, pkgRun) },
     {
       path: '.agents/skills/prisma-next/SKILL.md',
-      content: agentSkillMd(target, schemaPath, pkgRun),
+      content: agentSkillMd(inputs.target, inputs.authoring, inputs.schemaPath, pkgRun),
     },
+    { path: '.env.example', content: envExampleContent(inputs.target) },
   ];
 
-  for (const file of files) {
-    const fullPath = join(baseDir, file.path);
-    mkdirSync(dirname(fullPath), { recursive: true });
-    writeFileSync(fullPath, file.content, 'utf-8');
+  // FR9.1 — on re-init, queue the previously-emitted contract artefacts
+  // for deletion so a target switch (or schema-shape change) does not
+  // leave a stale `contract.json` / `contract.d.ts` next to the new
+  // schema source. Detection is filesystem-only (no parsing of the
+  // previous config) so the cleanup is safe to run before the write
+  // phase: each path is checked for existence in the precondition,
+  // and missing-on-disk-at-write-time is tolerated.
+  const filesToDelete: string[] = inputs.reinit ? [...findStaleArtefacts(baseDir, schemaDir)] : [];
+
+  // FR3.2: a real `.env` is only written when the user opted in. Never
+  // overwrite an existing `.env` — secrets live there and clobbering
+  // them is the most damaging possible side-effect of `init`.
+  if (inputs.writeEnv) {
+    if (!existsSync(join(baseDir, '.env'))) {
+      filesToWrite.push({ path: '.env', content: envFileContent(inputs.target) });
+    } else {
+      warnings.push(
+        '.env already exists; leaving it untouched. Compare with .env.example for any new keys.',
+      );
+    }
   }
 
+  // FR2.2 / FR6.1: tsconfig.json gets the minimum compiler options the
+  // scaffolded files need. JSONC (TS's actual configured dialect) is
+  // accepted; an unparseable file is mapped to a structured
+  // precondition error (5011) rather than crashing mid-write.
   const tsconfigPath = join(baseDir, 'tsconfig.json');
   if (existsSync(tsconfigPath)) {
     const existing = readFileSync(tsconfigPath, 'utf-8');
-    writeFileSync(tsconfigPath, mergeTsConfig(existing), 'utf-8');
-    ui.log('Updated tsconfig.json with required compiler options.');
+    let merged: string;
+    try {
+      merged = mergeTsConfig(existing);
+    } catch (err) {
+      if (err instanceof TsConfigParseError) {
+        return emitError(
+          ui,
+          flags,
+          errorInitInvalidTsconfig({ path: 'tsconfig.json', cause: err.message }),
+        );
+      }
+      throw err;
+    }
+    filesToWrite.push({
+      path: 'tsconfig.json',
+      content: merged,
+      logMessage: 'Updated tsconfig.json with required compiler options.',
+    });
   } else {
-    writeFileSync(tsconfigPath, defaultTsConfig(), 'utf-8');
+    filesToWrite.push({ path: 'tsconfig.json', content: defaultTsConfig() });
   }
 
-  const emitCommand = formatRunCommand(pm, 'prisma-next', 'contract emit');
+  // FR3.3: idempotent .gitignore — append only what's missing.
+  const gitignorePath = join(baseDir, '.gitignore');
+  const existingGitignore = existsSync(gitignorePath)
+    ? readFileSync(gitignorePath, 'utf-8')
+    : undefined;
+  const newGitignore = mergeGitignore(existingGitignore);
+  if (newGitignore !== null) {
+    filesToWrite.push({ path: '.gitignore', content: newGitignore });
+  }
 
-  if (options.noInstall) {
-    const pkg = targetPackageName(target);
-    ui.note(
-      [
-        'Run the following commands to complete setup:',
-        '',
-        '  1. Install dependencies:',
-        `     ${pm} ${formatAddArgs(pm, [pkg, 'dotenv']).join(' ')}`,
-        `     ${pm} ${formatAddDevArgs(pm, ['prisma-next']).join(' ')}`,
-        '',
-        '  2. Emit the contract:',
-        `     ${emitCommand}`,
-      ].join('\n'),
-      'Manual steps',
+  // FR3.4: idempotent .gitattributes — linguist-generated entries for
+  // the emitted artefacts so GitHub diff stats / code review collapse
+  // them by default.
+  const gitattributesPath = join(baseDir, '.gitattributes');
+  const existingGitattributes = existsSync(gitattributesPath)
+    ? readFileSync(gitattributesPath, 'utf-8')
+    : undefined;
+  const newGitattributes = mergeGitattributes(
+    existingGitattributes,
+    requiredGitattributesLines(schemaDir, inputs.target),
+  );
+  if (newGitattributes !== null) {
+    filesToWrite.push({ path: '.gitattributes', content: newGitattributes });
+  }
+
+  // Read + parse package.json once for both the FR3.5 scripts merge and
+  // the FR2.1 `@types/node`-presence check. A malformed manifest is
+  // mapped to a structured precondition error (5010) rather than the
+  // generic INTERNAL_ERROR fallback so CI/agents can branch on it.
+  const packageJsonPath = join(baseDir, 'package.json');
+  let parsedPackageJson: Record<string, unknown> | null = null;
+  if (existsSync(packageJsonPath)) {
+    const pkgRaw = readFileSync(packageJsonPath, 'utf-8');
+    try {
+      parsedPackageJson = JSON.parse(pkgRaw) as Record<string, unknown>;
+    } catch (err) {
+      if (err instanceof SyntaxError) {
+        return emitError(
+          ui,
+          flags,
+          errorInitInvalidManifest({ path: 'package.json', cause: err.message }),
+        );
+      }
+      throw err;
+    }
+
+    // package.json edits are chained: FR9.2 facade-dep removal first
+    // (so the script merge sees the cleaned `dependencies` and rounds
+    // out a single re-stringification), then FR3.5 / FR9.3 idempotent
+    // scripts merge with collision detection.
+    let workingPkg = pkgRaw;
+    let pkgChanged = false;
+    if (inputs.removePreviousFacade !== null) {
+      const next = removeDependency(workingPkg, inputs.removePreviousFacade);
+      if (next !== null) {
+        workingPkg = next;
+        pkgChanged = true;
+      }
+    }
+    const { content: nextPkg, warnings: scriptWarnings } = mergePackageScripts(
+      workingPkg,
+      REQUIRED_SCRIPTS,
     );
-  } else {
-    const pkg = targetPackageName(target);
-    const spinner = ui.spinner();
-    let installSucceeded = false;
+    if (nextPkg !== null) {
+      workingPkg = nextPkg;
+      pkgChanged = true;
+    }
+    if (pkgChanged) {
+      filesToWrite.push({ path: 'package.json', content: workingPkg });
+    }
+    warnings.push(...scriptWarnings);
+  }
 
-    const exec = promisify(execFile);
+  // -----------------------------------------------------------------
+  // Write phase — every input has been parsed and every merged file is
+  // staged. From here on, failures are only possible at the
+  // install/emit stages, which the spec treats as discrete subsequent
+  // phases (FR6.3): scaffold files remain on disk so the user can fix
+  // and retry.
+  // -----------------------------------------------------------------
+  for (const file of filesToWrite) {
+    const fullPath = join(baseDir, file.path);
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, file.content, 'utf-8');
+    filesWritten.push(file.path);
+    if (file.logMessage !== undefined && !flags.json && !flags.quiet) {
+      ui.log(file.logMessage);
+    }
+  }
 
-    spinner.start(`Installing ${pkg}, dotenv, and prisma-next...`);
+  // FR9.1 — delete stale artefacts after the new templates are written.
+  // Order is intentional: the names do not collide with `filesToWrite`
+  // (we never write `contract.json` from this command — that's `contract
+  // emit`'s job), so deletion *after* the writes guarantees we never
+  // remove a file we just produced. `existsSync` was checked in the
+  // precondition phase, but a concurrent `git checkout` could have
+  // already removed the file — `unlinkSync` would then throw ENOENT,
+  // which we tolerate as the user-visible end state we wanted anyway.
+  for (const rel of filesToDelete) {
+    const fullPath = join(baseDir, rel);
+    if (!existsSync(fullPath)) {
+      continue;
+    }
     try {
-      await exec(pm, formatAddArgs(pm, [pkg, 'dotenv']), { cwd: baseDir });
-      await exec(pm, formatAddDevArgs(pm, ['prisma-next']), { cwd: baseDir });
-      spinner.stop(`Installed ${pkg}, dotenv, and prisma-next`);
-      installSucceeded = true;
+      unlinkSync(fullPath);
+      filesDeleted.push(rel);
     } catch (err) {
-      spinner.stop('Installation failed');
-      const stderr =
-        err instanceof Error && 'stderr' in err ? (err as { stderr: string }).stderr : '';
-      ui.warn(
+      if (!(err instanceof Error && 'code' in err && (err as { code: string }).code === 'ENOENT')) {
+        throw err;
+      }
+    }
+  }
+
+  const emitCommand = formatRunCommand(pm, 'prisma-next', 'contract emit');
+
+  let install: InstallReport;
+  try {
+    install = await runInstall({
+      baseDir,
+      pm,
+      target: inputs.target,
+      install: inputs.install,
+      flags,
+      ui,
+      filesWritten,
+      hasTypesNode:
+        parsedPackageJson !== null ? hasDirectDep(parsedPackageJson, '@types/node') : false,
+    });
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return emitError(ui, flags, error);
+    }
+    throw error;
+  }
+  warnings.push(...install.warnings);
+
+  let contractEmitted = false;
+  if (!install.skipped) {
+    try {
+      await runEmit({ baseDir, ui, filesWritten, emitCommand });
+      contractEmitted = true;
+    } catch (error) {
+      if (CliStructuredError.is(error)) {
+        return emitError(ui, flags, error);
+      }
+      throw error;
+    }
+  }
+
+  // FR8.3 — optional database version probe. Strictly opt-in: we never
+  // open a network connection to the user's database without
+  // `--probe-db`. The probe runs after install + emit so the target
+  // driver (`pg` / `mongodb`) is guaranteed present in node_modules
+  // for the CJS `createRequire` resolution.
+  if (inputs.probeDb) {
+    const outcome = await probeServerVersion(
+      {
+        baseDir,
+        target: inputs.target,
+        databaseUrl: process.env['DATABASE_URL'],
+        minVersion: MIN_SERVER_VERSION[inputs.target],
+      },
+      probeOverrides ?? {},
+    );
+    const escalated = applyProbeOutcome(outcome, {
+      strictProbe: inputs.strictProbe,
+      warnings,
+    });
+    if (escalated !== null) {
+      return emitError(ui, flags, errorInitProbeFailed({ cause: escalated, filesWritten }));
+    }
+  }
+
+  const output: InitOutput = {
+    ok: true,
+    target: inputs.target === 'mongo' ? 'mongodb' : 'postgres',
+    authoring: inputs.authoring,
+    schemaPath: inputs.schemaPath,
+    filesWritten,
+    filesDeleted,
+    packagesInstalled: {
+      skipped: install.skipped,
+      deps: [...install.deps],
+      devDeps: [...install.devDeps],
+    },
+    contractEmitted,
+    nextSteps: buildNextSteps({
+      target: inputs.target === 'mongo' ? 'mongodb' : 'postgres',
+      contractEmitted,
+      emitCommand,
+      schemaPath: inputs.schemaPath,
+    }),
+    warnings,
+  };
+
+  // Validate the success document at the boundary so a regression in any
+  // upstream branch (templates, schema, install report) shows up as a
+  // typed runtime failure here instead of an opaque consumer-side parse
+  // error. The schema is also exported on the package surface for
+  // downstream consumers.
+  const validated = InitOutputSchema(output);
+  if (validated instanceof Error || (validated as { problems?: unknown }).problems !== undefined) {
+    // Route through `emitError` rather than throwing: the bare throw
+    // bypassed `--json` envelope formatting and `exitCodeForError`, so a
+    // 5009 regression would surface as an uncaught exception in
+    // commander instead of the documented `INTERNAL_ERROR` envelope on
+    // the right channel.
+    return emitError(
+      ui,
+      flags,
+      new CliStructuredError('5009', 'Init produced an invalid output document', {
+        domain: 'CLI',
+        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',
+      }),
+    );
+  }
+
+  if (flags.json) {
+    ui.output(formatInitJson(output));
+  } else {
+    renderInitOutro(ui, output, flags);
+    if (!flags.quiet) {
+      clack.outro('Done. Open prisma-next.md to get started.', { output: process.stderr });
+    }
+  }
+
+  return INIT_EXIT_OK;
+}
+
+/**
+ * Renders a structured CLI error to the right channel and returns the exit
+ * code derived from the error's PN code. JSON-mode errors go to stdout
+ * (so consumers always parse from one place); human-mode errors go to
+ * stderr. Mirrors `handleResult` but returns init-specific exit codes
+ * rather than the CLI/RUN binary.
+ */
+function emitError(ui: TerminalUI, flags: GlobalFlags, error: CliStructuredError): number {
+  const envelope = error.toEnvelope();
+  if (flags.json) {
+    ui.output(formatErrorJson(envelope));
+  } else {
+    ui.error(formatErrorOutput(envelope, flags));
+  }
+  return exitCodeForError(error);
+}
+
+/**
+ * Maps a structured init error to its documented exit code. Centralised so
+ * the error → exit-code contract lives next to the codes themselves.
+ *
+ * `5009` (and the unknown-code default branch) routes to
+ * `INIT_EXIT_INTERNAL_ERROR` because those represent prisma-next bugs the
+ * user did not cause — surfacing them as `PRECONDITION` would mislead
+ * automation into thinking the caller mis-invoked the CLI.
+ *
+ * See [exit-codes.ts](./exit-codes.ts) for the canonical list and
+ * [Style Guide § Exit Codes](../../../../../../../docs/CLI%20Style%20Guide.md#exit-codes)
+ * for the reservation policy.
+ *
+ * Exported for unit tests so the mapping can be asserted without
+ * round-tripping a full `runInit` invocation.
+ */
+export function exitCodeForError(error: { readonly code: string }): number {
+  switch (error.code) {
+    case '5001': // missing manifest — precondition
+    case '5002': // re-init needs --force — precondition
+    case '5003': // missing flags — precondition
+    case '5004': // invalid flag value — precondition
+    case '5005': // --strict-probe without --probe-db — precondition
+    case '5010': // invalid manifest (malformed package.json) — precondition
+    case '5011': // invalid tsconfig (unparseable JSONC) — precondition
+    case '5012': // probe failed under --strict-probe — precondition
+      return INIT_EXIT_PRECONDITION;
+    case '5006': // user aborted interactive prompt
+      return INIT_EXIT_USER_ABORTED;
+    case '5007': // install failed
+      return INIT_EXIT_INSTALL_FAILED;
+    case '5008': // emit failed
+      return INIT_EXIT_EMIT_FAILED;
+    case '5009': // invalid output document — internal bug in prisma-next
+      return INIT_EXIT_INTERNAL_ERROR;
+    default:
+      // Any unexpected code is treated as an internal bug rather than
+      // mis-routed to PRECONDITION. Adding a new code requires an
+      // explicit case above.
+      return INIT_EXIT_INTERNAL_ERROR;
+  }
+}
+
+/**
+ * Folds a `ProbeOutcome` into init's warning channel and returns the
+ * fatal cause string when `--strict-probe` should escalate. Mirrors
+ * the FR8.3 contract:
+ *
+ * - `ok` — informational; nothing surfaced unless verbose. (We could
+ *   plumb a `note` here, but the spec only requires the warning side
+ *   of the contract; an "all good" line would just be noise on the
+ *   common path.)
+ * - `below-minimum` — warning regardless of `--strict-probe`. The
+ *   probe ran successfully and found an old server; that is not a
+ *   probe *failure* (which is what `--strict-probe` escalates), it
+ *   is the probe doing its job.
+ * - `no-database-url` / `connection-failed` / `driver-missing` —
+ *   warning by default, fatal under `--strict-probe`.
+ *
+ * Exported for unit tests so the branching contract can be asserted
+ * without spinning up a full `runInit` round trip.
+ */
+export function applyProbeOutcome(
+  outcome: ProbeOutcome,
+  ctx: { readonly strictProbe: boolean; readonly warnings: string[] },
+): string | null {
+  switch (outcome.kind) {
+    case 'ok':
+      return null;
+    case 'below-minimum':
+      ctx.warnings.push(outcome.message);
+      return null;
+    case 'no-database-url':
+    case 'connection-failed':
+    case 'driver-missing':
+      if (ctx.strictProbe) {
+        return outcome.message;
+      }
+      ctx.warnings.push(outcome.message);
+      return null;
+  }
+}
+
+/**
+ * Drives the `pnpm add` / `npm install` step. Failures are escalated to
+ * a structured `errorInitInstallFailed` (exit code 4) — the spec treats
+ * an unrecoverable install as a hard outcome rather than a warning so
+ * CI/agents can branch on the exit code (FR1.6).
+ *
+ * For pnpm specifically, we additionally implement the FR7.2 fallback:
+ * if pnpm fails with a recognised workspace/catalog resolution error
+ * class (typically caused by a registry version that leaked
+ * `workspace:*` or `catalog:` specifiers), we retry the install using
+ * `npm` and surface a non-fatal warning explaining the swap.
+ */
+async function runInstall(ctx: {
+  readonly baseDir: string;
+  readonly pm: Awaited<ReturnType<typeof detectPackageManager>>;
+  readonly target: ResolvedInitInputs['target'];
+  readonly install: boolean;
+  readonly flags: GlobalFlags;
+  readonly ui: TerminalUI;
+  readonly filesWritten: readonly string[];
+  /**
+   * FR2.1 — set when the user already declares `@types/node` directly in
+   * `dependencies` or `devDependencies`. We then skip adding it so a
+   * pinned major (e.g. `^18` for a Node 18 runtime) survives `init`
+   * unchanged. Transitive presence is intentionally ignored: detecting
+   * it requires lockfile introspection and the realistic clobber risk
+   * is the direct-pin case.
+   */
+  readonly hasTypesNode: boolean;
+}): Promise<InstallReport> {
+  const { baseDir, pm, target, install, flags, ui, filesWritten, hasTypesNode } = ctx;
+  const pkg = targetPackageName(target);
+  const deps = [pkg, 'dotenv'];
+  // FR2.1: under `moduleResolution: 'bundler'` (FR2.2) the scaffolded
+  // `db.ts` / `prisma-next.config.ts` reference `process.env`, which
+  // only typechecks with Node's ambient types in the resolution graph.
+  // Pin it as a devDep rather than relying on a transitive resolution
+  // through `dotenv` (whose types bundle is internal and not guaranteed
+  // across versions). Skip when the user already declares `@types/node`
+  // directly so a pinned major (e.g. `^18` for a Node 18 runtime) is
+  // preserved. Listed last so the install log still leads with the
+  // user-relevant `prisma-next` line.
+  const devDeps = hasTypesNode ? ['prisma-next'] : ['prisma-next', '@types/node'];
+
+  const addCommand = `${pm} ${formatAddArgs(pm, deps).join(' ')}`;
+  const addDevCommand = `${pm} ${formatAddDevArgs(pm, devDeps).join(' ')}`;
+  const emitCommand = formatRunCommand(pm, 'prisma-next', 'contract emit');
+
+  // FR7.3 / Spec Decision 8 — honour-and-warn: if the surrounding pnpm
+  // workspace pins one of our packages via the catalog, surface a
+  // structured warning so the user knows the catalog version (not the
+  // published `latest`) is what ends up installed. We collect the
+  // warning whether or not we actually run install — the override
+  // applies to a manual install too — but only when pnpm is the chosen
+  // PM (catalog: specifiers are pnpm-specific).
+  const catalogWarnings = pm === 'pnpm' ? buildCatalogWarnings(baseDir, [...deps, ...devDeps]) : [];
+
+  if (!install) {
+    if (!flags.json && !flags.quiet) {
+      ui.note(
         [
-          'Could not install dependencies automatically.',
-          ...(stderr ? [`  ${stderr.trim()}`] : []),
+          'Run the following commands to complete setup:',
           '',
-          'Run manually:',
-          `  ${pm} ${formatAddArgs(pm, [pkg, 'dotenv']).join(' ')}`,
-          `  ${pm} ${formatAddDevArgs(pm, ['prisma-next']).join(' ')}`,
+          '  1. Install dependencies:',
+          `     ${addCommand}`,
+          `     ${addDevCommand}`,
+          '',
+          '  2. Emit the contract:',
+          `     ${emitCommand}`,
         ].join('\n'),
+        'Manual steps',
       );
     }
+    return { skipped: true, deps: [], devDeps: [], warnings: catalogWarnings };
+  }
 
-    if (installSucceeded) {
-      spinner.start('Emitting contract...');
+  const exec = promisify(execFile);
+  const runPair = async (manager: PackageManager): Promise<void> => {
+    await exec(manager, formatAddArgs(manager, deps), { cwd: baseDir });
+    await exec(manager, formatAddDevArgs(manager, devDeps), { cwd: baseDir });
+  };
+
+  const allPackages = [...deps, ...devDeps].join(', ');
+  const spinner = ui.spinner();
+  spinner.start(`Installing ${allPackages}...`);
+  try {
+    await runPair(pm);
+    spinner.stop(`Installed ${allPackages}`);
+    return { skipped: false, deps, devDeps, warnings: catalogWarnings };
+  } catch (err) {
+    const stderrText = redactSecrets(readChildStderr(err));
+
+    // FR7.2: detect a recognised pnpm workspace/catalog resolution error
+    // and fall back to npm. Limited to pnpm specifically; npm/yarn/bun/deno
+    // failures escalate straight to a structured install error.
+    if (pm === 'pnpm' && isRecognisedPnpmResolutionError(stderrText)) {
+      spinner.message(
+        'pnpm could not resolve a workspace/catalog dependency, retrying with npm...',
+      );
       try {
-        const { executeContractEmit } = await import('../../control-api/operations/contract-emit');
-        const configFilePath = join(baseDir, 'prisma-next.config.ts');
-        await executeContractEmit({ configPath: configFilePath });
-        spinner.stop('Contract emitted');
-      } catch {
-        spinner.stop('Contract emission failed');
-        ui.warn(
-          ['Could not emit contract automatically. Run manually:', `  ${emitCommand}`].join('\n'),
-        );
+        await runPair('npm');
+        spinner.stop(`Installed ${allPackages} via npm (pnpm fallback)`);
+        const fallbackWarning = [
+          'pnpm could not install: a published Prisma Next dependency leaked a `workspace:*` or `catalog:` specifier.',
+          'Falling back to `npm install` so init can complete.',
+          stderrText ? `  pnpm error: ${stderrText.trim().split('\n')[0]}` : '',
+          'Once the offending package republishes a clean version, re-run `pnpm install` to switch back.',
+        ]
+          .filter(Boolean)
+          .join('\n');
+        return {
+          skipped: false,
+          deps,
+          devDeps,
+          // The pnpm fallback fired, so the workspace catalog is not the
+          // version that was actually installed (npm bypassed pnpm's
+          // resolver). Surface the fallback warning but suppress the
+          // catalog-honour warning to avoid a contradictory message
+          // pair.
+          warnings: [fallbackWarning],
+        };
+      } catch (npmErr) {
+        spinner.stop('Installation failed');
+        const npmStderr = redactSecrets(readChildStderr(npmErr));
+        throw errorInitInstallFailed({
+          addCommand,
+          addDevCommand,
+          emitCommand,
+          filesWritten,
+          stderrLines: [stderrText, npmStderr],
+        });
       }
     }
+
+    spinner.stop('Installation failed');
+    throw errorInitInstallFailed({
+      addCommand,
+      addDevCommand,
+      emitCommand,
+      filesWritten,
+      stderrLines: [stderrText],
+    });
+  }
+}
+
+/**
+ * Builds the FR7.3 catalog-honoured warning(s) for the surrounding pnpm
+ * workspace, if any. Returns an empty array when no `pnpm-workspace.yaml`
+ * exists in any ancestor or when the workspace's catalog has no entry
+ * for any of the packages `init` is about to install.
+ *
+ * Exported for unit tests.
+ */
+export function buildCatalogWarnings(
+  baseDir: string,
+  packages: readonly string[],
+): readonly string[] {
+  const result = detectPnpmCatalogOverrides(baseDir, packages);
+  if (result === null || result.entries.length === 0) {
+    return [];
   }
+  return [formatCatalogWarning(result.workspaceFile, result.entries)];
+}
+
+function formatCatalogWarning(
+  workspaceFile: string,
+  entries: readonly PnpmCatalogOverride[],
+): string {
+  const list = entries.map((entry) => `  • ${entry.name}: ${entry.version}`).join('\n');
+  return [
+    'pnpm workspace catalog overrides detected — pnpm will install these versions instead of `latest`:',
+    list,
+    `Catalog source: ${workspaceFile}`,
+    'To use the published `latest` instead, remove or update the catalog entry, then re-run `pnpm install`.',
+  ].join('\n');
+}
+
+/**
+ * Recognised pnpm error signatures that justify a fallback to npm.
+ *
+ * These patterns indicate the published artefact itself is at fault
+ * (a leaked `workspace:*` or `catalog:` specifier), not the user's
+ * environment — pnpm is faithfully reporting "I cannot resolve this
+ * registry version", and npm is willing to install it because npm
+ * doesn't care about the protocol prefix when there's a fallback range.
+ *
+ * Exported for unit tests; do not depend on this from outside the init
+ * command.
+ */
+export function isRecognisedPnpmResolutionError(stderr: string): boolean {
+  if (!stderr) return false;
+  return (
+    stderr.includes('ERR_PNPM_WORKSPACE_PKG_NOT_FOUND') ||
+    stderr.includes('ERR_PNPM_NO_MATCHING_VERSION') ||
+    /No matching version found for .* in the catalog/i.test(stderr) ||
+    /workspace:[^\s]+ is not a valid (version|spec)/i.test(stderr) ||
+    /catalog:[^\s]* is not a valid (version|spec)/i.test(stderr)
+  );
+}
+
+/**
+ * FR2.1 — true when the parsed `package.json` declares `name` directly
+ * in either `dependencies` or `devDependencies`. We deliberately don't
+ * inspect `peerDependencies` (irrelevant for a leaf project) or the
+ * lockfile (transitive presence is brittle to detect and not the
+ * realistic clobber-risk path).
+ *
+ * Exported for unit tests.
+ */
+export function hasDirectDep(parsed: Record<string, unknown>, name: string): boolean {
+  for (const field of ['dependencies', 'devDependencies'] as const) {
+    const value = parsed[field];
+    if (value !== null && typeof value === 'object' && name in value) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function readChildStderr(err: unknown): string {
+  if (err instanceof Error && 'stderr' in err) {
+    return String((err as { stderr: string }).stderr ?? '');
+  }
+  return '';
+}
+
+/**
+ * Redacts userinfo (`user:password@`) from any URL-shaped substring inside
+ * package-manager stderr before we surface it in a warning or error
+ * meta. pnpm and npm both include the offending registry URL in resolve
+ * errors, and that URL can carry an auth token (e.g. corporate registry
+ * mirrors that bake `_authToken` into the URL). The Style Guide
+ * (Testing & Accessibility — "Security: never print secrets") requires
+ * we never surface those.
+ *
+ * Exported for unit tests.
+ */
+export function redactSecrets(stderr: string): string {
+  if (!stderr) return stderr;
+  // Match `scheme://userinfo@host…` and replace the userinfo with `***`.
+  return stderr.replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^/@\s]+)@/g, '$1***@');
+}
+
+/**
+ * Drives `prisma-next contract emit` against the freshly scaffolded
+ * project. On failure, throws `errorInitEmitFailed` with the underlying
+ * cause embedded in `meta.cause` so the user can re-run with `-v` to see
+ * the full envelope and follow the fix steps. Maps to exit code
+ * `5 = EMIT_FAILED` (FR1.6).
+ */
+async function runEmit(ctx: {
+  readonly baseDir: string;
+  readonly ui: TerminalUI;
+  readonly filesWritten: readonly string[];
+  readonly emitCommand: string;
+}): Promise<void> {
+  const spinner = ctx.ui.spinner();
+  spinner.start('Emitting contract...');
+  try {
+    const { executeContractEmit } = await import('../../control-api/operations/contract-emit');
+    const configFilePath = join(ctx.baseDir, 'prisma-next.config.ts');
+    await executeContractEmit({ configPath: configFilePath });
+    spinner.stop('Contract emitted');
+  } catch (err) {
+    spinner.stop('Contract emission failed');
+    throw errorInitEmitFailed({
+      emitCommand: ctx.emitCommand,
+      filesWritten: ctx.filesWritten,
+      cause: causeMessage(err),
+    });
+  }
+}
 
-  clack.outro('Done! Open prisma-next.md to get started.', { output: process.stderr });
+function causeMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
 }