@prisma-next/cli 0.5.0-dev.1 → 0.5.0-dev.10

package/src/commands/init/exit-codes.ts

@@ -0,0 +1,62 @@
+/**
+ * Stable exit codes for the `init` command.
+ *
+ * These are part of the command's public contract. AI agents and CI scripts
+ * branch on them (FR1.6), so the values must remain stable across versions.
+ *
+ * Codes 0–3 are the CLI-wide reserved values per the [CLI Style Guide
+ * Exit Codes section](../../../../../../../docs/CLI%20Style%20Guide.md#exit-codes):
+ * `OK = 0`, `INTERNAL_ERROR = 1`, `PRECONDITION = 2`, `USER_ABORTED = 3`.
+ * Codes 4 and 5 are command-specific outcomes for `init`'s two fallible
+ * side effects (install + emit). Documented in `--help` via
+ * `setCommandDescriptions` in `./index.ts`.
+ */
+
+export const INIT_EXIT_OK = 0;
+
+/**
+ * Anything we did not anticipate — a bug in prisma-next, not something
+ * the caller did wrong. Includes the structured error code `5009`
+ * (invalid output document) and any unrecognised internal error code,
+ * so callers can distinguish "tool is broken" from "your invocation
+ * was wrong" (`PRECONDITION = 2`). Maps to the generic "RUN" error
+ * domain.
+ */
+export const INIT_EXIT_INTERNAL_ERROR = 1;
+
+/**
+ * Preconditions not met. The caller asked for something we cannot do
+ * without more input or a different environment. Examples:
+ *   - missing `package.json` / `deno.json`
+ *   - non-interactive mode without enough flags to proceed
+ *   - re-init without `--force` in non-interactive mode
+ */
+export const INIT_EXIT_PRECONDITION = 2;
+
+/**
+ * The user actively aborted an interactive prompt (Ctrl-C, declined the
+ * re-init confirmation, etc.). Distinct from PRECONDITION because the user
+ * was given the choice and made it; no diagnostic is needed.
+ */
+export const INIT_EXIT_USER_ABORTED = 3;
+
+/**
+ * Dependency installation step failed without a recoverable fallback.
+ * `init` automatically falls back from `pnpm` to `npm` on a recognised
+ * workspace/catalog leak (FR7.2); this code is returned only when the
+ * fallback also fails, or when the package manager is not pnpm and the
+ * single attempt failed. Files written before the install step (config,
+ * schema, db client, etc.) remain on disk so the user can fix the
+ * environment and re-run; the error envelope's `meta.filesWritten` lists
+ * them.
+ */
+export const INIT_EXIT_INSTALL_FAILED = 4;
+
+/**
+ * Contract emit step failed after a successful install. Files written
+ * before emit (including any installed dependencies) are still on disk;
+ * the user can fix the underlying issue (typically a contract syntax
+ * error or a missing extension pack) and re-run `prisma-next contract
+ * emit` manually.
+ */
+export const INIT_EXIT_EMIT_FAILED = 5;

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

