@prisma-next/cli 0.3.0-pr.99.5 → 0.3.0

package/src/commands/migration-ref.ts

@@ -0,0 +1,305 @@
+import {
+  readRefs,
+  resolveRef,
+  validateRefName,
+  validateRefValue,
+  writeRefs,
+} from '@prisma-next/migration-tools/refs';
+import { MigrationToolsError } from '@prisma-next/migration-tools/types';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { Command } from 'commander';
+import { resolve } from 'pathe';
+import { loadConfig } from '../config-loader';
+import { CliStructuredError, errorRuntime, errorUnexpected } from '../utils/cli-errors';
+import { addGlobalOptions, setCommandDescriptions } from '../utils/command-helpers';
+import { formatCommandHelp } from '../utils/formatters/help';
+import { parseGlobalFlags } from '../utils/global-flags';
+import { handleResult } from '../utils/result-handler';
+import { TerminalUI } from '../utils/terminal-ui';
+
+interface RefSetResult {
+  readonly ok: true;
+  readonly ref: string;
+  readonly hash: string;
+}
+
+interface RefGetResult {
+  readonly ok: true;
+  readonly ref: string;
+  readonly hash: string;
+}
+
+interface RefDeleteResult {
+  readonly ok: true;
+  readonly ref: string;
+  readonly deleted: true;
+}
+
+interface RefListResult {
+  readonly ok: true;
+  readonly refs: Record<string, string>;
+}
+
+function resolveRefsPath(configPath?: string, config?: { migrations?: { dir?: string } }): string {
+  const base = configPath ? resolve(configPath, '..') : process.cwd();
+  return resolve(base, config?.migrations?.dir ?? 'migrations', 'refs.json');
+}
+
+function mapError(error: unknown): CliStructuredError {
+  if (MigrationToolsError.is(error)) {
+    return errorRuntime(error.message, {
+      why: error.why,
+      fix: error.fix,
+      meta: { code: error.code },
+    });
+  }
+  return errorUnexpected(error instanceof Error ? error.message : String(error));
+}
+
+function cliErrorInvalidRefName(name: string): CliStructuredError {
+  return errorRuntime(`Invalid ref name "${name}"`, {
+    why: `Ref name "${name}" does not match the required format`,
+    fix: 'Ref names must be lowercase alphanumeric with hyphens or forward slashes, no `.` or `..` segments',
+  });
+}
+
+function cliErrorInvalidRefValue(hash: string): CliStructuredError {
+  return errorRuntime(`Invalid contract hash "${hash}"`, {
+    why: `"${hash}" is not a valid contract hash`,
+    fix: 'Contract hashes must match the format "sha256:<64 hex chars>". Copy the hash from `prisma-next contract emit` or `migration status --json`.',
+  });
+}
+
+function errorRefNotFound(name: string): CliStructuredError {
+  return errorRuntime(`Ref "${name}" does not exist`, {
+    why: `No ref named "${name}" found in refs.json`,
+    fix: `Run \`prisma-next migration ref list\` to see available refs, or \`prisma-next migration ref set ${name} <hash>\` to create it`,
+  });
+}
+
+async function executeRefSetCommand(
+  name: string,
+  hash: string,
+  options: { config?: string },
+): Promise<Result<RefSetResult, CliStructuredError>> {
+  if (!validateRefName(name)) {
+    return notOk(cliErrorInvalidRefName(name));
+  }
+  if (!validateRefValue(hash)) {
+    return notOk(cliErrorInvalidRefValue(hash));
+  }
+
+  try {
+    const config = await loadConfig(options.config);
+    const refsPath = resolveRefsPath(options.config, config);
+    const refs = await readRefs(refsPath);
+    const updated = { ...refs, [name]: hash };
+    await writeRefs(refsPath, updated);
+    return ok({ ok: true as const, ref: name, hash });
+  } catch (error) {
+    if (error instanceof CliStructuredError) return notOk(error);
+    return notOk(mapError(error));
+  }
+}
+
+async function executeRefGetCommand(
+  name: string,
+  options: { config?: string },
+): Promise<Result<RefGetResult, CliStructuredError>> {
+  try {
+    const config = await loadConfig(options.config);
+    const refsPath = resolveRefsPath(options.config, config);
+    const refs = await readRefs(refsPath);
+    const hash = resolveRef(refs, name);
+    return ok({ ok: true as const, ref: name, hash });
+  } catch (error) {
+    if (error instanceof CliStructuredError) return notOk(error);
+    return notOk(mapError(error));
+  }
+}
+
+async function executeRefDeleteCommand(
+  name: string,
+  options: { config?: string },
+): Promise<Result<RefDeleteResult, CliStructuredError>> {
+  try {
+    const config = await loadConfig(options.config);
+    const refsPath = resolveRefsPath(options.config, config);
+    const refs = await readRefs(refsPath);
+    if (!Object.hasOwn(refs, name)) {
+      return notOk(errorRefNotFound(name));
+    }
+    const { [name]: _, ...remaining } = refs;
+    await writeRefs(refsPath, remaining);
+    return ok({ ok: true as const, ref: name, deleted: true as const });
+  } catch (error) {
+    if (error instanceof CliStructuredError) return notOk(error);
+    return notOk(mapError(error));
+  }
+}
+
+async function executeRefListCommand(options: {
+  config?: string;
+}): Promise<Result<RefListResult, CliStructuredError>> {
+  try {
+    const config = await loadConfig(options.config);
+    const refsPath = resolveRefsPath(options.config, config);
+    const refs = await readRefs(refsPath);
+    return ok({ ok: true as const, refs });
+  } catch (error) {
+    if (error instanceof CliStructuredError) return notOk(error);
+    return notOk(mapError(error));
+  }
+}
+
+function createRefSetCommand(): Command {
+  const command = new Command('set');
+  setCommandDescriptions(
+    command,
+    'Set a ref to a contract hash',
+    'Sets a named ref to point to a contract hash in migrations/refs.json.',
+  );
+  addGlobalOptions(command)
+    .argument('<name>', 'Ref name (e.g., staging, production)')
+    .argument('<hash>', 'Contract hash to point to')
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(
+      async (
+        name: string,
+        hash: string,
+        options: { config?: string; json?: string | boolean; quiet?: boolean },
+      ) => {
+        const flags = parseGlobalFlags(options);
+        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+        const result = await executeRefSetCommand(name, hash, options);
+        const exitCode = handleResult(result, flags, ui, (value) => {
+          if (flags.json) {
+            ui.output(JSON.stringify(value));
+          } else if (!flags.quiet) {
+            ui.output(`Set ref "${value.ref}" → ${value.hash}`);
+          }
+        });
+        process.exit(exitCode);
+      },
+    );
+  return command;
+}
+
+function createRefGetCommand(): Command {
+  const command = new Command('get');
+  setCommandDescriptions(
+    command,
+    'Get the hash for a ref',
+    'Reads a named ref from migrations/refs.json and prints its contract hash.',
+  );
+  addGlobalOptions(command)
+    .argument('<name>', 'Ref name to look up')
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(
+      async (
+        name: string,
+        options: { config?: string; json?: string | boolean; quiet?: boolean },
+      ) => {
+        const flags = parseGlobalFlags(options);
+        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+        const result = await executeRefGetCommand(name, options);
+        const exitCode = handleResult(result, flags, ui, (value) => {
+          if (flags.json) {
+            ui.output(JSON.stringify(value));
+          } else {
+            ui.output(value.hash);
+          }
+        });
+        process.exit(exitCode);
+      },
+    );
+  return command;
+}
+
+function createRefDeleteCommand(): Command {
+  const command = new Command('delete');
+  setCommandDescriptions(command, 'Delete a ref', 'Removes a named ref from migrations/refs.json.');
+  addGlobalOptions(command)
+    .argument('<name>', 'Ref name to delete')
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(
+      async (
+        name: string,
+        options: { config?: string; json?: string | boolean; quiet?: boolean },
+      ) => {
+        const flags = parseGlobalFlags(options);
+        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+        const result = await executeRefDeleteCommand(name, options);
+        const exitCode = handleResult(result, flags, ui, (value) => {
+          if (flags.json) {
+            ui.output(JSON.stringify(value));
+          } else if (!flags.quiet) {
+            ui.output(`Deleted ref "${value.ref}"`);
+          }
+        });
+        process.exit(exitCode);
+      },
+    );
+  return command;
+}
+
+function createRefListCommand(): Command {
+  const command = new Command('list');
+  setCommandDescriptions(
+    command,
+    'List all refs',
+    'Lists all named refs from migrations/refs.json.',
+  );
+  addGlobalOptions(command)
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(async (options: { config?: string; json?: string | boolean; quiet?: boolean }) => {
+      const flags = parseGlobalFlags(options);
+      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const result = await executeRefListCommand(options);
+      const exitCode = handleResult(result, flags, ui, (value) => {
+        if (flags.json) {
+          ui.output(JSON.stringify(value));
+        } else if (!flags.quiet) {
+          const entries = Object.entries(value.refs);
+          if (entries.length === 0) {
+            ui.output('No refs defined');
+          } else {
+            for (const [refName, hash] of entries) {
+              ui.output(`${refName} → ${hash}`);
+            }
+          }
+        }
+      });
+      process.exit(exitCode);
+    });
+  return command;
+}
+
+export {
+  executeRefSetCommand,
+  executeRefGetCommand,
+  executeRefDeleteCommand,
+  executeRefListCommand,
+  cliErrorInvalidRefName,
+  cliErrorInvalidRefValue,
+  errorRefNotFound,
+};
+
+export function createMigrationRefCommand(): Command {
+  const command = new Command('ref');
+  setCommandDescriptions(
+    command,
+    'Manage migration refs',
+    'Manage named refs in migrations/refs.json. Refs map logical environment\n' +
+      'names (e.g., staging, production) to contract hashes.',
+  );
+  addGlobalOptions(command).configureHelp({
+    formatHelp: (cmd) => formatCommandHelp({ command: cmd, flags: parseGlobalFlags({}) }),
+    subcommandDescription: () => '',
+  });
+  command.addCommand(createRefSetCommand());
+  command.addCommand(createRefGetCommand());
+  command.addCommand(createRefDeleteCommand());
+  command.addCommand(createRefListCommand());
+  return command;
+}

