@prisma-next/cli 0.10.0 → 0.11.0-dev.10

package/src/cli.ts

@@ -27,6 +27,7 @@ import { setCommandDescriptions } from './utils/command-helpers';
 import { formatCommandHelp, formatRootHelp } from './utils/formatters/help';
 import { parseGlobalFlags } from './utils/global-flags';
 import { suggestCommands } from './utils/suggest-command';
+import { fireTelemetryFromPreAction } from './utils/telemetry';
 
 /**
  * Lookup table mapping removed subcommands to their replacement verbs.
@@ -68,6 +69,21 @@ const program = new Command();
 
 program.name('prisma-next').description('Prisma Next CLI').version(packageJson.version);
 
+// Telemetry hook — fires at command start, before the action body
+// runs. Synchronous by construction: `fireTelemetryFromPreAction`
+// resolves gates (cheap), then `fork()`s the detached sender. The
+// fork is enqueued before the action body runs at all, so the child
+// survives even when the action throws synchronously. The try/catch
+// is defence-in-depth — `runTelemetry` already swallows every failure
+// mode internally and returns an outcome instead of throwing.
+program.hook('preAction', (_thisCommand, actionCommand) => {
+  try {
+    fireTelemetryFromPreAction(actionCommand);
+  } catch {
+    // defence-in-depth — runTelemetry already swallows internally.
+  }
+});
+
 // Override version option description to match capitalization style
 const versionOption = program.options.find((opt) => opt.flags.includes('--version'));
 if (versionOption) {
@@ -302,6 +318,32 @@ program.addCommand(dbCommand);
 program.addCommand(migrationCommand);
 program.addCommand(refCommand);
 
+// Test-only hidden command used by `cli-telemetry`'s `cli-e2e.test.ts`
+// to verify that telemetry still lands when a CLI command crashes
+// mid-execution. The preAction hook is synchronous and `fork()`s the
+// detached sender before this action body runs; the small sleep
+// gives the IPC `child.send()` a tick to flush before the throw
+// triggers commander's `exitOverride` and `process.exit(1)`. Hidden
+// from help; underscore prefix marks it as internal. Doesn't depend
+// on any project state, so it runs in any tempdir.
+//
+// Gated behind `PRISMA_NEXT_ENABLE_TEST_COMMANDS=1` so the command is
+// not even registered (and therefore not invocable) in shipped
+// binaries. `hidden: true` only filters the help output; without this
+// env gate the command would still be callable from production. The
+// e2e suite sets the env var when it spawns the CLI.
+const TELEMETRY_CRASH_TEST_SLEEP_MS = 200;
+if (process.env['PRISMA_NEXT_ENABLE_TEST_COMMANDS'] === '1') {
+  const telemetryCrashTestCommand = new Command('__telemetry-crash-test')
+    .description('Internal: deliberately throw for the telemetry e2e suite.')
+    .action(async () => {
+      await new Promise((settle) => setTimeout(settle, TELEMETRY_CRASH_TEST_SLEEP_MS));
+      throw new Error('__telemetry-crash-test: intentional crash for e2e coverage');
+    });
+  telemetryCrashTestCommand.configureHelp({ visibleCommands: () => [] });
+  program.addCommand(telemetryCrashTestCommand, { hidden: true });
+}
+
 // Create help command
 const helpCommand = new Command('help')
   .description('Show usage instructions')

package/src/commands/contract-emit.ts

@@ -3,7 +3,7 @@ import { errorContractConfigMissing } from '@prisma-next/errors/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
-import { dirname, relative, resolve } from 'pathe';
+import { dirname, join, relative, resolve } from 'pathe';
 import { loadConfig } from '../config-loader';
 import { executeContractEmit } from '../control-api/operations/contract-emit';
 import type { ContractEmitResult } from '../control-api/types';
@@ -20,13 +20,14 @@ import {
 } from '../utils/formatters/emit';
 import { formatStyledHeader, formatSuccessMessage } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { createProgressAdapter } from '../utils/progress-adapter';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface ContractEmitOptions extends CommonCommandOptions {
   readonly config?: string;
+  readonly outputPath?: string;
 }
 
 interface HeaderPaths {
@@ -43,6 +44,7 @@ interface HeaderPaths {
  */
 async function resolveHeaderPaths(
   configOption: string | undefined,
+  outputPath: string | undefined,
 ): Promise<Result<HeaderPaths, CliStructuredError>> {
   const displayConfigPath = configOption
     ? relative(process.cwd(), resolve(configOption))
@@ -62,7 +64,10 @@ async function resolveHeaderPaths(
     );
   }
 