@@ -0,0 +1,97 @@
+import type { TargetId } from './templates/code-templates';
+
+/**
+ * The schema-relative `.gitattributes` entries written for a freshly
+ * initialised project (FR3.4). Mirrors the relevant subset of the
+ * repo-root [`.gitattributes`](../../../../../../../../.gitattributes):
+ *
+ * - **Today**: `contract.json`, `contract.d.ts` are emitted on every
+ *   `prisma-next contract emit`. Marking them `linguist-generated`
+ *   keeps GitHub's diff stats honest and collapses the file in code
+ *   review by default.
+ * - **Forward-looking**: `end-contract.*`, `start-contract.*`, `ops.json`,
+ *   `migration.json` are not yet emitted by `init` flows but will be
+ *   produced by adjacent commands (lower / migration tooling). Adding
+ *   them now matches Decision 5 (forward-looking subset) so the file
+ *   does not need to be amended every time a new artefact lands.
+ *
+ * Patterns are written relative to the schema directory so a user
+ * who runs `init --schema-path db/contract.prisma` gets
+ * `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
+ * schema path).
+ */
+const ARTEFACT_FILENAMES: readonly string[] = [
+  'contract.json',
+  'contract.d.ts',
+  'end-contract.json',
+  'end-contract.d.ts',
+  'start-contract.json',
+  'start-contract.d.ts',
+  'ops.json',
+  'migration.json',
+];
+
+const ATTRIBUTE = 'linguist-generated';
+
+/**
+ * Computes the `.gitattributes` lines this scaffold expects to own. Each
+ * line has the shape `<path> linguist-generated`. The `target` parameter
+ * is currently unused but accepted for symmetry with the other hygiene
+ * helpers and to leave room for target-specific entries (e.g. a future
+ * Mongo-only artefact) without a signature break.
+ */
+export function requiredGitattributesLines(
+  schemaDir: string,
+  _target: TargetId,
+): readonly string[] {
+  const dir = schemaDir === '.' ? '' : schemaDir.replace(/\/+$/, '');
+  const prefix = dir === '' ? '' : `${dir}/`;
+  return ARTEFACT_FILENAMES.map((file) => `${prefix}${file} ${ATTRIBUTE}`);
+}
+
+/**
+ * Idempotent `.gitattributes` merge (FR3.4 / FR9.3). Returns the new file
+ * content given the existing content (or `undefined` if the file does
+ * not yet exist).
+ *
+ * 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
+ * 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).
+ *
+ * Returns `null` when no changes are required (file already contains
+ * every required entry).
+ */
+export function mergeGitattributes(
+  existing: string | undefined,
+  required: readonly string[],
+): string | null {
+  if (existing === undefined) {
+    return `${required.join('\n')}\n`;
+  }
+
+  const presentLines = new Set(
+    existing
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith('#')),
+  );
+
+  const missing = required.filter((line) => !presentLines.has(line));
+  if (missing.length === 0) {
+    return null;
+  }
+
+  // Mirrors `mergeGitignore`: a zero-byte existing file would otherwise
+  // gain a leading blank line, because `''.endsWith('\n')` is false. The
+  // empty-file case is uncommon (most projects either don't have a
+  // `.gitattributes` or have one with content), but symmetric handling
+  // keeps the two mergers' invariants identical.
+  const separator = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+  return `${existing}${separator}${missing.join('\n')}\n`;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * The minimal `.gitignore` lines a Prisma Next scaffold needs (FR3.3).
+ * Order matches what Node tooling typically writes today.
+ *
+ * `node_modules/` first because it's the byte-largest miss; `dist/`
+ * because the scaffolded `tsconfig.json` writes there; `.env` last so
+ * the secret-bearing file is the one most-recently visible in any diff
+ * (a paranoid-correct ordering — humans skim from the top).
+ */
+export const REQUIRED_GITIGNORE_ENTRIES: readonly string[] = ['node_modules/', 'dist/', '.env'];
+
+/**
+ * Idempotent `.gitignore` merge (FR3.3 / FR9.3). Returns the new file
+ * content given the existing content (or `undefined` if the file does
+ * not yet exist). Adds only entries that are not already present and
+ * never duplicates a line. Existing comments and blank lines are
+ * preserved verbatim — `.gitignore` is parsed by `git` without a tree,
+ * so any line modification risks changing semantics.
+ *
+ * Pattern equivalence is line-literal: `node_modules/` and `node_modules`
+ * are treated as different entries. This is intentional — `git` treats
+ * them differently (the trailing slash restricts the match to
+ * directories), and the AC pins the trailing-slash form.
+ *
+ * Returns `null` when no changes are required (file already contains
+ * every required entry). The caller can use this to decide whether to
+ * include `.gitignore` in `filesWritten`.
+ */
+export function mergeGitignore(existing: string | undefined): string | null {
+  if (existing === undefined) {
+    return `${REQUIRED_GITIGNORE_ENTRIES.join('\n')}\n`;
+  }
+
+  const present = new Set(
+    existing
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith('#')),
+  );
+
+  const missing = REQUIRED_GITIGNORE_ENTRIES.filter((entry) => !present.has(entry));
+  if (missing.length === 0) {
+    return null;
+  }
+
+  const separator = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+  return `${existing}${separator}${missing.join('\n')}\n`;
+}

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

