@prisma-next/cli 0.7.0 → 0.8.0-dev.10

package/src/cli.ts

@@ -12,17 +12,44 @@ import { createDbSchemaCommand } from './commands/db-schema';
 import { createDbSignCommand } from './commands/db-sign';
 import { createDbUpdateCommand } from './commands/db-update';
 import { createDbVerifyCommand } from './commands/db-verify';
-import { createMigrationApplyCommand } from './commands/migration-apply';
+import { createMigrateCommand } from './commands/migrate';
+import { createMigrationCheckCommand } from './commands/migration-check';
+import { createMigrationGraphCommand } from './commands/migration-graph';
+import { createMigrationListCommand } from './commands/migration-list';
+import { createMigrationLogCommand } from './commands/migration-log';
 import { createMigrationNewCommand } from './commands/migration-new';
 import { createMigrationPlanCommand } from './commands/migration-plan';
-import { createMigrationRefCommand } from './commands/migration-ref';
 import { createMigrationShowCommand } from './commands/migration-show';
 import { createMigrationStatusCommand } from './commands/migration-status';
+import { createRefCommand } from './commands/ref';
 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';
 
+/**
+ * Lookup table mapping removed subcommands to their replacement verbs.
+ * Keyed by `<parent>:<subcommand>` (e.g. `migration:apply`).
+ * The handler consults this before falling back to the fuzzy suggest engine.
+ */
+const removedVerbRedirects: Record<string, string> = {
+  'migration:apply': 'Use `prisma-next migrate --to <contract>` instead.',
+  'migration:ref': 'Use `prisma-next ref set|list|delete` instead.',
+};
+
+/**
+ * Removed flags on specific subcommands. Keyed by `<parent>:<sub>:<flag>`.
+ * Checked during the pre-parse argv scan before commander sees the flags.
+ */
+const removedFlagRedirects: Record<string, string> = {
+  'migration:status:graph': 'Use `prisma-next migration graph` to view the migration graph.',
+  'migration:status:all':
+    'Use `prisma-next migration log --db <url>` to view the full execution history.',
+  'migration:status:limit':
+    'Use `prisma-next migration log --db <url>` to view the full execution history.',
+  'migration:status:ref': 'Use `--to <contract>` instead of `--ref`.',
+};
+
 /**
  * Formats the "Did you mean ...?" hint for an unknown command.
  */
@@ -177,9 +204,6 @@ contractCommand.addCommand(contractEmitCommand);
 const contractInferCommand = createContractInferCommand();
 contractCommand.addCommand(contractInferCommand);
 
