@prisma-next/cli 0.5.0-dev.4 → 0.5.0-dev.40

package/src/commands/db-update.ts

@@ -112,7 +112,7 @@ async function executeDbUpdateCommand(
           label: op.label,
           operationClass: op.operationClass,
         })),
-        ...ifDefined('sql', result.value.plan.sql),
+        ...ifDefined('preview', result.value.plan.preview),
       },
       ...ifDefined(
         'execution',

package/src/commands/init/detect-pnpm-catalog.ts

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'pathe';
+
+/**
+ * Catalog entry detected in a `pnpm-workspace.yaml` that overrides one of
+ * the packages `init` installs. The `version` is the raw value as written
+ * in the workspace file (no normalisation), so the warning surfaces the
+ * exact text the user can search for if they want to find the override.
+ */
+export interface PnpmCatalogOverride {
+  readonly name: string;
+  readonly version: string;
+}
+
+/**
+ * Result of scanning for a pnpm workspace catalog that overrides any of
+ * the packages `init` is about to install. Returns `null` when no
+ * `pnpm-workspace.yaml` is found in `baseDir` or any ancestor; an empty
+ * `entries` array means a workspace exists but contains none of our
+ * packages.
+ */
+export interface PnpmCatalogScanResult {
+  /** Absolute path of the `pnpm-workspace.yaml` that was consulted. */
+  readonly workspaceFile: string;
+  readonly entries: readonly PnpmCatalogOverride[];
+}
+
+/**
+ * Walks up from `baseDir` looking for `pnpm-workspace.yaml`, then scans
+ * its top-level `catalog:` block for entries that match any of `packages`.
+ *
+ * Implements FR7.3 / Spec Decision 8 (honour-and-warn): when `init` runs
+ * inside a pnpm workspace whose catalog overrides one of the packages it
+ * installs, surface a structured warning so the user knows the catalog
+ * version (not the published `latest`) is what ended up in their
+ * `node_modules`. pnpm itself does this silently; the warning closes the
+ * "looks fine, must be wrong version six months later" gap.
+ *
+ * Notes / scope:
+ *
+ * - We only inspect the unnamed top-level `catalog:` block. pnpm also
+ *   supports `catalogs:` (plural — *named* catalogs referenced via
+ *   `catalog:foo` specifiers); those don't apply to a vanilla
+ *   `pnpm add prisma-next` invocation, so we skip them.
+ * - We don't validate YAML syntax exhaustively. The file format pnpm
+ *   ships is line-oriented and well-known; a minimal regex is more
+ *   robust than depending on a YAML parser for one warning.
+ * - We don't compare against the registry's `latest` — pnpm uses the
+ *   catalog version regardless, so the warning fires whenever a match
+ *   exists. The user-facing copy explains how to opt out.
+ */
+export function detectPnpmCatalogOverrides(
+  baseDir: string,
+  packages: readonly string[],
+): PnpmCatalogScanResult | null {
+  const workspaceFile = findNearestPnpmWorkspaceFile(baseDir);
+  if (workspaceFile === null) {
+    return null;
+  }
+
+  const contents = readFileSync(workspaceFile, 'utf-8');
+  const catalog = extractCatalogBlock(contents);
+  if (catalog === null) {
+    return { workspaceFile, entries: [] };
+  }
+
+  const wanted = new Set(packages);
+  const entries: PnpmCatalogOverride[] = [];
+  for (const [name, version] of catalog) {
+    if (wanted.has(name)) {
+      entries.push({ name, version });
+    }
+  }
+  return { workspaceFile, entries };
+}
+
+function findNearestPnpmWorkspaceFile(baseDir: string): string | null {
+  let dir = baseDir;
+  let prev = '';
+  while (dir !== prev) {
+    const candidate = join(dir, 'pnpm-workspace.yaml');
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    prev = dir;
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Returns the entries inside the top-level `catalog:` block as `[name, version]`
+ * pairs in document order, or `null` when no `catalog:` block exists.
+ *
+ * The parser is intentionally minimal: it reads line-by-line, locates the
+ * top-level `catalog:` line (no leading whitespace), then collects every
+ * subsequent indented line of the form `<key>: <value>` until the next
+ * top-level key (or end of file). Quotes around `<key>` and `<value>`
+ * are stripped; comments (`#…`) are ignored.
+ */
+function extractCatalogBlock(contents: string): Array<[string, string]> | null {
+  const lines = contents.split(/\r?\n/);
+  const startIdx = lines.findIndex((line) => /^catalog\s*:\s*$/.test(line));
+  if (startIdx === -1) {
+    return null;
+  }
+
+  const entries: Array<[string, string]> = [];
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const raw = lines[i] ?? '';
+    if (raw.trim() === '' || /^\s*#/.test(raw)) {
+      continue;
+    }
+    if (!/^\s/.test(raw)) {
+      // Hit the next top-level key — catalog block ended.
+      break;
+    }
+    const match = raw.match(/^\s+(?:'([^']+)'|"([^"]+)"|([^:\s'"]+))\s*:\s*(.*?)\s*(?:#.*)?$/);
+    if (!match) {
+      continue;
+    }
+    const name = match[1] ?? match[2] ?? match[3];
+    if (name === undefined) continue;
+    const rawValue = match[4] ?? '';
+    const version = stripQuotes(rawValue.trim());
+    if (version === '') continue;
+    entries.push([name, version]);
+  }
+  return entries;
+}
+
+function stripQuotes(value: string): string {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}

package/src/commands/init/errors.ts

@@ -0,0 +1,254 @@
+import { CliStructuredError } from '../../utils/cli-errors';
+
+/**
+ * No `package.json` / `deno.json` / `deno.jsonc` in the target directory.
+ *
+ * `init` cannot bootstrap a fresh project from a bare directory (NG1) — that
+ * gap is tracked separately. The fix is for the user to run `npm init` (or
+ * the equivalent for their package manager) first.
+ */
+export function errorInitMissingManifest(): CliStructuredError {
+  return new CliStructuredError('5001', 'No project manifest found', {
+    domain: 'CLI',
+    why: 'No package.json or deno.json found in the target directory. `prisma-next init` requires an existing project to attach to.',
+    fix: 'Initialize your project first (e.g. `npm init -y` or `deno init`), then re-run `prisma-next init`.',
+    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+  });
+}
+
+/**
+ * Re-init in non-interactive mode without `--force`. Distinct from the
+ * decline-the-prompt path (which is `errorInitUserAborted`) because here
+ * the user was never given the choice — `--force` is the contract.
+ */
+export function errorInitReinitNeedsForce(): CliStructuredError {
+  return new CliStructuredError('5002', 'Project is already initialized', {
+    domain: 'CLI',
+    why: 'A `prisma-next.config.ts` already exists in this directory. Re-running `init` would overwrite the scaffolded files; in non-interactive mode `init` will not do that without `--force`.',
+    fix: 'Pass `--force` to overwrite the existing scaffold, or run `init` interactively to confirm.',
+    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+  });
+}
+
+/**
+ * Non-interactive mode is missing one or more required inputs. Lists every
+ * missing flag in the error so an agent / CI script can react without
+ * needing to parse English.
+ *
+ * @param missing — kebab-case flag names without leading dashes
+ * @param why — additional context (e.g. "stdin is not a TTY") that helps
+ *              the user understand why interactive fallback was skipped.
+ */
+export function errorInitMissingFlags(options: {
+  readonly missing: readonly string[];
+  readonly why: string;
+}): CliStructuredError {
+  const flagList = options.missing.map((flag) => `--${flag}`).join(', ');
+  const fixList = options.missing
+    .map((flag) => {
+      switch (flag) {
+        case 'target':
+          return '--target postgres|mongodb';
+        case 'authoring':
+          return '--authoring psl|typescript';
+        case 'schema-path':
+          return '--schema-path <path>';
+        default:
+          return `--${flag} <value>`;
+      }
+    })
+    .join(' ');
+  return new CliStructuredError('5003', 'Missing required flags', {
+    domain: 'CLI',
+    why: `${options.why} Missing required flag(s): ${flagList}.`,
+    fix: `Re-run with the missing flag(s) supplied, e.g. \`prisma-next init --yes ${fixList}\`. Use \`prisma-next init --help\` to see every flag.`,
+    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    meta: { missingFlags: options.missing },
+  });
+}
+
+/**
+ * A flag value was supplied but is not in the allowed set. Lists the
+ * allowed values in `meta` for machine-readable consumption.
+ */
+export function errorInitInvalidFlagValue(options: {
+  readonly flag: string;
+  readonly value: string;
+  readonly allowed: readonly string[];
+}): CliStructuredError {
+  return new CliStructuredError('5004', `Invalid value for --${options.flag}`, {
+    domain: 'CLI',
+    why: `\`--${options.flag} ${options.value}\` is not one of: ${options.allowed.join(', ')}.`,
+    fix: `Use one of: ${options.allowed.map((v) => `--${options.flag} ${v}`).join(', ')}.`,
+    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    meta: { flag: options.flag, value: options.value, allowed: options.allowed },
+  });
+}
+
+/**
+ * The user cancelled an interactive prompt (Ctrl-C, escape, declined a
+ * selection). Distinct from `errorInitReinitNeedsForce` because that path
+ * applies to non-interactive mode where the user was never given the
+ * choice; this one is the generic "user said no" path. Maps to exit code
+ * 3 (USER_ABORTED).
+ */
+export function errorInitUserAborted(): CliStructuredError {
+  return new CliStructuredError('5006', 'Init cancelled', {
+    domain: 'CLI',
+    why: 'The interactive prompt was cancelled before all required inputs were supplied. No files were modified.',
+    fix: 'Re-run `prisma-next init` and complete the prompts, or pass the required inputs as flags (see `--help`) for a non-interactive run.',
+    severity: 'info',
+  });
+}
+
+/**
+ * `--strict-probe` was supplied without `--probe-db`. Per FR8.3 / NFR9
+ * (offline-by-default), `--strict-probe` is a no-op without `--probe-db` —
+ * but rather than silently ignoring it we tell the user what they probably
+ * meant. Without this guard, the flag combination silently does nothing,
+ * which is exactly the kind of "looks like it worked" trap that a strict
+ * mode is supposed to prevent.
+ */
+export function errorInitStrictProbeWithoutProbe(): CliStructuredError {
+  return new CliStructuredError('5005', '`--strict-probe` requires `--probe-db`', {
+    domain: 'CLI',
+    why: '`--strict-probe` only changes how a *failed* probe is reported; without `--probe-db` no probe is attempted in the first place. (`init` is offline-by-default — it never opens a connection to your database without explicit consent.)',
+    fix: 'Add `--probe-db` to opt in to the probe, or drop `--strict-probe` if you do not need the version check.',
+    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+  });
+}
+
+/**
+ * Dependency installation failed and the pnpm → npm fallback (FR7.2)
+ * either did not apply (pm ≠ pnpm or stderr did not match a recognised
+ * leak) or also failed. Files scaffolded before the install step are
+ * already on disk; `meta.filesWritten` carries the list so a follow-up
+ * agent can resume manually. Maps to exit code `4 = INSTALL_FAILED`.
+ */
+export function errorInitInstallFailed(options: {
+  readonly addCommand: string;
+  readonly addDevCommand: string;
+  readonly emitCommand: string;
+  readonly filesWritten: readonly string[];
+  readonly stderrLines: readonly string[];
+}): CliStructuredError {
+  const trimmed = options.stderrLines.map((s) => s.trim()).filter(Boolean);
+  const why =
+    trimmed.length === 0
+      ? 'The package manager exited with an error and no recoverable fallback applied.'
+      : `The package manager exited with: ${trimmed[0]}`;
+  return new CliStructuredError('5007', 'Failed to install dependencies', {
+    domain: 'CLI',
+    why,
+    fix: `Install manually:\n  ${options.addCommand}\n  ${options.addDevCommand}\nThen run \`${options.emitCommand}\` to emit the contract.`,
+    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    meta: {
+      filesWritten: options.filesWritten,
+      stderr: trimmed,
+    },
+  });
+}
+
+/**
+ * The user's project manifest (typically `package.json`) failed to parse
+ * as JSON. Init reads the manifest to merge `scripts` (FR3.5) and to
+ * skip `@types/node` when it is already declared (FR2.1); a malformed
+ * file would otherwise surface as an `INTERNAL_ERROR` with a raw
+ * `SyntaxError` stack, which violates the FR1.6 contract that every
+ * documented failure mode maps to a stable exit code.
+ *
+ * Maps to exit code `2 = PRECONDITION` — the user can fix the manifest
+ * and re-run.
+ */
+export function errorInitInvalidManifest(options: {
+  readonly path: string;
+  readonly cause: string;
+}): CliStructuredError {
+  return new CliStructuredError('5010', `Failed to parse ${options.path}`, {
+    domain: 'CLI',
+    why: `\`${options.path}\` is not valid JSON: ${options.cause}`,
+    fix: `Fix the JSON syntax in \`${options.path}\` (a missing comma or unbalanced brace is the most common cause), then re-run \`prisma-next init\`.`,
+    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    meta: { path: options.path, cause: options.cause },
+  });
+}
+
+/**
+ * The user's existing `tsconfig.json` could not be parsed even with JSONC
+ * tolerance (comments + trailing commas) enabled. Init merges the
+ * minimum compiler options the scaffolded files need (FR2.2), so an
+ * unparseable tsconfig is a hard precondition failure: we cannot
+ * faithfully edit a file we cannot read.
+ *
+ * Init must surface this **before** writing any scaffold file so the
+ * user's working tree stays byte-identical (FR6.2 / NFR3) — see
+ * `runInit` for the precondition gate.
+ *
+ * Maps to exit code `2 = PRECONDITION` — the user can fix the file and
+ * re-run.
+ */
+export function errorInitInvalidTsconfig(options: {
+  readonly path: string;
+  readonly cause: string;
+}): CliStructuredError {
+  return new CliStructuredError('5011', `Failed to parse ${options.path}`, {
+    domain: 'CLI',
+    why: `\`${options.path}\` is not valid JSON or JSONC: ${options.cause}`,
+    fix: `Fix the syntax in \`${options.path}\` and re-run \`prisma-next init\`. \`init\` accepts JSONC (comments and trailing commas) but cannot recover from unbalanced braces or missing commas.`,
+    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    meta: { path: options.path, cause: options.cause },
+  });
+}
+
+/**
+ * `--probe-db` was supplied along with `--strict-probe` and the probe
+ * could not complete (no `DATABASE_URL`, network/auth error, the target
+ * driver was not installed, …). Without `--strict-probe` the probe
+ * surfaces these as warnings; `--strict-probe` escalates them to
+ * fatal so a CI gate can rely on "init exit code 2 means something
+ * about the runtime environment is wrong" (FR8.3).
+ *
+ * Maps to exit code `2 = PRECONDITION`. The caller's project files
+ * are already on disk by this point — the probe runs after the write
+ * phase — but the install/emit steps may or may not have completed
+ * depending on `--no-install` and the exact failure mode; `meta`
+ * carries `filesWritten` so a follow-up agent can resume manually.
+ */
+export function errorInitProbeFailed(options: {
+  readonly cause: string;
+  readonly filesWritten: readonly string[];
+}): CliStructuredError {
+  return new CliStructuredError('5012', 'Database probe failed', {
+    domain: 'CLI',
+    why: `\`--probe-db\` could not complete and \`--strict-probe\` was set: ${options.cause}`,
+    fix: 'Confirm `DATABASE_URL` points at a reachable server, or drop `--strict-probe` to treat probe failures as warnings.',
+    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    meta: {
+      filesWritten: options.filesWritten,
+      cause: options.cause,
+    },
+  });
+}
+
+/**
+ * `prisma-next contract emit` failed after a successful install. Surface
+ * the underlying error so the user can fix it and re-run; files and
+ * dependencies remain on disk untouched. Maps to exit code
+ * `5 = EMIT_FAILED`.
+ */
+export function errorInitEmitFailed(options: {
+  readonly emitCommand: string;
+  readonly filesWritten: readonly string[];
+  readonly cause: string;
+}): CliStructuredError {
+  return new CliStructuredError('5008', 'Failed to emit contract', {
+    domain: 'CLI',
+    why: `\`prisma-next contract emit\` failed: ${options.cause}`,
+    fix: `Inspect your contract file, fix the underlying issue, then re-run \`${options.emitCommand}\`. Pass \`-v\` for the full error envelope.`,
+    docsUrl: 'https://prisma-next.dev/docs/cli/contract-emit',
+    meta: {
+      filesWritten: options.filesWritten,
+      cause: options.cause,
+    },
+  });
+}

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`;
+}