@@ -0,0 +1,91 @@
+/**
+ * The package.json `scripts` entries `init` adds idempotently (FR3.5).
+ * The script *name* mirrors the CLI subcommand path (`contract:emit` →
+ * `prisma-next contract emit`) so the script is greppable: a user
+ * encountering `npm run contract:emit` in CI logs can navigate
+ * straight to the equivalent CLI invocation.
+ *
+ * No watch-mode entry is included (Spec Decision 9) — file-watching is
+ * the build tool's job (Vite plugin, `tsc --watch`, etc.).
+ */
+export interface RequiredScript {
+  readonly name: string;
+  readonly command: string;
+}
+
+export const REQUIRED_SCRIPTS: readonly RequiredScript[] = [
+  { name: 'contract:emit', command: 'prisma-next contract emit' },
+];
+
+export interface PackageScriptsMergeResult {
+  /**
+   * The new package.json content. `null` when no changes are required
+   * (every required script is already present with the correct
+   * command).
+   */
+  readonly content: string | null;
+  /**
+   * Structured warnings raised when an existing script of the same
+   * name maps to a different command. Each warning names the script,
+   * the existing command, and the command we wanted to write — the
+   * user can decide whether to keep their override or update it.
+   */
+  readonly warnings: readonly string[];
+}
+
+/**
+ * Idempotent `package.json#scripts` merge with collision detection
+ * (FR3.5 / FR9.3):
+ *
+ * - If a required script is **missing**, append it.
+ * - If a required script is **already present and identical**, leave
+ *   the file alone (idempotency).
+ * - If a required script is **present but maps to a different command**,
+ *   skip the write for that script and surface a structured warning.
+ *   The user's override is sacred — `init` should never silently
+ *   overwrite a custom build pipeline.
+ *
+ * Preserves the existing key order (so a user who has alphabetised
+ * their scripts does not see them reshuffled) and appends new entries
+ * at the end.
+ *
+ * The `package.json` is parsed and re-stringified through `JSON` —
+ * comments are not preserved (package.json does not support them per
+ * spec). Trailing newline matches the original input's trailing
+ * newline behaviour.
+ */
+export function mergePackageScripts(
+  existing: string,
+  required: readonly RequiredScript[] = REQUIRED_SCRIPTS,
+): PackageScriptsMergeResult {
+  const parsed = JSON.parse(existing) as Record<string, unknown>;
+  const scripts: Record<string, string> =
+    typeof parsed['scripts'] === 'object' && parsed['scripts'] !== null
+      ? { ...(parsed['scripts'] as Record<string, string>) }
+      : {};
+
+  const warnings: string[] = [];
+  let mutated = false;
+
+  for (const { name, command } of required) {
+    const existingValue = scripts[name];
+    if (existingValue === undefined) {
+      scripts[name] = command;
+      mutated = true;
+      continue;
+    }
+    if (existingValue !== command) {
+      warnings.push(
+        `package.json already has a "${name}" script with a different command — keeping yours.\n  existing: ${existingValue}\n  expected: ${command}\nIf you want the default, remove your "${name}" script and re-run \`init\`.`,
+      );
+    }
+  }
+
+  if (!mutated) {
+    return { content: null, warnings };
+  }
+
+  parsed['scripts'] = scripts;
+  const trailingNewline = existing.endsWith('\n') ? '\n' : '';
+  return { content: `${JSON.stringify(parsed, null, 2)}${trailingNewline}`, warnings };
+}

package/src/commands/init/index.ts

@@ -1,5 +1,39 @@
 import { Command } from 'commander';
