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

package/src/commands/init/templates/code-templates.ts

@@ -23,6 +23,90 @@ export function starterSchema(target: TargetId, authoring: AuthoringId): string
   return target === 'mongo' ? starterSchemaPslMongo() : starterSchemaPslPostgres();
 }
 
+/**
+ * Renders a short authoring-appropriate schema sample (FR5.1) for embedding
+ * in `prisma-next.md`. Returns a complete fenced markdown code block.
+ *
+ * The sample intentionally shows just one model: it's illustrative, not
+ * a substitute for the full scaffolded contract file. The TS samples use
+ * the same outer shape as `starterSchemaTs*` (FR5.3) so a user reading
+ * the doc and the file side-by-side sees the same structure.
+ */
+export function schemaSample(target: TargetId, authoring: AuthoringId): string {
+  if (authoring === 'typescript') {
+    return target === 'mongo' ? schemaSampleTsMongo() : schemaSampleTsPostgres();
+  }
+  return target === 'mongo' ? schemaSamplePslMongo() : schemaSamplePslPostgres();
+}
+
+function schemaSamplePslPostgres(): string {
+  return `\`\`\`prisma
+model User {
+  id    Int     @id @default(autoincrement())
+  email String  @unique
+  name  String?
+}
+\`\`\``;
+}
+
+function schemaSamplePslMongo(): string {
+  return `\`\`\`prisma
+model User {
+  id    ObjectId @id @map("_id")
+  email String   @unique
+  name  String?
+  @@map("users")
+}
+\`\`\``;
+}
+
+function schemaSampleTsPostgres(): string {
+  return `\`\`\`typescript
+import sqlFamily from '@prisma-next/family-sql/pack';
+import { defineContract } from '@prisma-next/sql-contract-ts/contract-builder';
+import postgresPack from '@prisma-next/target-postgres/pack';
+
+export const contract = defineContract(
+  { family: sqlFamily, target: postgresPack },
+  ({ field, model }) => ({
+    models: {
+      User: model('User', {
+        fields: {
+          id: field.id.uuidv7(),
+          email: field.text().unique(),
+          name: field.text().optional(),
+        },
+      }),
+    },
+  }),
+);
+\`\`\``;
+}
+
+function schemaSampleTsMongo(): string {
+  return `\`\`\`typescript
+import mongoFamily from '@prisma-next/family-mongo/pack';
+import { defineContract } from '@prisma-next/mongo-contract-ts/contract-builder';
+import mongoTarget from '@prisma-next/target-mongo/pack';
+
+export const contract = defineContract(
+  { family: mongoFamily, target: mongoTarget },
+  ({ field, model }) => ({
+    models: {
+      User: model('User', {
+        collection: 'users',
+        fields: {
+          _id: field.objectId(),
+          email: field.string(),
+          name: field.string().optional(),
+        },
+      }),
+    },
+  }),
+);
+\`\`\``;
+}
+
 function starterSchemaPslPostgres(): string {
   return `model User {
   id        Int      @id @default(autoincrement())
@@ -79,8 +163,9 @@ export const contract = defineContract(
           name: field.text().optional(),
           createdAt: field.createdAt(),
         },
-      }).relations({
-        posts: rel.hasMany('Post', { by: 'authorId' }),
+        relations: {
+          posts: rel.hasMany('Post', { by: 'authorId' }),
+        },
       }),
 
       Post: model('Post', {
@@ -91,8 +176,9 @@ export const contract = defineContract(
           authorId: field.uuid(),
           createdAt: field.createdAt(),
         },
-      }).relations({
-        author: rel.belongsTo('User', { from: 'authorId', to: 'id' }),
+        relations: {
+          author: rel.belongsTo('User', { from: 'authorId', to: 'id' }),
+        },
       }),
     },
   }),
@@ -102,36 +188,40 @@ export const contract = defineContract(
 
 function starterSchemaTsMongo(): string {
   return `import mongoFamily from '@prisma-next/family-mongo/pack';
-import { defineContract, field, model, rel } from '@prisma-next/mongo-contract-ts/contract-builder';
+import { defineContract } from '@prisma-next/mongo-contract-ts/contract-builder';
 import mongoTarget from '@prisma-next/target-mongo/pack';
 
-const User = model('User', {
-  collection: 'users',
-  fields: {
-    _id: field.objectId(),
-    email: field.string(),
-    name: field.string().optional(),
-  },
-});
-
-const Post = model('Post', {
-  collection: 'posts',
-  fields: {
-    _id: field.objectId(),
-    title: field.string(),
-    content: field.string().optional(),
-    authorId: field.objectId(),
-  },
-  relations: {
-    author: rel.belongsTo(User, { from: 'authorId', to: User.ref('_id') }),
-  },
-});
+export const contract = defineContract(
+  { family: mongoFamily, target: mongoTarget },
+  ({ field, model, rel }) => ({
+    models: {
+      User: model('User', {
+        collection: 'users',
+        fields: {
+          _id: field.objectId(),
+          email: field.string(),
+          name: field.string().optional(),
+        },
+        relations: {
+          posts: rel.hasMany('Post', { from: '_id', to: 'authorId' }),
+        },
+      }),
 
-export const contract = defineContract({
-  family: mongoFamily,
-  target: mongoTarget,
-  models: { User, Post },
-});
+      Post: model('Post', {
+        collection: 'posts',
+        fields: {
+          _id: field.objectId(),
+          title: field.string(),
+          content: field.string().optional(),
+          authorId: field.objectId(),
+        },
+        relations: {
+          author: rel.belongsTo('User', { from: 'authorId', to: '_id' }),
+        },
+      }),
+    },
+  }),
+);
 `;
 }
 
@@ -163,6 +253,9 @@ export const db = postgres<Contract>({ contractJson });
 import type { Contract } from './contract.d';
 import contractJson from './contract.json' with { type: 'json' };
 
-export const db = mongo<Contract>({ contractJson });
+export const db = mongo<Contract>({
+  contractJson,
+  url: process.env['DATABASE_URL']!,
+});
 `;
 }