-// Register contract command
-program.addCommand(contractCommand);
-
 // Register db subcommand
 const dbCommand = new Command('db');
 setCommandDescriptions(
@@ -216,9 +240,6 @@ dbCommand.addCommand(dbSchemaCommand);
 const dbSignCommand = createDbSignCommand();
 dbCommand.addCommand(dbSignCommand);
 
-// Register db command
-program.addCommand(dbCommand);
-
 // Register migration subcommand
 const migrationCommand = new Command('migration');
 setCommandDescriptions(
@@ -247,17 +268,38 @@ migrationCommand.addCommand(migrationShowCommand);
 const migrationStatusCommand = createMigrationStatusCommand();
 migrationCommand.addCommand(migrationStatusCommand);
 
-const migrationApplyCommand = createMigrationApplyCommand();
-migrationCommand.addCommand(migrationApplyCommand);
+const migrationLogCommand = createMigrationLogCommand();
+migrationCommand.addCommand(migrationLogCommand);
 
-const migrationRefCommand = createMigrationRefCommand();
-migrationCommand.addCommand(migrationRefCommand);
+const migrationListCommand = createMigrationListCommand();
+migrationCommand.addCommand(migrationListCommand);
 
-program.addCommand(migrationCommand);
+const migrationGraphCommand = createMigrationGraphCommand();
+migrationCommand.addCommand(migrationGraphCommand);
+
+const migrationCheckCommand = createMigrationCheckCommand();
+migrationCommand.addCommand(migrationCheckCommand);
+
+// Top-level migrate command
+const migrateCommand = createMigrateCommand();
 
-// Register init command (top-level, not nested)
+// Top-level ref command (replaces `migration ref`)
+const refCommand = createRefCommand();
+
+// Top-level init command
 const initCommand = createInitCommand();
+
+// Register top-level commands in the order the spec's intended-surface
+// diagram lists them: verbs (init, migrate) first, then subject
+// namespaces (contract, db, migration, ref). The order shows up in
+// `prisma-next --help` and is the first thing a new user sees, so it
+// matches the order spec.md uses to introduce the surface.
 program.addCommand(initCommand);
+program.addCommand(migrateCommand);
+program.addCommand(contractCommand);
+program.addCommand(dbCommand);
+program.addCommand(migrationCommand);
+program.addCommand(refCommand);
 
 // Create help command
 const helpCommand = new Command('help')
@@ -324,7 +366,28 @@ if (args.length > 0) {
       const helpText = formatRootHelp({ program, flags });
       process.stderr.write(`${helpText}\n`);
       process.exit(2);
-    } else if (command.commands.length > 0 && args.length === 1) {
+    } else if (command.commands.length > 0 && args.length >= 2) {
+      const subcommandName = args[1];
+      const redirectKey = `${commandName}:${subcommandName}`;
+      const redirect = removedVerbRedirects[redirectKey];
+      if (redirect) {
+        process.stderr.write(`Unknown command: ${subcommandName}\n${redirect}\n`);
+        process.exit(2);
+      }
+      for (let i = 2; i < args.length; i++) {
+        const arg = args[i]!;
+        if (!arg.startsWith('--')) continue;
+        const flagName = arg.slice(2);
+        const flagKey = `${commandName}:${subcommandName}:${flagName}`;
+        const flagRedirect = removedFlagRedirects[flagKey];
+        if (flagRedirect) {
+          process.stderr.write(`Unknown option: ${arg}\n${flagRedirect}\n`);
+          process.exit(2);
+        }
+      }
+    }
+
+    if (command.commands.length > 0 && args.length === 1) {
       // Parent command called with no subcommand. Same shape as the
       // no-args case above: the user did not request help, we are
       // voluntarily rendering it as decoration around an underspecified

package/src/commands/db-sign.ts

@@ -3,9 +3,12 @@ import type {
   SignDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
+import { readRefs } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
-import { relative, resolve } from 'pathe';
+import { join, relative, resolve } from 'pathe';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import { ContractValidationError } from '../control-api/errors';
@@ -15,12 +18,17 @@ import {
   errorDatabaseConnectionRequired,
   errorDriverRequired,
   errorFileNotFound,
+  errorRuntime,
   errorUnexpected,
+  mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
+  loadMigrationPackages,
   maskConnectionUrl,
   resolveContractPath,
+  resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
@@ -40,6 +48,7 @@ import { TerminalUI } from '../utils/terminal-ui';
 interface DbSignOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
+  readonly contract?: string;
 }
 
 /**
@@ -54,11 +63,11 @@ type DbSignFailure = CliStructuredError | VerifyDatabaseSchemaResult;
  * Failure: CliStructuredError (infra error) or VerifyDatabaseSchemaResult (schema mismatch)
  */
 async function executeDbSignCommand(
+  contractArg: string | undefined,
   options: DbSignOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<SignDatabaseResult, DbSignFailure>> {
-  // Load config
   const config = await loadConfig(options.config);
   const configPath = options.config
     ? relative(process.cwd(), resolve(options.config))
@@ -66,11 +75,12 @@ async function executeDbSignCommand(
   const contractPathAbsolute = resolveContractPath(config);
   const contractPath = relative(process.cwd(), contractPathAbsolute);
 
-  // Output header
+  const effectiveContractArg = contractArg ?? options.contract;
+
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
       { label: 'config', value: configPath },
-      { label: 'contract', value: contractPath },
+      { label: 'contract', value: effectiveContractArg ?? contractPath },
     ];
     if (options.db) {
       details.push({ label: 'database', value: maskConnectionUrl(options.db) });
@@ -85,36 +95,79 @@ async function executeDbSignCommand(
     ui.stderr(header);
   }
 
-  // Load contract file
-  let contractJsonContent: string;
-  try {
-    contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
-  } catch (error) {
-    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+  let contractJson: Record<string, unknown>;
+
+  if (effectiveContractArg) {
+    try {
+      const { appMigrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
+      const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
+      const refs = await readRefs(refsDir);
+      const refResult = parseContractRef(effectiveContractArg, { graph, refs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
+      }
+      const targetHash = refResult.value.hash;
+      const matchingBundle = bundles.find((p) => p.metadata.to === targetHash);
+      if (matchingBundle) {
+        const endContractPath = join(matchingBundle.dirPath, 'end-contract.json');
+        const raw = await readFile(endContractPath, 'utf-8');
+        contractJson = JSON.parse(raw) as Record<string, unknown>;
+      } else {
+        const defaultRaw = await readFile(contractPathAbsolute, 'utf-8');
+        const defaultContract = JSON.parse(defaultRaw) as Record<string, unknown>;
+        const storageHash = (defaultContract['storage'] as Record<string, unknown> | undefined)?.[
+          'storageHash'
+        ];
+        if (storageHash === targetHash) {
+          contractJson = defaultContract;
+        } else {
+          return notOk(
+            errorRuntime(`No contract file found for hash "${targetHash}"`, {
+              why: `Resolved contract reference "${effectiveContractArg}" to hash "${targetHash}" but no migration produces that hash and the emitted contract does not match.`,
+              fix: 'Ensure the target contract exists on disk — either as a migration endpoint or as the emitted contract.json.',
+            }),
+          );
+        }
+      }
+    } catch (error) {
+      if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
+      if (error instanceof CliStructuredError) return notOk(error);
       return notOk(
-        errorFileNotFound(contractPathAbsolute, {
-          why: `Contract file not found at ${contractPathAbsolute}`,
-          fix: `Run \`prisma-next contract emit\` to generate ${contractPath}, or update \`config.contract.output\` in ${configPath}`,
+        errorUnexpected(error instanceof Error ? error.message : String(error), {
+          why: `Failed to resolve contract reference: ${error instanceof Error ? error.message : String(error)}`,
+        }),
+      );
+    }
+  } else {
+    let contractJsonContent: string;
+    try {
+      contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
+    } catch (error) {
+      if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+        return notOk(
+          errorFileNotFound(contractPathAbsolute, {
+            why: `Contract file not found at ${contractPathAbsolute}`,
+            fix: `Run \`prisma-next contract emit\` to generate ${contractPath}, or update \`config.contract.output\` in ${configPath}`,
+          }),
+        );
+      }
+      return notOk(
+        errorUnexpected(error instanceof Error ? error.message : String(error), {
+          why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}`,
         }),
       );
     }
-    return notOk(
-      errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}`,
-      }),
-    );
-  }
 
-  let contractJson: Record<string, unknown>;
-  try {
-    contractJson = JSON.parse(contractJsonContent) as Record<string, unknown>;
-  } catch (error) {
-    return notOk(
-      errorContractValidationFailed(
-        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
-        { where: { path: contractPathAbsolute } },
-      ),
-    );
+    try {
+      contractJson = JSON.parse(contractJsonContent) as Record<string, unknown>;
+    } catch (error) {
+      return notOk(
+        errorContractValidationFailed(
+          `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+          { where: { path: contractPathAbsolute } },
+        ),
+      );
+    }
   }
 
   // Resolve database connection (--db flag or config.db.connection)
@@ -203,16 +256,33 @@ export function createDbSignCommand(): Command {
       'in CI/deployment pipelines. The signature records that this database instance is aligned\n' +
       'with a specific contract version.',
   );
-  setCommandExamples(command, ['prisma-next db sign --db $DATABASE_URL']);
+  setCommandExamples(command, [
+    'prisma-next db sign --db $DATABASE_URL',
+    'prisma-next db sign production --db $DATABASE_URL',
+    'prisma-next db sign --contract production --db $DATABASE_URL',
+  ]);
   addGlobalOptions(command)
+    .argument('[contract]', 'Contract reference (hash, prefix, ref name, or migration dir name)')
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
-    .action(async (options: DbSignOptions) => {
+    .option(
+      '--contract <contract>',
+      'Contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
+    .action(async (positionalContract: string | undefined, options: DbSignOptions) => {
       const flags = parseGlobalFlags(options);
 
+      if (positionalContract && options.contract) {
+        process.stderr.write(
+          'Cannot specify both a positional contract argument and --contract flag.\n',
+        );
+        process.exit(2);
+        return;
+      }
+
       const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
 
-      const result = await executeDbSignCommand(options, flags, ui);
+      const result = await executeDbSignCommand(positionalContract, options, flags, ui);
 
       if (result.ok) {
         // Success - format sign output

package/src/commands/db-update.ts

@@ -1,6 +1,11 @@
+import { readFile } from 'node:fs/promises';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
+import { readRefs } from '@prisma-next/migration-tools/refs';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
+import { join } from 'pathe';
 import { ContractValidationError } from '../control-api/errors';
 import type { DbUpdateFailure } from '../control-api/types';
 import {
@@ -11,9 +16,12 @@ import {
   errorMigrationPlanningFailed,
   errorRunnerFailed,
   errorUnexpected,
+  mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import type { MigrationCommandOptions } from '../utils/command-helpers';
 import {
+  loadMigrationPackages,
   resolveMigrationPaths,
   sanitizeErrorMessage,
   setCommandDescriptions,
@@ -33,7 +41,9 @@ import {
 import { handleResult } from '../utils/result-handler';
 import { TerminalUI } from '../utils/terminal-ui';
 
-type DbUpdateOptions = MigrationCommandOptions;
+interface DbUpdateOptions extends MigrationCommandOptions {
+  readonly to?: string;
+}
 
 /**
  * Maps a DbUpdateFailure to a CliStructuredError for consistent error handling.
@@ -81,9 +91,47 @@ async function executeDbUpdateCommand(
   if (!ctxResult.ok) {
     return ctxResult;
   }
-  const { client, config, contractJson, dbConnection, onProgress, contractPathAbsolute } =
-    ctxResult.value;
-  const { migrationsDir } = resolveMigrationPaths(options.config, config);
+  const { client, config, dbConnection, onProgress, contractPathAbsolute } = ctxResult.value;
+  let { contractJson } = ctxResult.value;
+  const { migrationsDir, appMigrationsDir, refsDir } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
+
+  if (options.to) {
+    try {
+      const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
+      const refs = await readRefs(refsDir);
+      const refResult = parseContractRef(options.to, { graph, refs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
+      }
+      const targetHash = refResult.value.hash;
+      const matchingBundle = bundles.find((p) => p.metadata.to === targetHash);
+      if (!matchingBundle) {
+        return notOk(
+          errorUnexpected(
+            `No migration bundle found for --to "${options.to}" (resolved hash: ${targetHash})`,
+            {
+              why: `The ref resolved successfully but no on-disk migration package has an end-contract hash matching ${targetHash}.`,
+              fix: 'Provide a ref or hash that corresponds to an existing migration package, or run `migration list` to see available migrations.',
+            },
+          ),
+        );
+      }
+      const endContractPath = join(matchingBundle.dirPath, 'end-contract.json');
+      const raw = await readFile(endContractPath, 'utf-8');
+      contractJson = JSON.parse(raw) as Record<string, unknown>;
+    } catch (error) {
+      if (MigrationToolsError.is(error)) {
+        return notOk(mapMigrationToolsError(error));
+      }
+      if (CliStructuredError.is(error)) {
+        return notOk(error);
+      }
+      throw error;
+    }
+  }
 
   try {
     await client.connect(dbConnection);
@@ -185,6 +233,10 @@ export function createDbUpdateCommand(): Command {
     'prisma-next db update --db $DATABASE_URL --dry-run',
   ]);
   addMigrationCommandOptions(command);
+  command.option(
+    '--to <contract>',
+    'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+  );
   command.action(async (options: DbUpdateOptions) => {
     const flags = parseGlobalFlags(options);
     const startTime = Date.now();

package/src/commands/init/agent-skill-install.ts

@@ -0,0 +1,232 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { version as cliVersion } from '../../../package.json' with { type: 'json' };
+import type { PackageManager } from './detect-package-manager';
+import { errorInitSkillInstallFailed } from './errors';
+
+const exec = promisify(execFile);
+
+/**
+ * Default base for the GitHub-URL form `<owner>/<repo>` consumed by
+ * upstream `skills add`. Each `SkillSource` joins this base with its
+ * own subpath (and optional `#ref` for version-pinned clusters).
+ */
+export const DEFAULT_AGENT_SKILL_BASE = 'prisma/prisma-next';
+
+/**
+ * One discovery scope inside the Prisma Next monorepo. The CLI emits
+ * one `skills add <base>/<subpath>[#ref] --all` invocation per source
+ * during `init`.
+ *
+ * `ref` semantics:
+ * - `cli`: pin to the CLI's own package version (lockstep with the
+ *   skills' SPI). Used for the version-locked usage cluster — the
+ *   skills under `skills/<X>/SKILL.md`, which describe the public
+ *   package API and are pinned to the version of `@prisma-next/*`
+ *   currently installed in the consumer's project.
+ * - `null`: no ref. The cluster is "always-latest" — the cumulative
+ *   instruction set is the source of truth, and the latest revision
+ *   on `main` includes bug fixes for every prior transition. Used
+ *   for the upgrade and extension-author clusters.
+ */
+export interface SkillSource {
+  readonly subpath: string;
+  readonly ref: 'cli' | null;
+  readonly description: string;
+}
+
+export const DEFAULT_AGENT_SKILL_SOURCES: readonly SkillSource[] = [
+  {
+    subpath: 'skills',
+    ref: 'cli',
+    description: 'usage skills (version-locked to installed Prisma Next)',
+  },
+  {
+    subpath: 'skills/upgrade',
+    ref: null,
+    description: 'upgrade skill (always tracks `main`)',
+  },
+  {
+    subpath: 'skills/extension-author',
+    ref: null,
+    description: 'extension-author skill (always tracks `main`)',
+  },
+];
+
+/**
+ * Test-only escape hatch for pinning the install base to a local
+ * checkout. Production runs leave this unset, so installs always use
+ * `DEFAULT_AGENT_SKILL_BASE`.
+ *
+ * When set to an absolute filesystem path (typical for tests), the
+ * `#ref` fragment is dropped — local-path mode in upstream's CLI does
+ * not accept refs, and the local clone has whatever content the test
+ * checked into it anyway. When set to anything else (e.g. a fork name
+ * `myuser/prisma-next`), the ref policy is preserved.
+ */
+function resolveAgentSkillBase(): string {
+  const override = process.env['PRISMA_NEXT_SKILLS_BASE']?.trim();
+  return override && override.length > 0 ? override : DEFAULT_AGENT_SKILL_BASE;
+}
+
+function isLocalPath(base: string): boolean {
+  return base.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(base);
+}
+
+/**
+ * Build the `<base>/<subpath>[#ref]` URL the `skills` CLI will
+ * resolve. Exported for unit tests so the per-source format can be
+ * asserted without going through the full install loop.
+ */
+export function formatSkillSourceUrl(source: SkillSource): string {
+  const base = resolveAgentSkillBase();
+  const url = `${base}/${source.subpath}`;
+  if (source.ref === null) return url;
+  if (isLocalPath(base)) return url;
+  if (source.ref === 'cli') return `${url}#v${cliVersion}`;
+  return url;
+}
+
+/**
+ * The skill-install command for one source, formatted for the
+ * project's detected package manager. `npx`/`pnpm dlx`/`bunx` are
+ * interchangeable to the user; we pick the variant that matches the
+ * rest of the install step so a single project consistently uses one
+ * runner.
+ *
+ * `--all` auto-selects every skill in the cluster and every detected
+ * agent runtime, skipping the multi-select prompts the `skills` CLI
+ * shows by default. A non-interactive scaffold step cannot present
+ * prompts.
+ *
+ * Exported for unit tests so the per-PM dispatch can be asserted
+ * without a live subprocess.
+ */
+export function formatSkillInstallCommand(pm: PackageManager, source: SkillSource): string {
+  const args = ['skills@latest', 'add', formatSkillSourceUrl(source), '--all'];
+  return formatPackageManagerCommand(pm, args);
+}
+
+/**
+ * `skills add --all` should cover Claude Code, but upstream currently skips
+ * project-local Claude symlinks when `.claude/` does not already exist. Run
+ * the explicit Claude Code install as well so fresh projects get
+ * `.claude/skills` without asking users to create that folder first.
+ */
+export function formatClaudeSkillInstallCommand(pm: PackageManager, source: SkillSource): string {
+  const args = [
+    'skills@latest',
+    'add',
+    formatSkillSourceUrl(source),
+    '--agent',
+    'claude-code',
+    '--skill',
+    "'*'",
+    '-y',
+  ];
+  return formatPackageManagerCommand(pm, args);
+}
+
+function formatPackageManagerCommand(pm: PackageManager, args: readonly string[]): string {
+  switch (pm) {
+    case 'pnpm':
+      return `pnpm dlx ${args.join(' ')}`;
+    case 'yarn':
+      return `yarn dlx ${args.join(' ')}`;
+    case 'bun':
+      return `bunx ${args.join(' ')}`;
+    case 'deno':
+      return `deno run -A npm:${args.join(' ')}`;
+    case 'npm':
+      return `npx ${args.join(' ')}`;
+  }
+}
+
+/**
+ * Parse the project-pm-formatted command into an exec call. The
+ * format-then-parse split keeps the user-facing command string the same
+ * as the surface the structured error advertises, so a user who copies
+ * the error's `fix` line gets the same invocation that init just
+ * attempted. Single quotes are preserved in the display form so `*` is
+ * safe to copy into a shell, then stripped before `execFile`.
+ */
+function commandToExec(command: string): {
+  readonly file: string;
+  readonly args: readonly string[];
+} {
+  const tokens = (command.match(/'[^']*'|\S+/g) ?? []).map((token) =>
+    token.startsWith("'") && token.endsWith("'") ? token.slice(1, -1) : token,
+  );
+  return { file: tokens[0] ?? 'npx', args: tokens.slice(1) };
+}
+
+/**
+ * Runs the project-level skill install for every source in
+ * `DEFAULT_AGENT_SKILL_SOURCES`, in order. Returns
+ * `{ ok: true, commands }` on success; throws a structured
+ * `errorInitSkillInstallFailed` on the first failure (subsequent
+ * sources are not attempted — the user opted into Prisma Next by
+ * running `init` and a partial install would leave the project in an
+ * ambiguous state). The throw is intentionally fatal — project-level
+ * skill install is unconditional (modulo `--no-skill`).
+ */
+export async function runProjectLevelSkillInstall(ctx: {
+  readonly baseDir: string;
+  readonly pm: PackageManager;
+  readonly filesWritten: readonly string[];
+}): Promise<{ readonly ok: true; readonly commands: readonly string[] }> {
+  const commands: string[] = [];
+  const installCommands = DEFAULT_AGENT_SKILL_SOURCES.flatMap((source) => [
+    formatSkillInstallCommand(ctx.pm, source),
+    formatClaudeSkillInstallCommand(ctx.pm, source),
+  ]);
+
+  for (const command of installCommands) {
+    const { file, args } = commandToExec(command);
+    try {
+      await exec(file, args, { cwd: ctx.baseDir });
+      commands.push(command);
+    } catch (err) {
+      throw errorInitSkillInstallFailed({
+        skillInstallCommand: command,
+        filesWritten: ctx.filesWritten,
+        cause:
+          redactSecrets(readChildStderr(err)) || (err instanceof Error ? err.message : String(err)),
+      });
+    }
+  }
+  return { ok: true, commands };
+}
+
+function readChildStderr(err: unknown): string {
+  if (err instanceof Error && 'stderr' in err) {
+    return String((err as { stderr: string }).stderr ?? '');
+  }
+  return '';
+}
+
+/**
+ * Strips credentials from a `scheme://user:pass@host/...` URL anywhere
+ * in `stderr`. Package-manager stderr regularly contains credentialed
+ * registry URLs (private npm registries, GitHub Packages tokens), and
+ * those bubble into the structured `errorInitSkillInstallFailed`
+ * envelope, which ends up in logs and CI output. Redact at the
+ * boundary so we never re-emit a secret.
+ *
+ * Exported for unit tests.
+ */
+export function redactSecrets(stderr: string): string {
+  if (!stderr) return stderr;
+  return stderr.replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^/@\s]+)@/g, '$1***@');
+}
+
+// -------------------------------------------------------------------
+// Legacy file cleanup
+// -------------------------------------------------------------------
+
+/**
+ * Hand-rolled skill stub path that init must not leave behind. Removed
+ * on every init run so a project's `.agents/skills/prisma-next/` does
+ * not shadow the installed Prisma Next skill cluster.
+ */
+export const LEGACY_SKILL_FILE = '.agents/skills/prisma-next/SKILL.md';