-import { setCommandDescriptions, setCommandExamples } from '../../utils/command-helpers';
+import {
+  addGlobalOptions,
+  setCommandDescriptions,
+  setCommandExamples,
+} from '../../utils/command-helpers';
+import { type CommonCommandOptions, parseGlobalFlags } from '../../utils/global-flags';
+import {
+  INIT_EXIT_EMIT_FAILED,
+  INIT_EXIT_INSTALL_FAILED,
+  INIT_EXIT_INTERNAL_ERROR,
+  INIT_EXIT_OK,
+  INIT_EXIT_PRECONDITION,
+  INIT_EXIT_USER_ABORTED,
+} from './exit-codes';
+
+/**
+ * Commander.js parsed options for `init`. The init-specific options live
+ * alongside the inherited `CommonCommandOptions` global flags.
+ *
+ * `target` and `authoring` are typed as plain `string` here because
+ * Commander.js does not enforce enums at parse time — the validation /
+ * normalisation happens in `inputs.ts::resolveInitInputs`, which can
+ * raise a structured `errorInitInvalidFlagValue` with the full set of
+ * allowed values.
+ */
+interface InitCommandOptions extends CommonCommandOptions {
+  readonly target?: string;
+  readonly authoring?: string;
+  readonly schemaPath?: string;
+  readonly force?: boolean;
+  readonly writeEnv?: boolean;
+  readonly probeDb?: boolean;
+  readonly strictProbe?: boolean;
+  readonly install?: boolean;
+}
 
 export function createInitCommand(): Command {
   const command = new Command('init');
@@ -7,15 +41,86 @@ export function createInitCommand(): Command {
     command,
     'Initialize a new Prisma Next project',
     'Scaffolds config, schema, and runtime files, installs dependencies,\n' +
-      'and emits the contract. Gets you from zero to typed queries in one step.',
+      'and emits the contract. Gets you from zero to typed queries in one step.\n' +
+      '\n' +
+      'Run interactively for a guided experience, or supply --target / --authoring\n' +
+      'and --yes for a fully scriptable run (CI, AI coding agents, automation).\n' +
+      '\n' +
+      'Exit codes (see CLI Style Guide § Exit Codes):\n' +
+      `  ${INIT_EXIT_OK}   OK                    Init succeeded.\n` +
+      `  ${INIT_EXIT_INTERNAL_ERROR}   INTERNAL_ERROR        Unexpected bug in prisma-next (please report).\n` +
+      `  ${INIT_EXIT_PRECONDITION}   PRECONDITION          Bad flags / missing prerequisite (e.g. no package.json).\n` +
+      `  ${INIT_EXIT_USER_ABORTED}   USER_ABORTED          User cancelled an interactive prompt.\n` +
+      `  ${INIT_EXIT_INSTALL_FAILED}   INSTALL_FAILED        Dependency installation failed (init-specific).\n` +
+      `  ${INIT_EXIT_EMIT_FAILED}   EMIT_FAILED           \`contract emit\` failed after install (init-specific).`,
   );
-  setCommandExamples(command, ['prisma-next init', 'prisma-next init --no-install']);
-  command
+  setCommandExamples(command, [
+    'prisma-next init',
+    'prisma-next init --yes --target postgres --authoring psl',
+    'prisma-next init --yes --target mongodb --authoring typescript --json',
+    'prisma-next init --yes --force --target postgres --authoring psl  # overwrite an existing scaffold',
+    'prisma-next init --no-install                                       # skip pnpm/npm install + emit',
+  ]);
+
+  return addGlobalOptions(command)
+    .option('--target <db>', 'Database target: postgres or mongodb')
+    .option('--authoring <style>', 'Schema authoring style: psl or typescript')
+    .option(
+      '--schema-path <path>',
+      'Where to write the starter schema (default: prisma/contract.prisma)',
+    )
+    .option('--force', 'Overwrite an existing scaffold without prompting')
+    .option(
+      '--write-env',
+      'Write a .env file from .env.example (gitignored; default: only .env.example)',
+    )
+    .option(
+      '--probe-db',
+      'Connect to DATABASE_URL once and check the server version against the target minimum (opt-in; off by default)',
+    )
+    .option(
+      '--strict-probe',
+      'Treat a failed --probe-db as fatal (no-op without --probe-db; init is offline-by-default)',
+    )
     .option('--no-install', 'Skip dependency installation and contract emission')
-    .action(async (options: { readonly install?: boolean }) => {
+    .action(async (options: InitCommandOptions) => {
       const { runInit } = await import('./init');
-      await runInit(process.cwd(), { noInstall: !options.install });
+      const flags = parseGlobalFlags(options);
+      const canPrompt = deriveCanPrompt({
+        flagsInteractive: flags.interactive,
+        optionInteractive: options.interactive,
+        stdinIsTTY: Boolean(process.stdin.isTTY),
+      });
+      const exitCode = await runInit(process.cwd(), { options, flags, canPrompt });
+      process.exit(exitCode);
     });
+}
 
-  return command;
+/**
+ * Bridges the action handler's two TTY checks (stdout via `flags`, stdin
+ * via `process.stdin.isTTY`) into the `canPrompt` boolean `runInit`
+ * consumes.
+ *
+ * Per the [Style Guide § Interactivity](../../../../../../../docs/CLI%20Style%20Guide.md#interactivity):
+ *
+ * - `flags.interactive` governs *decoration* (TerminalUI, intro/outro,
+ *   spinners) and is derived from stdout-TTY by `parseGlobalFlags`,
+ *   honouring `--interactive` / `--no-interactive`.
+ * - Prompting additionally requires a stdin TTY — closing stdin is a
+ *   common signal in CI / agent environments even when stdout stays
+ *   attached.
+ * - `--interactive` is the explicit override: when the user passes it,
+ *   we honour it (e.g. testing flows where stdin is stubbed).
+ *
+ * Exported so callers and tests can derive the same value without
+ * touching `process` globals — F14 of the M1/M2 review.
+ */
+export function deriveCanPrompt(opts: {
+  readonly flagsInteractive: boolean | undefined;
+  readonly optionInteractive: boolean | undefined;
+  readonly stdinIsTTY: boolean;
+}): boolean {
+  if (opts.optionInteractive === true) return true;
+  if (opts.flagsInteractive === false) return false;
+  return opts.stdinIsTTY;
 }