@prisma-next/cli 0.5.0-dev.3 → 0.5.0-dev.5

package/src/commands/init/inputs.ts

@@ -0,0 +1,421 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as clack from '@clack/prompts';
+import { extname, join, normalize } from 'pathe';
+import type { GlobalFlags } from '../../utils/global-flags';
+import {
+  errorInitInvalidFlagValue,
+  errorInitMissingFlags,
+  errorInitReinitNeedsForce,
+  errorInitStrictProbeWithoutProbe,
+  errorInitUserAborted,
+} from './errors';
+import {
+  type AuthoringId,
+  defaultSchemaPath,
+  type TargetId,
+  targetLabel,
+  targetPackageName,
+} from './templates/code-templates';
+
+/**
+ * Raw command-line input as Commander.js parses it. `target` here uses the
+ * user-facing `mongodb` spelling (matching the flag); the internal
+ * `TargetId` uses `mongo`. The mapping happens in `resolveInitInputs`.
+ */
+export interface InitFlagOptions {
+  readonly target?: string;
+  readonly authoring?: string;
+  readonly schemaPath?: string;
+  readonly force?: boolean;
+  readonly writeEnv?: boolean;
+  readonly probeDb?: boolean;
+  readonly strictProbe?: boolean;
+  readonly install?: boolean;
+}
+
+/**
+ * The fully-resolved set of decisions `runInit` operates on. After this
+ * value object is constructed, `runInit` should not need to consult the
+ * environment again for any user-visible decision.
+ */
+export interface ResolvedInitInputs {
+  readonly target: TargetId;
+  readonly authoring: AuthoringId;
+  readonly schemaPath: string;
+  readonly install: boolean;
+  readonly writeEnv: boolean;
+  readonly probeDb: boolean;
+  readonly strictProbe: boolean;
+  /**
+   * True if the project already has `prisma-next.config.ts` and the user
+   * has agreed (or `--force` has been supplied) to overwrite it.
+   */
+  readonly reinit: boolean;
+  /**
+   * FR9.2 — set to the **previous** facade package name (e.g.
+   * `@prisma-next/postgres`) when re-init is switching targets and the
+   * user has consented to remove it from `package.json#dependencies`.
+   * `null` when no removal is needed: not a re-init, no previous facade
+   * present, the previous facade matches the chosen target, or the user
+   * declined the interactive confirm. The chosen-target facade itself
+   * is added separately via the install step.
+   */
+  readonly removePreviousFacade: string | null;
+}
+
+const TARGET_ALIASES: ReadonlyMap<string, TargetId> = new Map([
+  ['postgres', 'postgres'],
+  ['postgresql', 'postgres'],
+  ['mongo', 'mongo'],
+  ['mongodb', 'mongo'],
+]);
+
+const AUTHORING_VALUES: ReadonlyMap<string, AuthoringId> = new Map([
+  ['psl', 'psl'],
+  ['typescript', 'typescript'],
+  ['ts', 'typescript'],
+]);
+
+/**
+ * Resolves every required input for `runInit`. In interactive mode, missing
+ * inputs are prompted via clack; in non-interactive mode, missing required
+ * inputs throw a structured error listing exactly which flags are missing
+ * (FR1.4). Throws `CliStructuredError` on any unrecoverable input issue.
+ *
+ * `canPrompt` is decoupled from `flags.interactive` so the action handler
+ * (`./index.ts`) owns the merge of stdout-TTY (decoration) and stdin-TTY
+ * (prompts). `flags.interactive` continues to gate `TerminalUI` decoration
+ * — see [Style Guide § Interactivity](../../../../../../../docs/CLI%20Style%20Guide.md#interactivity).
+ */
+export async function resolveInitInputs(ctx: {
+  readonly baseDir: string;
+  readonly options: InitFlagOptions;
+  readonly flags: GlobalFlags;
+  readonly canPrompt: boolean;
+}): Promise<ResolvedInitInputs> {
+  const { baseDir, options, flags, canPrompt } = ctx;
+  // `--force` and `--yes` are deliberately separate: `--force` is the
+  // contract for "overwrite an existing scaffold" (works in both modes);
+  // `--yes` only auto-accepts interactive prompts and never substitutes
+  // for the explicit destructive opt-in. In non-interactive mode, `--yes`
+  // alone does nothing useful; the user must supply `--target`,
+  // `--authoring`, and (for re-init) `--force`.
+  const force = Boolean(options.force);
+  const autoAcceptPrompts = Boolean(flags.yes);
+
+  // --strict-probe is a no-op without --probe-db; surface the mistake
+  // rather than silently swallowing it (FR8.3 / NFR9).
+  if (options.strictProbe && !options.probeDb) {
+    throw errorInitStrictProbeWithoutProbe();
+  }
+
+  const reinit = await resolveReinit({ baseDir, force, canPrompt, autoAcceptPrompts });
+  const target = resolveTarget(options.target);
+  const authoring = resolveAuthoring(options.authoring);
+
+  // Now collect what's still missing under non-interactive rules.
+  const missing: string[] = [];
+  if (target === undefined) missing.push('target');
+  if (authoring === undefined) missing.push('authoring');
+
+  if (!canPrompt && missing.length > 0) {
+    const reason = process.stdin.isTTY
+      ? 'Non-interactive mode is active (`--no-interactive` or stdout is piped).'
+      : 'stdin is not a TTY, so `init` cannot prompt interactively.';
+    throw errorInitMissingFlags({ missing, why: reason });
+  }
+
+  // Interactive path — fall back to clack for anything still missing.
+  const finalTarget = target ?? (await promptTarget());
+  const finalAuthoring = authoring ?? (await promptAuthoring());
+  const finalSchemaPath =
+    options.schemaPath !== undefined
+      ? validateSchemaPath(options.schemaPath, finalAuthoring)
+      : canPrompt
+        ? await promptSchemaPath(finalAuthoring)
+        : defaultSchemaPath(finalAuthoring);
+
+  // FR3.2: `--write-env` is the explicit opt-in for non-interactive
+  // mode. Interactive runs additionally get a single confirm — but only
+  // when the flag was not already supplied (an explicit `--write-env`
+  // suppresses the prompt) and `--yes` did not auto-accept everything
+  // (in which case interactive mode is effectively non-interactive and
+  // the flag-only contract applies). See Style Guide § Interactivity.
+  const writeEnv = await resolveWriteEnv({
+    flag: options.writeEnv,
+    canPrompt,
+    autoAcceptPrompts,
+  });
+
+  // FR9.2 — when re-init switches targets, ask whether to drop the
+  // previous facade from `dependencies`. Detection happens here (not in
+  // `runInit`) so the prompt sequence stays in one place; the actual
+  // edit is applied during `runInit`'s precondition phase alongside the
+  // other `package.json` merges.
+  const removePreviousFacade = await resolveRemovePreviousFacade({
+    baseDir,
+    target: finalTarget,
+    reinit,
+    force,
+    canPrompt,
+    autoAcceptPrompts,
+  });
+
+  return {
+    target: finalTarget,
+    authoring: finalAuthoring,
+    schemaPath: finalSchemaPath,
+    install: options.install !== false,
+    writeEnv,
+    probeDb: Boolean(options.probeDb),
+    strictProbe: Boolean(options.strictProbe),
+    reinit,
+    removePreviousFacade,
+  };
+}
+
+async function resolveWriteEnv(opts: {
+  readonly flag: boolean | undefined;
+  readonly canPrompt: boolean;
+  readonly autoAcceptPrompts: boolean;
+}): Promise<boolean> {
+  if (opts.flag !== undefined) {
+    return Boolean(opts.flag);
+  }
+  if (!opts.canPrompt || opts.autoAcceptPrompts) {
+    return false;
+  }
+  const result = await clack.confirm({
+    message: 'Also write a .env file from .env.example? (gitignored)',
+    initialValue: false,
+    output: process.stderr,
+  });
+  if (clack.isCancel(result)) {
+    throw errorInitUserAborted();
+  }
+  return Boolean(result);
+}
+
+/**
+ * FR9.2 — detects whether re-init is switching targets (the previous
+ * facade differs from the chosen target's facade) and resolves the
+ * remove-or-keep question.
+ *
+ * The non-interactive contract is the same as the `--force` re-init
+ * gate above: a non-interactive run that reaches this helper always
+ * has `--force` (otherwise `resolveReinit` would have thrown 5002), so
+ * the removal proceeds without further prompting. Interactive runs see
+ * a `clack.confirm` with `initialValue: true` — the destructive default
+ * is correct because keeping both facades produces a project that
+ * imports from one but pays for both in the lockfile, which is a
+ * silent foot-gun the user almost never wants.
+ *
+ * Returns the previous facade package name when the user consented (or
+ * was force-ed) to remove it, otherwise `null`. Parse failures on
+ * `package.json` resolve to `null` here — `runInit`'s precondition
+ * gate surfaces a structured 5010 error for the same file shortly
+ * after, so we avoid double-reporting and keep this helper side-effect
+ * free under hostile inputs.
+ */
+async function resolveRemovePreviousFacade(opts: {
+  readonly baseDir: string;
+  readonly target: TargetId;
+  readonly reinit: boolean;
+  readonly force: boolean;
+  readonly canPrompt: boolean;
+  readonly autoAcceptPrompts: boolean;
+}): Promise<string | null> {
+  if (!opts.reinit) {
+    return null;
+  }
+  const packageJsonPath = join(opts.baseDir, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return null;
+  }
+  const otherTarget: TargetId = opts.target === 'postgres' ? 'mongo' : 'postgres';
+  const otherFacade = targetPackageName(otherTarget);
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  const deps = parsed['dependencies'];
+  if (deps === null || typeof deps !== 'object' || Array.isArray(deps)) {
+    return null;
+  }
+  if (!Object.hasOwn(deps as Record<string, unknown>, otherFacade)) {
+    return null;
+  }
+
+  // `--force` (and `--yes` in interactive mode) auto-confirms the
+  // removal. The `!canPrompt` branch is unreachable in practice because
+  // the FR9.0 reinit gate already required `--force` for non-interactive
+  // re-init, but we keep the guard for defence-in-depth.
+  if (opts.force || (opts.canPrompt && opts.autoAcceptPrompts)) {
+    return otherFacade;
+  }
+  if (!opts.canPrompt) {
+    return otherFacade;
+  }
+  const result = await clack.confirm({
+    message: `Switching from ${targetLabel(otherTarget)} to ${targetLabel(opts.target)} — remove ${otherFacade} from package.json dependencies?`,
+    initialValue: true,
+    output: process.stderr,
+  });
+  if (clack.isCancel(result)) {
+    throw errorInitUserAborted();
+  }
+  return result === true ? otherFacade : null;
+}
+
+async function resolveReinit(opts: {
+  readonly baseDir: string;
+  readonly force: boolean;
+  readonly canPrompt: boolean;
+  readonly autoAcceptPrompts: boolean;
+}): Promise<boolean> {
+  const configPath = join(opts.baseDir, 'prisma-next.config.ts');
+  if (!existsSync(configPath)) {
+    return false;
+  }
+  if (opts.force) {
+    return true;
+  }
+  if (!opts.canPrompt) {
+    throw errorInitReinitNeedsForce();
+  }
+  // In interactive mode, `--yes` auto-accepts the re-init confirm.
+  if (opts.autoAcceptPrompts) {
+    return true;
+  }
+  const result = 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(result) || result !== true) {
+    throw errorInitUserAborted();
+  }
+  return true;
+}
+
+function resolveTarget(value: string | undefined): TargetId | undefined {
+  if (value === undefined) return undefined;
+  const mapped = TARGET_ALIASES.get(value.toLowerCase());
+  if (mapped === undefined) {
+    throw errorInitInvalidFlagValue({
+      flag: 'target',
+      value,
+      allowed: ['postgres', 'mongodb'],
+    });
+  }
+  return mapped;
+}
+
+function resolveAuthoring(value: string | undefined): AuthoringId | undefined {
+  if (value === undefined) return undefined;
+  const mapped = AUTHORING_VALUES.get(value.toLowerCase());
+  if (mapped === undefined) {
+    throw errorInitInvalidFlagValue({
+      flag: 'authoring',
+      value,
+      allowed: ['psl', 'typescript'],
+    });
+  }
+  return mapped;
+}
+
+/**
+ * Validates `--schema-path` against the chosen `--authoring` style: PSL
+ * authoring requires a `.prisma` file and TypeScript authoring requires a
+ * `.ts` file. Mismatched combinations would silently scaffold PSL content
+ * into a `.ts` file (or vice versa); this validator surfaces the mistake
+ * as a precondition error naming both flags.
+ */
+function validateSchemaPath(value: string, authoring: AuthoringId): string {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw errorInitInvalidFlagValue({
+      flag: 'schema-path',
+      value,
+      allowed: ['<non-empty file path with .prisma or .ts extension>'],
+    });
+  }
+  if (trimmed.endsWith('/') || trimmed.endsWith('\\')) {
+    throw errorInitInvalidFlagValue({
+      flag: 'schema-path',
+      value,
+      allowed: ['<file path, not a directory>'],
+    });
+  }
+  const ext = extname(trimmed).toLowerCase();
+  const expected = authoring === 'typescript' ? '.ts' : '.prisma';
+  if (ext !== expected) {
+    throw errorInitInvalidFlagValue({
+      flag: 'schema-path',
+      value,
+      allowed: [`<file path ending in ${expected} for --authoring ${authoring}>`],
+    });
+  }
+  return normalize(trimmed);
+}
+
+async function promptTarget(): Promise<TargetId> {
+  const result = 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(result)) {
+    throw errorInitUserAborted();
+  }
+  return result as TargetId;
+}
+
+async function promptAuthoring(): Promise<AuthoringId> {
+  const result = 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(result)) {
+    throw errorInitUserAborted();
+  }
+  return result as AuthoringId;
+}
+
+async function promptSchemaPath(authoring: AuthoringId): Promise<string> {
+  const expectedExt = authoring === 'typescript' ? '.ts' : '.prisma';
+  const result = 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';
+      const ext = extname(trimmed).toLowerCase();
+      if (ext === '') return 'Path must include a file extension (e.g. .prisma or .ts)';
+      if (ext !== expectedExt) {
+        return `Schema path must end in ${expectedExt} for --authoring ${authoring} (got ${ext}).`;
+      }
+      return undefined;
+    },
+    output: process.stderr,
+  });
+  if (clack.isCancel(result)) {
+    throw errorInitUserAborted();
+  }
+  // Pipe through `validateSchemaPath` so the final value goes through the
+  // same canonicalisation as the flag path — defence-in-depth in case
+  // the inline `validate` ever drifts from the flag-mode rules.
+  return validateSchemaPath(result as string, authoring);
+}