-  if (!config.contract?.output) {
+  const effectiveJsonPath =
+    outputPath !== undefined ? join(outputPath, 'contract.json') : config.contract?.output;
+
+  if (!effectiveJsonPath) {
     return notOk(
       errorContractConfigMissing({
         why: 'Config.contract.output is required for emit. Define it in your config: contract: { source: ..., output: ... }',
@@ -71,9 +76,8 @@ async function resolveHeaderPaths(
   }
 
   try {
-    const { jsonPath: outputJsonPath, dtsPath: outputDtsPath } = getEmittedArtifactPaths(
-      config.contract.output,
-    );
+    const { jsonPath: outputJsonPath, dtsPath: outputDtsPath } =
+      getEmittedArtifactPaths(effectiveJsonPath);
     return ok({ displayConfigPath, outputJsonPath, outputDtsPath });
   } catch (error) {
     return notOk(
@@ -90,7 +94,9 @@ async function executeContractEmitCommand(
   ui: TerminalUI,
   startTime: number,
 ): Promise<Result<EmitContractResult, CliStructuredError>> {
-  const headerPathsResult = await resolveHeaderPaths(options.config);
+  const outputPath = options.outputPath !== undefined ? resolve(options.outputPath) : undefined;
+
+  const headerPathsResult = await resolveHeaderPaths(options.config, outputPath);
   if (!headerPathsResult.ok) {
     return headerPathsResult;
   }
@@ -117,7 +123,11 @@ async function executeContractEmitCommand(
 
   let result: ContractEmitResult;
   try {
-    result = await executeContractEmit({ configPath, onProgress });
+    result = await executeContractEmit({
+      configPath,
+      onProgress,
+      ...ifDefined('outputPath', outputPath),
+    });
   } catch (error) {
     if (CliStructuredError.is(error)) {
       return notOk(error);
@@ -155,12 +165,14 @@ export function createContractEmitCommand(): Command {
   setCommandExamples(command, [
     'prisma-next contract emit',
     'prisma-next contract emit --config ./custom-config.ts',
+    'prisma-next contract emit --output-path ./generated',
   ]);
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
+    .option('--output-path <dir>', 'Directory to write contract.json and contract.d.ts into')
     .action(async (options: ContractEmitOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const startTime = Date.now();
 
       const result = await executeContractEmitCommand(options, flags, ui, startTime);

package/src/commands/contract-infer.ts

@@ -10,9 +10,9 @@ import {
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
-import { parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 import { resolveContractInferOutputPath } from './contract-infer-paths';
 import {
   type InspectLiveSchemaOptions,
@@ -39,10 +39,10 @@ interface ContractInferSuccessResult {
 
 async function executeContractInferCommand(
   options: ContractInferOptions,
+  flags: GlobalFlags,
   ui: TerminalUI,
   startTime: number,
 ): Promise<Result<ContractInferSuccessResult, CliStructuredError>> {
-  const flags = parseGlobalFlags(options);
   const inspectResult = await inspectLiveSchema(options, flags, ui, startTime, {
     commandName: 'contract infer',
     description: 'Infer a PSL contract from the live database schema',
@@ -104,7 +104,7 @@ export function createContractInferCommand(): Command {
   );
   setCommandExamples(command, [
     'prisma-next contract infer --db $DATABASE_URL',
-    'prisma-next contract infer --db $DATABASE_URL --output ./prisma/contract.prisma',
+    'prisma-next contract infer --db $DATABASE_URL --output ./src/prisma/contract.prisma',
     'prisma-next contract infer --db $DATABASE_URL --json',
   ]);
   addGlobalOptions(command)
@@ -112,11 +112,11 @@ export function createContractInferCommand(): Command {
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .option('--output <path>', 'Write the inferred PSL contract to the specified path')
     .action(async (options: ContractInferOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const startTime = Date.now();
 
-      const result = await executeContractInferCommand(options, ui, startTime);
+      const result = await executeContractInferCommand(options, flags, ui, startTime);
       const exitCode = handleResult(result, flags, ui, (value) => {
         if (flags.json) {
           ui.output(JSON.stringify(value, null, 2));

package/src/commands/db-init.ts

@@ -1,3 +1,4 @@
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
@@ -10,6 +11,7 @@ import {
   errorRunnerFailed,
   errorRuntime,
   errorUnexpected,
+  mapMigrationToolsError,
 } from '../utils/cli-errors';
 import type { MigrationCommandOptions } from '../utils/command-helpers';
 import {
@@ -24,15 +26,23 @@ import {
   formatMigrationPlanOutput,
   type MigrationCommandResult,
 } from '../utils/formatters/migrations';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import {
   addMigrationCommandOptions,
   prepareMigrationContext,
 } from '../utils/migration-command-scaffold';
+import {
+  buildRefAdvancementFields,
+  computeRefAdvancementName,
+  type RefAdvancementFields,
+  readContractIR,
+} from '../utils/ref-advancement';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
-type DbInitOptions = MigrationCommandOptions;
+interface DbInitOptions extends MigrationCommandOptions {
+  readonly advanceRef?: string;
+}
 
 /**
  * Maps a DbInitFailure to a CliStructuredError for consistent error handling.
@@ -80,9 +90,17 @@ function mapDbInitFailure(failure: DbInitFailure): CliStructuredError {
   }
 
   if (failure.code === 'RUNNER_FAILED') {
+    const runnerCode =
+      typeof failure.meta?.['runnerErrorCode'] === 'string'
+        ? failure.meta['runnerErrorCode']
+        : undefined;
+    const fix =
+      runnerCode === 'LEGACY_MARKER_SHAPE'
+        ? 'Legacy marker-table shape detected. Drop `prisma_contract.marker` (Postgres) or `_prisma_marker` (SQLite) and re-run `prisma-next db init` to recreate it with the current per-space schema.'
+        : 'Fix the schema mismatch (db init is additive-only), or drop/reset the database and re-run `prisma-next db init`';
     return errorRunnerFailed(failure.summary, {
       why: failure.why ?? 'Migration runner failed',
-      fix: 'Fix the schema mismatch (db init is additive-only), or drop/reset the database and re-run `prisma-next db init`',
+      fix,
       ...(failure.meta
         ? { meta: { code: 'RUNNER_FAILED', ...failure.meta } }
         : { meta: { code: 'RUNNER_FAILED' } }),
@@ -120,7 +138,7 @@ async function executeDbInitCommand(
   // per-space precheck + marker-check helpers are no longer needed at
   // this surface. Marker-vs-on-disk drift surfaces through the planner's
   // graph-walk strategy.
-  const { migrationsDir } = resolveMigrationPaths(options.config, config);
+  const { migrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
 
   try {
     await client.connect(dbConnection);
@@ -137,6 +155,39 @@ async function executeDbInitCommand(
       return notOk(mapDbInitFailure(result.failure));
     }
 
+    const advancementHash =
+      result.value.mode === 'apply'
+        ? (result.value.marker?.storageHash ?? result.value.destination.storageHash)
+        : result.value.destination.storageHash;
+
+    let refAdvancementFields: RefAdvancementFields = {
+      advancedRef: null,
+      plannedAdvanceRef: null,
+    };
+    if (
+      computeRefAdvancementName({
+        ...ifDefined('advanceRef', options.advanceRef),
+        ...ifDefined('db', options.db),
+      }) !== null
+    ) {
+      try {
+        const contractIR = await readContractIR(contractJson, contractPathAbsolute);
+        refAdvancementFields = await buildRefAdvancementFields({
+          ...ifDefined('advanceRef', options.advanceRef),
+          ...ifDefined('db', options.db),
+          refsDir,
+          contractIR,
+          mode: result.value.mode,
+          hash: advancementHash,
+        });
+      } catch (error) {
+        if (MigrationToolsError.is(error)) {
+          return notOk(mapMigrationToolsError(error));
+        }
+        throw error;
+      }
+    }
+
     // Convert success result to CLI output format
     const dbInitResult: MigrationCommandResult = {
       ok: true,
@@ -171,6 +222,8 @@ async function executeDbInitCommand(
           }
         : {}),
       ...ifDefined('perSpace', result.value.perSpace),
+      advancedRef: refAdvancementFields.advancedRef,
+      plannedAdvanceRef: refAdvancementFields.plannedAdvanceRef,
       summary: result.value.summary,
       timings: { total: Date.now() - startTime },
     };
@@ -221,11 +274,12 @@ export function createDbInitCommand(): Command {
     'prisma-next db init --db $DATABASE_URL --dry-run',
   ]);
   addMigrationCommandOptions(command);
+  command.option('--advance-ref <name>', 'Ref to advance to the post-command contract hash');
   command.action(async (options: DbInitOptions) => {
-    const flags = parseGlobalFlags(options);
+    const flags = parseGlobalFlagsOrExit(options);
     const startTime = Date.now();
 
-    const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+    const ui = createTerminalUI(flags);
 
     const result = await executeDbInitCommand(options, flags, ui, startTime);
 

package/src/commands/db-schema.ts

@@ -6,9 +6,9 @@ import {
   setCommandExamples,
 } from '../utils/command-helpers';
 import { formatIntrospectJson, formatIntrospectOutput } from '../utils/formatters/verify';
-import { parseGlobalFlags } from '../utils/global-flags';
+import { parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI } from '../utils/terminal-ui';
 import {
   type InspectLiveSchemaOptions,
   type InspectLiveSchemaResult,
@@ -46,8 +46,8 @@ export function createDbSchemaCommand(): Command {
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: InspectLiveSchemaOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const startTime = Date.now();
 
       const result = await inspectLiveSchema(options, flags, ui, startTime, {

package/src/commands/db-sign.ts

@@ -40,10 +40,10 @@ import {
   formatSignOutput,
 } from '../utils/formatters/verify';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { createProgressAdapter } from '../utils/progress-adapter';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface DbSignOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -270,7 +270,7 @@ export function createDbSignCommand(): Command {
       'Contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
     )
     .action(async (positionalContract: string | undefined, options: DbSignOptions) => {
-      const flags = parseGlobalFlags(options);
+      const flags = parseGlobalFlagsOrExit(options);
 
       if (positionalContract && options.contract) {
         process.stderr.write(
@@ -280,7 +280,7 @@ export function createDbSignCommand(): Command {
         return;
       }
 
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const ui = createTerminalUI(flags);
 
       const result = await executeDbSignCommand(positionalContract, options, flags, ui);
 

package/src/commands/db-update.ts

@@ -33,16 +33,23 @@ import {
   formatMigrationPlanOutput,
   type MigrationCommandResult,
 } from '../utils/formatters/migrations';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import {
   addMigrationCommandOptions,
   prepareMigrationContext,
 } from '../utils/migration-command-scaffold';
+import {
+  buildRefAdvancementFields,
+  computeRefAdvancementName,
+  type RefAdvancementFields,
+  readContractIR,
+} from '../utils/ref-advancement';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface DbUpdateOptions extends MigrationCommandOptions {
   readonly to?: string;
+  readonly advanceRef?: string;
 }
 
 /**
@@ -54,9 +61,17 @@ function mapDbUpdateFailure(failure: DbUpdateFailure): CliStructuredError {
   }
 
   if (failure.code === 'RUNNER_FAILED') {
+    const runnerCode =
+      typeof failure.meta?.['runnerErrorCode'] === 'string'
+        ? failure.meta['runnerErrorCode']
+        : undefined;
+    const fix =
+      runnerCode === 'LEGACY_MARKER_SHAPE'
+        ? 'Legacy marker-table shape detected. Drop `prisma_contract.marker` (Postgres) or `_prisma_marker` (SQLite) and re-run `prisma-next db init` to recreate it with the current per-space schema.'
+        : 'Inspect the reported conflict, reconcile schema drift if needed, then re-run `prisma-next db update`';
     return errorRunnerFailed(failure.summary, {
       why: failure.why ?? 'Migration runner failed',
-      fix: 'Inspect the reported conflict, reconcile schema drift if needed, then re-run `prisma-next db update`',
+      fix,
       ...ifDefined('meta', failure.meta),
     });
   }
@@ -93,6 +108,7 @@ async function executeDbUpdateCommand(
   }
   const { client, config, dbConnection, onProgress, contractPathAbsolute } = ctxResult.value;
   let { contractJson } = ctxResult.value;
+  let contractJsonPathForSnapshot = contractPathAbsolute;
   const { migrationsDir, appMigrationsDir, refsDir } = resolveMigrationPaths(
     options.config,
     config,
@@ -122,6 +138,7 @@ async function executeDbUpdateCommand(
       const endContractPath = join(matchingBundle.dirPath, 'end-contract.json');
       const raw = await readFile(endContractPath, 'utf-8');
       contractJson = JSON.parse(raw) as Record<string, unknown>;
+      contractJsonPathForSnapshot = endContractPath;
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));
@@ -149,6 +166,39 @@ async function executeDbUpdateCommand(
       return notOk(mapDbUpdateFailure(result.failure));
     }
 
+    const advancementHash =
+      result.value.mode === 'apply'
+        ? (result.value.marker?.storageHash ?? result.value.destination.storageHash)
+        : result.value.destination.storageHash;
+
+    let refAdvancementFields: RefAdvancementFields = {
+      advancedRef: null,
+      plannedAdvanceRef: null,
+    };
+    if (
+      computeRefAdvancementName({
+        ...ifDefined('advanceRef', options.advanceRef),
+        ...ifDefined('db', options.db),
+      }) !== null
+    ) {
+      try {
+        const contractIR = await readContractIR(contractJson, contractJsonPathForSnapshot);
+        refAdvancementFields = await buildRefAdvancementFields({
+          ...ifDefined('advanceRef', options.advanceRef),
+          ...ifDefined('db', options.db),
+          refsDir,
+          contractIR,
+          mode: result.value.mode,
+          hash: advancementHash,
+        });
+      } catch (error) {
+        if (MigrationToolsError.is(error)) {
+          return notOk(mapMigrationToolsError(error));
+        }
+        throw error;
+      }
+    }
+
     // Convert success result to CLI output format
     const dbUpdateResult: MigrationCommandResult = {
       ok: true,
@@ -185,6 +235,8 @@ async function executeDbUpdateCommand(
           : undefined,
       ),
       ...ifDefined('perSpace', result.value.perSpace),
+      advancedRef: refAdvancementFields.advancedRef,
+      plannedAdvanceRef: refAdvancementFields.plannedAdvanceRef,
       summary: result.value.summary,
       timings: { total: Date.now() - startTime },
     };
@@ -237,11 +289,12 @@ export function createDbUpdateCommand(): Command {
     '--to <contract>',
     'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
   );
+  command.option('--advance-ref <name>', 'Ref to advance to the post-command contract hash');
   command.action(async (options: DbUpdateOptions) => {
-    const flags = parseGlobalFlags(options);
+    const flags = parseGlobalFlagsOrExit(options);
     const startTime = Date.now();
 
-    const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+    const ui = createTerminalUI(flags);
 
     let result = await executeDbUpdateCommand(options, flags, ui, startTime);
 

package/src/commands/db-verify.ts

@@ -47,10 +47,10 @@ import {
   formatVerifyOutput,
 } from '../utils/formatters/verify';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { createProgressAdapter } from '../utils/progress-adapter';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface DbVerifyOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -331,7 +331,7 @@ function wrapVerifyError(
   contractPathAbsolute: string,
   modeLabel: string,
 ): Result<never, CliStructuredError> {
-  if (error instanceof CliStructuredError) {
+  if (CliStructuredError.is(error)) {
     return notOk(error);
   }
   if (error instanceof ContractValidationError) {
@@ -529,8 +529,8 @@ export function createDbVerifyCommand(): Command {
       false,
     )
     .action(async (options: DbVerifyOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
 
       const modeResult = resolveDbVerifyMode(options);
       if (!modeResult.ok) {

package/src/commands/init/detect-package-manager.ts

@@ -56,6 +56,21 @@ export function formatRunCommand(pm: PackageManager, bin: string, args: string):
   return `${pm} ${bin} ${args}`;
 }
 
+export function formatRunScriptCommand(pm: PackageManager, scriptName: string): string {
+  switch (pm) {
+    case 'deno':
+      return `deno task ${scriptName}`;
+    case 'bun':
+      return `bun run ${scriptName}`;
+    case 'pnpm':
+      return `pnpm run ${scriptName}`;
+    case 'yarn':
+      return `yarn run ${scriptName}`;
+    default:
+      return `npm run ${scriptName}`;
+  }
+}
+
 export function formatAddArgs(pm: PackageManager, packages: string[]): string[] {
   if (pm === 'deno') {
     return ['add', ...packages.map((p) => `npm:${p}`)];

package/src/commands/init/errors.ts

@@ -69,6 +69,37 @@ export function errorInitInvalidFlagValue(options: {
   });
 }
 
+/**
+ * `--authoring` and `--schema-path` disagree on file extension (e.g. PSL
+ * authoring with a `.ts` path). Surfaces before any scaffold files are
+ * written so the project tree stays untouched.
+ */
+export function errorInitAuthoringSchemaPathMismatch(options: {
+  readonly authoring: 'psl' | 'typescript';
+  readonly schemaPath: string;
+  readonly actualExtension: string;
+  readonly expectedExtension: string;
+}): CliStructuredError {
+  const expectedAuthoring = options.expectedExtension === '.ts' ? 'typescript' : 'psl';
+  return new CliStructuredError('5014', 'Authoring and schema path do not match', {
+    domain: 'CLI',
+    why:
+      `\`--authoring ${options.authoring}\` requires a schema file ending in ${options.expectedExtension}, ` +
+      `but \`--schema-path ${options.schemaPath}\` ends in ${options.actualExtension}.`,
+    fix:
+      `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',
+    meta: {
+      authoring: options.authoring,
+      schemaPath: options.schemaPath,
+      actualExtension: options.actualExtension,
+      expectedExtension: options.expectedExtension,
+    },
+  });
+}
+
 /**
  * The user cancelled an interactive prompt (Ctrl-C, escape, declined a
  * selection). Distinct from `errorInitReinitNeedsForce` because that path
@@ -238,7 +269,7 @@ export function errorInitEmitFailed(options: {
 }
 
 /**
- * The project-level agent-skill install (`npx skills add
+ * The project-level skills install (`npx skills add
  * prisma/prisma-next#v<version>`) failed after a successful dependency
  * install + emit. The project's scaffold remains on disk; the user
  * can either fix the underlying issue (network, registry, PATH) and
@@ -260,7 +291,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#agent-skill',
+    docsUrl: 'https://prisma-next.dev/docs/cli/init#skills',
     meta: {
       filesWritten: options.filesWritten,
       skillInstallCommand: options.skillInstallCommand,

package/src/commands/init/hygiene-gitattributes.ts

@@ -20,7 +20,7 @@ import type { TargetId } from './templates/code-templates';
  * `db/contract.json linguist-generated` — not the workspace-glob form
  * `<glob>/contract.json` (which would over-match any unrelated
  * `contract.json` the user has elsewhere) and not the absolute
- * `prisma/contract.json` (which would silently break for a non-default
+ * `DEFAULT_CONTRACT_SOURCE_DIR/contract.json` (which would silently break for a non-default
  * schema path).
  */
 const ARTEFACT_FILENAMES: readonly string[] = [
@@ -59,7 +59,7 @@ export function requiredGitattributesLines(
  *
  * Equivalence is exact-line: a user-customised line like
  * `prisma/*.json linguist-generated` is *not* recognised as covering
- * `prisma/contract.json linguist-generated`. We accept that
+ * `DEFAULT_CONTRACT_SOURCE_DIR/contract.json linguist-generated`. We accept that
  * over-specification — preserving the user's broad pattern *and*
  * appending the narrow one — because the narrow lines are what the
  * acceptance criteria pin (FR3.4 AC).