package/src/commands/init/templates/env.ts

@@ -0,0 +1,80 @@
+import type { TargetId } from './code-templates';
+
+/**
+ * The minimum supported server version for each target (FR8.1). The
+ * authoritative source of truth is each target package's
+ * `package.json#prismaNext.minServerVersion` field — this module
+ * mirrors those values and a workspace-level test asserts the two
+ * never drift (`templates/tsconfig-env.test.ts`).
+ *
+ * Bumping a value here in isolation is **not** safe: edit the
+ * corresponding target package's `package.json` first, then mirror
+ * here. The scaffold's `.env.example` (FR3.1, FR8.2) and the
+ * "Requirements" section of `prisma-next.md` both read from this
+ * constant, so a stale value lies to every freshly initialised user.
+ */
+export const MIN_SERVER_VERSION: Record<TargetId, string> = {
+  postgres: '14',
+  mongo: '6.0',
+};
+
+export const TARGET_LABEL: Record<TargetId, string> = {
+  postgres: 'PostgreSQL',
+  mongo: 'MongoDB',
+};
+
+/**
+ * Renders the placeholder body shared by `.env` and `.env.example`:
+ * the target-specific connection-string requirement comments and the
+ * commented-shape `DATABASE_URL` line. The output is identical for both
+ * authoring styles — the env file is orthogonal to PSL vs TS schema
+ * authoring.
+ */
+function envPlaceholderBody(target: TargetId): string {
+  const label = TARGET_LABEL[target];
+  const minVersion = MIN_SERVER_VERSION[target];
+  const lines: string[] = [];
+  lines.push(`# Connection string for ${label}.`);
+  lines.push(`# Requires ${label} >= ${minVersion}.`);
+  lines.push('');
+  if (target === 'postgres') {
+    lines.push('DATABASE_URL="postgresql://user:password@localhost:5432/mydb"');
+  } else {
+    lines.push('DATABASE_URL="mongodb://localhost:27017/mydb"');
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Renders the `.env.example` content for a given target (FR3.1):
+ *
+ * - Carries a "Copy this file to `.env`…" intro that only makes sense
+ *   for the example file (the real `.env` is the destination of that
+ *   copy and so does not get the same intro).
+ * - Documents the `DATABASE_URL` placeholder in the target's native URL
+ *   shape (Postgres: standard `postgresql://`, Mongo: `mongodb://` plus
+ *   a `mydb` database segment so the lazy facade has a `dbName`).
+ * - Carries a `# Requires <db> >= <version>` comment so a fresh user
+ *   knows the minimum supported server before they first try to
+ *   connect (FR8.2).
+ */
+export function envExampleContent(target: TargetId): string {
+  const lines: string[] = [];
+  lines.push(
+    '# Copy this file to `.env` and replace the placeholder with your real connection string.',
+  );
+  lines.push(envPlaceholderBody(target));
+  return lines.join('\n');
+}
+
+/**
+ * Renders the initial `.env` content for `--write-env` / interactive
+ * opt-in (FR3.2). Same placeholder body as `.env.example`, **without**
+ * the example file's "Copy this file to `.env`…" intro: the real `.env`
+ * is the destination of that copy, so the line would lie. Writing this
+ * file is gitignored (FR3.3 ensures `.env` lands in `.gitignore`).
+ */
+export function envFileContent(target: TargetId): string {
+  return envPlaceholderBody(target);
+}

package/src/commands/init/templates/quick-reference-mongo.md

@@ -4,35 +4,29 @@ Prisma Next lets you query your database in simple, easy-to-read TypeScript. Def
 
 This project is set up for MongoDB. Prisma Next also supports other databases.
 
+{{requirements}}
+
 ## Your data contract
 
 Your data contract is the heart of your application. It lives at [`{{schemaPath}}`]({{schemaPath}}) and describes your models:
 
-```prisma
-model User {
-  id    ObjectId @id @map("_id")
-  email String   @unique
-  name  String?
-  posts Post[]
-  @@map("users")
-}
-```
+{{schemaSample}}
 
 Every model you define in your contract can be queried from your app. Your editor will autocomplete the query methods and show you what type each field is:
 
 ```typescript
 import { db } from '{{dbImportPath}}';
 
-const client = await db.connect(process.env['DATABASE_URL']!, 'mydb');
-
-const user = await client.orm.User
+const user = await db.orm.users
   .where({ email: 'alice@example.com' })
   .first();
 
 // Your editor will show the type of user as
-// { id: ObjectId; email: string; name: string | null; posts: Post[] } | null
+// { _id: ObjectId; email: string; name: string | null; posts: Post[] } | null
 ```
 
+`db` connects to MongoDB lazily on the first query, so there is no manual `connect(...)` step in your application code. Call `await db.close()` if you need to release the underlying connection (typically only in tests or short-lived scripts). After `close()` the client is single-shot — any further query, `connect()`, or `runtime()` call rejects with `"Mongo client is closed"`. Construct a new `mongo({...})` if you need to use it again.
+
 Your contract has two companion files in the same directory:
 
 - **`contract.json`** — this tells your application what models exist, just like `package-lock.json` tells your package manager what dependencies your project has
@@ -91,3 +85,30 @@ You can customize how your environment variables are loaded by changing or remov
 1. Edit [`{{schemaPath}}`]({{schemaPath}}) to add or change models.
 2. Run `{{pkgRun}} contract emit` to regenerate the contract.
 3. Query your models — your IDE will autocomplete everything.
+
+## Transactions and change streams (Mongo)
+
+Multi-document transactions and change streams require MongoDB to run as a **replica set** — even single-node setups for development. A standalone `mongod` will reject `withTransaction()` at runtime. For local development you have a few options:
+
+- **Docker Compose:** start `mongo` with `--replSet rs0` and run `rs.initiate()` once.
+- **`mongodb-memory-server`:** use `MongoMemoryReplSet` instead of `MongoMemoryServer` in tests.
+- **MongoDB Atlas:** every Atlas cluster is already a replica set.
+
+The transaction API (`db.transaction(...)`) is on the roadmap and tracked under [TML-2313](https://linear.app/prisma-company/issue/TML-2313/mongo-dev-replica-set-story-is-missing-transactions-change-streams). Prisma Next's Mongo facade does not expose it yet — until that ticket lands, drive transactions yourself with a raw `MongoClient` using the escape hatch in the next section.
+
+## Escape hatches
+
+The ORM covers the common cases. For the rest, two escape hatches are designed in:
+
+- **Typed raw aggregations — `db.query`.** The facade exposes `db.query`, a typed builder for aggregation pipelines that runs through the same runtime + middleware + codec stack as `db.orm`. Reach for it when the ORM can't express a `$lookup`/`$facet`/`$graphLookup`/window-function pipeline.
+- **Direct `mongodb` driver control — `mongoClient` binding.** Construct your own `MongoClient` and pass it to `mongo({ mongoClient, dbName, contractJson })`. Your code keeps the `MongoClient` reference and uses it directly (transactions, change streams, sessions, anything Prisma Next doesn't surface yet); the same `db` object continues to give you the typed ORM.
+
+`db.runtime()` is **not** the escape hatch — it returns the internal executor (`MongoRuntime`), not a `mongodb` `MongoClient` or `Db`. Use `db.query` for raw aggregations and the `mongoClient` binding for direct driver control.
+
+## Monorepo notes (pnpm workspaces)
+
+If this project lives inside a pnpm workspace, a few things are worth knowing:
+
+- **Catalogs.** When the workspace's `pnpm-workspace.yaml` defines a `catalogs` entry for `prisma-next` or `@prisma-next/mongo`, pnpm uses the catalog version everywhere — `init` does too. If you wanted the published `latest` instead, update or remove the catalog entry, then re-run `pnpm install`.
+- **`pnpm dlx`.** `pnpm dlx prisma-next@latest init …` works in any directory. Inside a workspace, pnpm still resolves dependencies through the workspace's catalog/overrides rather than the registry; expect the installed Prisma Next packages to reflect the workspace's catalog rather than `latest`.
+- **`pnpm` → `npm` fallback.** If `pnpm` ever fails to install Prisma Next with a `workspace:*` or `catalog:` resolution error (a leak in a published artefact), `init` falls back to `npm install` and surfaces a warning. Once the offending package republishes a clean version you can switch back with `pnpm install`.

package/src/commands/init/templates/quick-reference-postgres.md

@@ -4,19 +4,13 @@ Prisma Next lets you query your database in simple, easy-to-read TypeScript. Def
 
 This project is set up for PostgreSQL. Prisma Next also supports other databases.
 
+{{requirements}}
+
 ## Your data contract
 
 Your data contract is the heart of your application. It lives at [`{{schemaPath}}`]({{schemaPath}}) and describes your models:
 
-```prisma
-model User {
-  id        Int      @id @default(autoincrement())
-  email     String   @unique
-  name      String?
-  posts     Post[]
-  createdAt DateTime @default(now())
-}
-```
+{{schemaSample}}
 
 Every model you define in your contract can be queried from your app. Your editor will autocomplete the query methods and show you what type each model field is:
 
@@ -89,3 +83,11 @@ You can customize how your environment variables are loaded by changing or remov
 1. Edit [`{{schemaPath}}`]({{schemaPath}}) to add or change models.
 2. Run `{{pkgRun}} contract emit` to regenerate the contract.
 3. Query your models — your IDE will autocomplete everything.
+
+## Monorepo notes (pnpm workspaces)
+
+If this project lives inside a pnpm workspace, a few things are worth knowing:
+
+- **Catalogs.** When the workspace's `pnpm-workspace.yaml` defines a `catalogs` entry for `prisma-next` or `@prisma-next/postgres`, pnpm uses the catalog version everywhere — `init` does too. If you wanted the published `latest` instead, update or remove the catalog entry, then re-run `pnpm install`.
+- **`pnpm dlx`.** `pnpm dlx prisma-next@latest init …` works in any directory. Inside a workspace, pnpm still resolves dependencies through the workspace's catalog/overrides rather than the registry; expect the installed Prisma Next packages to reflect the workspace's catalog rather than `latest`.
+- **`pnpm` → `npm` fallback.** If `pnpm` ever fails to install Prisma Next with a `workspace:*` or `catalog:` resolution error (a leak in a published artefact), `init` falls back to `npm install` and surfaces a warning. Once the offending package republishes a clean version you can switch back with `pnpm install`.

package/src/commands/init/templates/quick-reference.ts

@@ -1,19 +1,58 @@
 import { dirname } from 'pathe';
-import type { TargetId } from './code-templates';
+import { type AuthoringId, schemaSample, type TargetId } from './code-templates';
+import { MIN_SERVER_VERSION, TARGET_LABEL } from './env';
 import { renderTemplate } from './render';
 
-export const variables = ['schemaPath', 'schemaDir', 'dbImportPath', 'pkgRun'] as const;
+export const variables = [
+  'schemaPath',
+  'schemaDir',
+  'dbImportPath',
+  'pkgRun',
+  'schemaSample',
+  'requirements',
+] as const;
 
 type TemplateVars = Record<(typeof variables)[number], string>;
 
-export function quickReferenceMd(target: TargetId, schemaPath: string, pkgRun: string): string {
+export function quickReferenceMd(
+  target: TargetId,
+  authoring: AuthoringId,
+  schemaPath: string,
+  pkgRun: string,
+): string {
   const schemaDir = dirname(schemaPath);
   const vars: TemplateVars = {
     schemaPath,
     schemaDir,
     dbImportPath: `./${schemaDir}/db`,
     pkgRun,
+    schemaSample: schemaSample(target, authoring),
+    requirements: requirementsBlock(target),
   };
   const templateFile = `quick-reference-${target}.md`;
   return renderTemplate(templateFile, variables, vars);
 }
+
+/**
+ * Renders the FR8.2 "Requirements" block injected into `prisma-next.md`
+ * (the user-facing quick reference). Sources the minimum server
+ * version from `MIN_SERVER_VERSION` — itself mirrored from each
+ * target package's `package.json#prismaNext.minServerVersion`
+ * (FR8.1).
+ *
+ * The verification command is target-specific — Postgres scaffolds
+ * shouldn't ship Mongo's `db.runCommand` (and vice versa) just because
+ * we couldn't be bothered to branch.
+ */
+function requirementsBlock(target: TargetId): string {
+  const label = TARGET_LABEL[target];
+  const minVersion = MIN_SERVER_VERSION[target];
+  const verifyCommand =
+    target === 'postgres' ? '`SELECT version()`' : '`db.runCommand({ buildInfo: 1 })`';
+  return [
+    '## Requirements',
+    '',
+    `- **${label} ${minVersion} or newer.** Older servers are not supported. Run ${verifyCommand} against your server to verify.`,
+    '- The CLI never connects to your database without explicit consent. Pass `--probe-db` to `prisma-next init` if you want `init` to verify the server version itself.',
+  ].join('\n');
+}

package/src/commands/init/templates/tsconfig.ts

@@ -1,15 +1,48 @@
+import {
+  applyEdits,
+  modify,
+  type ParseError,
+  parse as parseJsonc,
+  printParseErrorCode,
+} from 'jsonc-parser';
+
+/**
+ * Compiler options the scaffolded `prisma-next.config.ts` and `db.ts` need
+ * to typecheck:
+ *
+ * - `module: 'preserve'` + `moduleResolution: 'bundler'` align with how
+ *   modern bundlers (and `tsdown`) consume our facade packages.
+ * - `resolveJsonModule` lets `db.ts` import `contract.json with { type:
+ *   'json' }` — the runtime path the facades document (FR4).
+ *
+ * `types: ['node']` is FR2.2 territory and lives in
+ * `REQUIRED_COMPILER_OPTIONS_TYPES` because TS only honours an _array_
+ * here, and a string-keyed merge would clobber any user-specified entries.
+ * Merge handling preserves any extra `types` the user added.
+ */
 export const REQUIRED_COMPILER_OPTIONS: Record<string, string | boolean> = {
   module: 'preserve',
   moduleResolution: 'bundler',
   resolveJsonModule: true,
 };
 
+/**
+ * Types that must be present in `compilerOptions.types` for the scaffold
+ * to typecheck. With `moduleResolution: 'bundler'`, TypeScript does not
+ * implicitly include all `@types/*` packages — `process.env` only resolves
+ * when `node` is in this array (or `types` is omitted, but then any other
+ * type listed here would force the same behaviour). Listing `node`
+ * explicitly is the documented escape hatch (FR2.2).
+ */
+export const REQUIRED_COMPILER_OPTIONS_TYPES: readonly string[] = ['node'];
+
 export function defaultTsConfig(): string {
   return JSON.stringify(
     {
       compilerOptions: {
         target: 'ES2022',
         ...REQUIRED_COMPILER_OPTIONS,
+        types: [...REQUIRED_COMPILER_OPTIONS_TYPES],
         strict: true,
         skipLibCheck: true,
         esModuleInterop: true,
@@ -22,14 +55,143 @@ export function defaultTsConfig(): string {
   );
 }
 
+/**
+ * Thrown by `mergeTsConfig` when the user's existing `tsconfig.json` is
+ * not parseable as JSONC (TypeScript's actual configured dialect — see
+ * FR6.1). Carries the raw parse errors so the caller can render an
+ * actionable, location-aware message.
+ *
+ * `runInit` catches this exception during the precondition phase and
+ * maps it to a `CliStructuredError(5011)` so the user's working tree
+ * stays byte-identical when init bails (FR6.2 / NFR3).
+ */
+export class TsConfigParseError extends Error {
+  readonly errors: readonly ParseError[];
+
+  constructor(errors: readonly ParseError[]) {
+    super(formatTsConfigParseErrors(errors));
+    this.errors = errors;
+    this.name = 'TsConfigParseError';
+  }
+}
+
+function formatTsConfigParseErrors(errors: readonly ParseError[]): string {
+  if (errors.length === 0) {
+    return 'tsconfig.json is empty or not an object';
+  }
+  return errors.map((e) => `${printParseErrorCode(e.error)} at offset ${e.offset}`).join('; ');
+}
+
+/**
+ * Merges the required compiler options into an existing `tsconfig.json`.
+ *
+ * Parsing is delegated to `jsonc-parser` so JSONC inputs (comments,
+ * trailing commas) — TypeScript's real configuration dialect — survive
+ * unchanged: edits are applied as text patches via `modify` /
+ * `applyEdits`, preserving the user's formatting, key ordering, and
+ * comments wherever the touched paths permit (FR6.1, AC "Hostile
+ * inputs").
+ *
+ * Throws `TsConfigParseError` when the input is not parseable as JSONC.
+ * The caller must catch this and surface a structured error before
+ * writing any scaffold files (FR6.2 atomicity).
+ */
 export function mergeTsConfig(existing: string): string {
-  const config = JSON.parse(existing) as Record<string, unknown>;
-  const compilerOptions = (config['compilerOptions'] ?? {}) as Record<string, unknown>;
+  const { config } = parseTsConfigText(existing);
 
+  // Match the indentation / line-ending style of the existing file so
+  // the merged output diffs cleanly against it. `jsonc-parser` uses
+  // these only when it has to insert a brand-new object node;
+  // existing-key edits replace the value in place.
+  const formattingOptions = {
+    tabSize: detectIndent(existing),
+    insertSpaces: true,
+    eol: existing.includes('\r\n') ? '\r\n' : '\n',
+  };
+
+  let result = existing;
   for (const [key, value] of Object.entries(REQUIRED_COMPILER_OPTIONS)) {
-    compilerOptions[key] = value;
+    const edits = modify(result, ['compilerOptions', key], value, { formattingOptions });
+    result = applyEdits(result, edits);
+  }
+
+  const existingTypes = (config['compilerOptions'] as Record<string, unknown> | undefined)?.[
+    'types'
+  ];
+  const mergedTypes = mergeTypesArray(existingTypes);
+  const typesEdits = modify(result, ['compilerOptions', 'types'], mergedTypes, {
+    formattingOptions,
+  });
+  result = applyEdits(result, typesEdits);
+
+  return result;
+}
+
+/**
+ * Parses an existing `tsconfig.json` (JSONC) and returns the structured
+ * config alongside any non-fatal parse warnings. Throws
+ * `TsConfigParseError` if the input cannot be parsed at all or does
+ * not resolve to a JSON object — both cases mean we cannot safely
+ * apply edits.
+ *
+ * Exposed independently so callers (notably `runInit`'s precondition
+ * gate) can validate the file *before* any scaffold file is written.
+ */
+export function parseTsConfigText(text: string): {
+  readonly config: Record<string, unknown>;
+} {
+  const errors: ParseError[] = [];
+  const value = parseJsonc(text, errors, {
+    allowTrailingComma: true,
+    disallowComments: false,
+    allowEmptyContent: false,
+  });
+
+  if (value === undefined || value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TsConfigParseError(errors);
+  }
+  if (errors.length > 0) {
+    throw new TsConfigParseError(errors);
+  }
+  return { config: value as Record<string, unknown> };
+}
+
+function detectIndent(text: string): number {
+  // Look at the first indented line. A 2-space indent (the TS default)
+  // is by far the most common; we fall back to 2 when nothing useful
+  // is detectable (e.g. a single-line tsconfig).
+  const match = text.match(/^([ \t]+)\S/m);
+  if (match === null) {
+    return 2;
+  }
+  const indent = match[1] ?? '';
+  if (indent.startsWith('\t')) {
+    return 1;
   }
+  return indent.length || 2;
+}
 
-  config['compilerOptions'] = compilerOptions;
-  return JSON.stringify(config, null, 2);
+/**
+ * Merges `REQUIRED_COMPILER_OPTIONS_TYPES` into the user's existing
+ * `compilerOptions.types` array. Preserves order and dedupes. If the
+ * user has no `types` array (or has set it to a non-array), we replace
+ * with the required minimum — overwriting a non-array `types` is the
+ * correct fix because anything other than a string array is invalid TS
+ * config.
+ */
+function mergeTypesArray(existing: unknown): readonly string[] {
+  const result: string[] = [];
+  if (Array.isArray(existing)) {
+    for (const item of existing) {
+      if (typeof item === 'string' && !result.includes(item)) {
+        result.push(item);
+      }
+    }
+  }
+  for (const required of REQUIRED_COMPILER_OPTIONS_TYPES) {
+    if (!result.includes(required)) {
+      result.push(required);
+    }
+  }
+  return result;
 }

package/src/commands/migration-apply.ts

@@ -112,7 +112,7 @@ async function executeMigrationApplyCommand(
   startTime: number,
 ): Promise<Result<MigrationApplyResult, CliStructuredErrorType>> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, migrationsRelative, refsPath } = resolveMigrationPaths(
+  const { configPath, migrationsDir, migrationsRelative, refsDir } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -149,8 +149,8 @@ async function executeMigrationApplyCommand(
   if (options.ref) {
     refName = options.ref;
     try {
-      const refs = await readRefs(refsPath);
-      destinationHash = resolveRef(refs, refName);
+      const refs = await readRefs(refsDir);
+      destinationHash = resolveRef(refs, refName).hash;
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));