package/src/commands/init/output.ts

@@ -0,0 +1,147 @@
+import { type } from 'arktype';
+import type { GlobalFlags } from '../../utils/global-flags';
+import type { TerminalUI } from '../../utils/terminal-ui';
+
+/**
+ * arktype schema for the structured success document `init --json` writes
+ * to stdout (FR1.5). The same shape backs the human-readable outro
+ * renderer (FR10), so the two output modes carry identical information.
+ *
+ * `target` is normalised to the user-facing flag value (`mongodb` rather
+ * than the internal `mongo`) so consumers can round-trip the document
+ * straight into a follow-up `--target` invocation.
+ *
+ * The `ok: true` literal is the documented success/error discriminator —
+ * see [Style Guide § JSON Semantics](../../../../../../../docs/CLI%20Style%20Guide.md#json-semantics).
+ * Error envelopes (`CliErrorEnvelope`) carry `ok: false` so consumers can
+ * branch with `if (doc.ok)` without inspecting the rest of the structure.
+ */
+export const InitOutputSchema = type({
+  ok: 'true',
+  target: "'postgres'|'mongodb'",
+  authoring: "'psl'|'typescript'",
+  schemaPath: 'string',
+  filesWritten: 'string[]',
+  /**
+   * FR9.1 — files removed from disk during this run. Populated only on
+   * re-init when previously-emitted contract artefacts (`contract.json`,
+   * `contract.d.ts`, `start-/end-contract.*`, `ops.json`,
+   * `migration.json`) were left behind by an earlier run. Empty on a
+   * green-field init.
+   */
+  filesDeleted: 'string[]',
+  packagesInstalled: {
+    skipped: 'boolean',
+    deps: 'string[]',
+    devDeps: 'string[]',
+  },
+  contractEmitted: 'boolean',
+  nextSteps: 'string[]',
+  warnings: 'string[]',
+});
+
+export type InitOutput = typeof InitOutputSchema.infer;
+
+/**
+ * Serialises the output document for `--json`. Sorted keys are not enforced
+ * — `JSON.stringify` preserves insertion order, and the schema field order
+ * is the documented order, which matches what users will see when they
+ * `jq .` the result.
+ */
+export function formatInitJson(output: InitOutput): string {
+  return JSON.stringify(output, null, 2);
+}
+
+/**
+ * Renders the human-readable outro on stderr (FR10.1). Re-uses the same
+ * data structure as the JSON output so the two stay in lock-step.
+ *
+ * Warnings come before "Next steps" because they describe state the user
+ * needs to be aware of before acting on the next-steps list.
+ */
+export function renderInitOutro(ui: TerminalUI, output: InitOutput, flags: GlobalFlags): void {
+  if (flags.quiet || flags.json) {
+    return;
+  }
+
+  for (const warning of output.warnings) {
+    ui.warn(warning);
+  }
+
+  const lines: string[] = [];
+  lines.push(`Target:    ${output.target}`);
+  lines.push(`Authoring: ${output.authoring}`);
+  lines.push(`Schema:    ${output.schemaPath}`);
+  lines.push('');
+  lines.push('Files written:');
+  for (const file of output.filesWritten) {
+    lines.push(`  • ${file}`);
+  }
+
+  if (output.filesDeleted.length > 0) {
+    lines.push('');
+    lines.push('Files deleted (stale contract artefacts):');
+    for (const file of output.filesDeleted) {
+      lines.push(`  • ${file}`);
+    }
+  }
+
+  if (!output.packagesInstalled.skipped) {
+    lines.push('');
+    lines.push('Packages installed:');
+    for (const dep of output.packagesInstalled.deps) {
+      lines.push(`  • ${dep}`);
+    }
+    for (const dep of output.packagesInstalled.devDeps) {
+      lines.push(`  • ${dep} (dev)`);
+    }
+  }
+
+  lines.push('');
+  lines.push('Next steps:');
+  for (const step of output.nextSteps) {
+    lines.push(`  ${step}`);
+  }
+
+  ui.note(lines.join('\n'), 'Done');
+}
+
+/**
+ * Builds the `nextSteps` array from the resolved scaffold state. Steps are
+ * ordered by the workflow a user needs to follow: configure connection →
+ * (emit if not yet done) → run a starter query → docs / agent skill.
+ *
+ * The strings are stable and human-readable; agents wanting to act on them
+ * should match on substrings (e.g. "DATABASE_URL") rather than exact text,
+ * since copy may evolve.
+ */
+export function buildNextSteps(options: {
+  readonly target: 'postgres' | 'mongodb';
+  readonly contractEmitted: boolean;
+  readonly emitCommand: string;
+  readonly schemaPath: string;
+}): string[] {
+  const steps: string[] = [];
+  steps.push('1. Set DATABASE_URL in your environment (export it or add it to .env).');
+  if (!options.contractEmitted) {
+    steps.push(`2. Emit the contract: \`${options.emitCommand}\``);
+    steps.push(`3. Edit your schema at ${options.schemaPath}, then re-run the emit command.`);
+    steps.push(
+      '4. Open prisma-next.md for a quick reference on how to write your first typed query.',
+    );
+    steps.push(
+      '5. The .agents/skills/prisma-next/SKILL.md file is wired up for AI-coding agents in this project.',
+    );
+  } else {
+    steps.push(
+      `2. Edit your schema at ${options.schemaPath}, then re-run \`${options.emitCommand}\`.`,
+    );
+    steps.push(
+      '3. Open prisma-next.md for a quick reference on how to write your first typed query.',
+    );
+    steps.push(
+      '4. The .agents/skills/prisma-next/SKILL.md file is wired up for AI-coding agents in this project.',
+    );
+  }
+  return steps;
+}