package/src/commands/migration-show.ts

@@ -0,0 +1,246 @@
+import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
+import { findLatestMigration, reconstructGraph } from '@prisma-next/migration-tools/dag';
+import { readMigrationPackage, readMigrationsDir } from '@prisma-next/migration-tools/io';
+import type { MigrationBundle } from '@prisma-next/migration-tools/types';
+import { isAttested, MigrationToolsError } from '@prisma-next/migration-tools/types';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { Command } from 'commander';
+import { relative, resolve } from 'pathe';
+import { loadConfig } from '../config-loader';
+import { extractOperationStatements } from '../control-api/operations/extract-operation-statements';
+import { type CliStructuredError, errorRuntime, errorUnexpected } from '../utils/cli-errors';
+import {
+  addGlobalOptions,
+  setCommandDescriptions,
+  setCommandExamples,
+} from '../utils/command-helpers';
+import { formatMigrationShowOutput } from '../utils/formatters/migrations';
+import { formatStyledHeader } from '../utils/formatters/styled';
+import type { CommonCommandOptions } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { handleResult } from '../utils/result-handler';
+import { TerminalUI } from '../utils/terminal-ui';
+
+interface MigrationShowOptions extends CommonCommandOptions {
+  readonly config?: string;
+}
+
+export interface MigrationShowResult {
+  readonly ok: true;
+  readonly dirName: string;
+  readonly dirPath: string;
+  readonly from: string;
+  readonly to: string;
+  readonly migrationId: string | null;
+  readonly kind: string;
+  readonly createdAt: string;
+  readonly operations: readonly {
+    readonly id: string;
+    readonly label: string;
+    readonly operationClass: string;
+  }[];
+  readonly sql: readonly string[];
+  readonly summary: string;
+}
+
+function looksLikePath(target: string): boolean {
+  return target.includes('/') || target.includes('\\');
+}
+
+export function resolveByHashPrefix(
+  packages: readonly MigrationBundle[],
+  prefix: string,
+): Result<MigrationBundle, CliStructuredError> {
+  const normalizedPrefix = prefix.startsWith('sha256:') ? prefix : `sha256:${prefix}`;
+  const attested = packages.filter((p) => typeof p.manifest.migrationId === 'string');
+  const matches = attested.filter((p) => p.manifest.migrationId!.startsWith(normalizedPrefix));
+
+  if (matches.length === 1) {
+    return ok(matches[0]!);
+  }
+
+  if (matches.length === 0) {
+    return notOk(
+      errorRuntime('No migration found matching prefix', {
+        why: `No attested migration has a migrationId starting with "${normalizedPrefix}"`,
+        fix: 'Run `prisma-next migration show` (no argument) to see the latest migration, or check the migrations directory for available packages.',
+      }),
+    );
+  }
+
+  const candidates = matches.map((p) => `  ${p.dirName}  ${p.manifest.migrationId}`).join('\n');
+  return notOk(
+    errorRuntime('Ambiguous hash prefix', {
+      why: `Multiple migrations match prefix "${normalizedPrefix}":\n${candidates}`,
+      fix: 'Provide a longer prefix to uniquely identify the migration.',
+    }),
+  );
+}
+
+async function executeMigrationShowCommand(
+  target: string | undefined,
+  options: MigrationShowOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+): Promise<Result<MigrationShowResult, CliStructuredError>> {
+  const config = await loadConfig(options.config);
+  const configPath = options.config
+    ? relative(process.cwd(), resolve(options.config))
+    : 'prisma-next.config.ts';
+
+  const migrationsDir = resolve(
+    options.config ? resolve(options.config, '..') : process.cwd(),
+    config.migrations?.dir ?? 'migrations',
+  );
+  const migrationsRelative = relative(process.cwd(), migrationsDir);
+
+  if (!flags.json && !flags.quiet) {
+    const details: Array<{ label: string; value: string }> = [
+      { label: 'config', value: configPath },
+      { label: 'migrations', value: migrationsRelative },
+    ];
+    if (target) {
+      details.push({ label: 'target', value: target });
+    }
+    const header = formatStyledHeader({
+      command: 'migration show',
+      description: 'Display migration package contents',
+      details,
+      flags,
+    });
+    ui.stderr(header);
+  }
+
+  let pkg: MigrationBundle;
+
+  try {
+    if (target && looksLikePath(target)) {
+      pkg = await readMigrationPackage(resolve(target));
+    } else {
+      const allPackages = await readMigrationsDir(migrationsDir);
+      if (allPackages.length === 0) {
+        return notOk(
+          errorRuntime('No migrations found', {
+            why: `No migration packages found in ${migrationsRelative}`,
+            fix: 'Run `prisma-next migration plan` to create a migration first.',
+          }),
+        );
+      }
+
+      if (target) {
+        const resolved = resolveByHashPrefix(allPackages, target);
+        if (!resolved.ok) return resolved;
+        pkg = resolved.value;
+      } else {
+        const attested = allPackages.filter(isAttested);
+        if (attested.length === 0) {
+          return notOk(
+            errorRuntime('No attested migrations found', {
+              why: `All migrations in ${migrationsRelative} are drafts (migrationId: null)`,
+              fix: 'Run `prisma-next migration verify --dir <path>` to attest a draft migration.',
+            }),
+          );
+        }
+        const graph = reconstructGraph(attested);
+        const latestMigration = findLatestMigration(graph);
+        if (!latestMigration) {
+          return notOk(
+            errorRuntime('Could not resolve latest migration', {
+              why: 'No latest migration found in the migration history',
+              fix: 'The migrations directory may be corrupted. Inspect the migration.json files.',
+            }),
+          );
+        }
+        const leafPkg = attested.find(
+          (p) => p.manifest.migrationId === latestMigration.migrationId,
+        );
+        if (!leafPkg) {
+          return notOk(
+            errorRuntime('Could not resolve latest migration', {
+              why: `Latest migration ${latestMigration.dirName} does not match any package`,
+              fix: 'The migrations directory may be corrupted. Inspect the migration.json files.',
+            }),
+          );
+        }
+        pkg = leafPkg;
+      }
+    }
+  } catch (error) {
+    if (MigrationToolsError.is(error)) {
+      return notOk(
+        errorRuntime(error.message, {
+          why: error.why,
+          fix: error.fix,
+          meta: { code: error.code, ...(error.details ?? {}) },
+        }),
+      );
+    }
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read migration: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+
+  const ops = pkg.ops as readonly MigrationPlanOperation[];
+  const sql = extractOperationStatements(config.family.familyId, ops) ?? [];
+
+  const result: MigrationShowResult = {
+    ok: true,
+    dirName: pkg.dirName,
+    dirPath: relative(process.cwd(), pkg.dirPath),
+    from: pkg.manifest.from,
+    to: pkg.manifest.to,
+    migrationId: pkg.manifest.migrationId,
+    kind: pkg.manifest.kind,
+    createdAt: pkg.manifest.createdAt,
+    operations: ops.map((op) => ({
+      id: op.id,
+      label: op.label,
+      operationClass: op.operationClass,
+    })),
+    sql,
+    summary: `${ops.length} operation(s)`,
+  };
+  return ok(result);
+}
+
+export function createMigrationShowCommand(): Command {
+  const command = new Command('show');
+  setCommandDescriptions(
+    command,
+    'Display migration package contents',
+    'Shows the operations, DDL preview, and metadata for a migration package.\n' +
+      'Accepts a directory path, a hash prefix (git-style), or defaults to the\n' +
+      'latest migration.',
+  );
+  setCommandExamples(command, [
+    'prisma-next migration show',
+    'prisma-next migration show sha256:a1b2c3',
+  ]);
+  addGlobalOptions(command)
+    .argument(
+      '[target]',
+      'Migration directory path or migrationId hash prefix (defaults to latest)',
+    )
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(async (target: string | undefined, options: MigrationShowOptions) => {
+      const flags = parseGlobalFlags(options);
+
+      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+
+      const result = await executeMigrationShowCommand(target, options, flags, ui);
+
+      const exitCode = handleResult(result, flags, ui, (showResult) => {
+        if (flags.json) {
+          ui.output(JSON.stringify(showResult, null, 2));
+        } else if (!flags.quiet) {
+          ui.log(formatMigrationShowOutput(showResult, flags));
+        }
+      });
+
+      process.exit(exitCode);
+    });
+
+  return command;
+}