@prisma-next/cli 0.5.0-dev.2 → 0.5.0-dev.20

package/src/commands/init/probe-db.ts

@@ -0,0 +1,308 @@
+import { createRequire } from 'node:module';
+import { join } from 'pathe';
+import type { TargetId } from './templates/code-templates';
+
+/**
+ * Result of an attempted database probe (FR8.3). `kind` is the
+ * machine-readable status; `message` is the human-readable line we
+ * surface in `init`'s warning channel (or, under `--strict-probe`, in
+ * the structured error). The probe never throws — every failure
+ * mode is folded into one of these variants so `runInit` can branch
+ * exactly once.
+ */
+export type ProbeOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly serverVersion: string;
+      readonly minVersion: string;
+      readonly meetsMinimum: true;
+      readonly message: string;
+    }
+  | {
+      readonly kind: 'below-minimum';
+      readonly serverVersion: string;
+      readonly minVersion: string;
+      readonly meetsMinimum: false;
+      readonly message: string;
+    }
+  | {
+      readonly kind: 'no-database-url';
+      readonly minVersion: string;
+      readonly meetsMinimum: null;
+      readonly message: string;
+    }
+  | {
+      readonly kind: 'connection-failed';
+      readonly minVersion: string;
+      readonly meetsMinimum: null;
+      readonly cause: string;
+      readonly message: string;
+    }
+  | {
+      readonly kind: 'driver-missing';
+      readonly minVersion: string;
+      readonly meetsMinimum: null;
+      readonly cause: string;
+      readonly message: string;
+    };
+
+export interface ProbeContext {
+  readonly baseDir: string;
+  readonly target: TargetId;
+  readonly databaseUrl: string | undefined;
+  readonly minVersion: string;
+}
+
+/**
+ * Optional injection seam exposed for unit tests so the probe logic
+ * (env handling, version parsing, comparator, message formatting) can
+ * be exercised without a live database. Production callers omit this
+ * argument and get the real `pg` / `mongodb` driver path.
+ */
+export interface ProbeOverrides {
+  readonly probePostgres?: (databaseUrl: string) => Promise<DriverResult>;
+  readonly probeMongo?: (databaseUrl: string) => Promise<DriverResult>;
+  readonly requireFromBaseDir?: (baseDir: string, moduleId: string) => unknown;
+}
+
+interface DriverResult {
+  readonly serverVersion: string;
+}
+
+/**
+ * Connects (when configured) to the user's database and returns a
+ * structured outcome describing whether the server meets the declared
+ * minimum (FR8.1). Pure with respect to its inputs: no I/O happens
+ * unless `databaseUrl` is set.
+ *
+ * The outcome is shaped so that `--strict-probe` can branch on the
+ * `kind`/`meetsMinimum` pair without re-stringifying the message:
+ *
+ * - `ok` — informational; `init` continues.
+ * - `below-minimum` — warning; `init` continues regardless of
+ *   `--strict-probe` (the spec scopes strict-probe to "probe
+ *   *failures*", and a successful probe that finds an old server is
+ *   not a failure).
+ * - `no-database-url` / `connection-failed` / `driver-missing` —
+ *   warning by default, fatal under `--strict-probe`.
+ */
+export async function probeServerVersion(
+  ctx: ProbeContext,
+  overrides: ProbeOverrides = {},
+): Promise<ProbeOutcome> {
+  const { databaseUrl, minVersion, target } = ctx;
+  if (databaseUrl === undefined || databaseUrl.trim().length === 0) {
+    return {
+      kind: 'no-database-url',
+      minVersion,
+      meetsMinimum: null,
+      message:
+        'Skipped --probe-db: DATABASE_URL is not set in the current shell environment. (init does not read .env for the probe; export the variable or drop --probe-db.)',
+    };
+  }
+
+  let driverResult: DriverResult;
+  try {
+    if (target === 'postgres') {
+      driverResult =
+        overrides.probePostgres !== undefined
+          ? await overrides.probePostgres(databaseUrl)
+          : await defaultProbePostgres(databaseUrl, ctx.baseDir, overrides);
+    } else {
+      driverResult =
+        overrides.probeMongo !== undefined
+          ? await overrides.probeMongo(databaseUrl)
+          : await defaultProbeMongo(databaseUrl, ctx.baseDir, overrides);
+    }
+  } catch (err) {
+    if (err instanceof DriverMissingError) {
+      return {
+        kind: 'driver-missing',
+        minVersion,
+        meetsMinimum: null,
+        cause: err.message,
+        message: `Skipped --probe-db: ${err.message}. (Run with install enabled, or install the driver yourself, then re-run \`prisma-next init --probe-db\`.)`,
+      };
+    }
+    const cause = redactDatabaseUrlSecrets(causeMessage(err));
+    return {
+      kind: 'connection-failed',
+      minVersion,
+      meetsMinimum: null,
+      cause,
+      message: `--probe-db could not connect: ${cause}.`,
+    };
+  }
+
+  const meets = compareVersionPrefix(driverResult.serverVersion, minVersion);
+  if (meets < 0) {
+    return {
+      kind: 'below-minimum',
+      serverVersion: driverResult.serverVersion,
+      minVersion,
+      meetsMinimum: false,
+      message: `--probe-db: server reports version ${driverResult.serverVersion}, below the declared minimum (${minVersion}). Some queries may fail until the server is upgraded.`,
+    };
+  }
+  return {
+    kind: 'ok',
+    serverVersion: driverResult.serverVersion,
+    minVersion,
+    meetsMinimum: true,
+    message: `--probe-db: server reports version ${driverResult.serverVersion} (>= ${minVersion}).`,
+  };
+}
+
+/**
+ * Compares two semver-prefix strings ("14", "14.2", "6.0", …) by
+ * numeric components left-to-right. Returns a negative number when `a`
+ * is older than `b`, zero when both versions agree on every numeric
+ * component (treating missing trailing components as `0`), and a
+ * positive number when `a` is newer.
+ *
+ * The loop runs over the **longer** of the two prefixes so that
+ * `'14'` compares less than `'14.1'` — without that, the shorter
+ * prefix would be silently accepted whenever the configured minimum
+ * has a non-zero minor or patch.
+ *
+ * Exported for unit tests.
+ */
+export function compareVersionPrefix(a: string, b: string): number {
+  const aParts = parseNumericParts(a);
+  const bParts = parseNumericParts(b);
+  const len = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < len; i += 1) {
+    const aPart = aParts[i] ?? 0;
+    const bPart = bParts[i] ?? 0;
+    if (aPart !== bPart) return aPart - bPart;
+  }
+  return 0;
+}
+
+function parseNumericParts(version: string): readonly number[] {
+  const match = version.match(/^[^\d]*(\d+(?:\.\d+){0,3})/);
+  if (match === null) return [];
+  return (match[1] ?? '').split('.').map((part) => Number.parseInt(part, 10));
+}
+
+class DriverMissingError extends Error {}
+
+function causeMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+/**
+ * Strips `user:password@` userinfo from any URL-shaped substring before
+ * we surface the cause to the user. Mirrors `redactSecrets` in
+ * `init.ts` — the probe path has its own redactor because the inputs
+ * here include the raw connection string by construction (driver
+ * errors echo the URL back).
+ *
+ * Exported for unit tests.
+ */
+export function redactDatabaseUrlSecrets(text: string): string {
+  if (!text) return text;
+  return text.replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^/@\s]+)@/g, '$1***@');
+}
+
+async function defaultProbePostgres(
+  databaseUrl: string,
+  baseDir: string,
+  overrides: ProbeOverrides,
+): Promise<DriverResult> {
+  const pg = requirePeer<{ Client: new (cfg: { connectionString: string }) => PgClient }>(
+    'pg',
+    baseDir,
+    overrides,
+  );
+  const client = new pg.Client({ connectionString: databaseUrl });
+  await client.connect();
+  try {
+    const result = await client.query('SELECT version() as version');
+    const versionString = String(result?.rows?.[0]?.version ?? '');
+    const parsed = parsePostgresVersion(versionString);
+    return { serverVersion: parsed };
+  } finally {
+    await client.end().catch(() => undefined);
+  }
+}
+
+interface PgClient {
+  connect(): Promise<void>;
+  query(sql: string): Promise<{ rows: ReadonlyArray<{ version: string }> }>;
+  end(): Promise<void>;
+}
+
+/**
+ * Extracts the numeric prefix from a Postgres `version()` row, e.g.
+ *
+ *   `PostgreSQL 14.10 on x86_64-pc-linux-gnu, ...`  → `"14.10"`
+ *   `PostgreSQL 16beta1 on …`                       → `"16"` (we
+ *      conservatively drop the suffix; minimum-version comparisons
+ *      treat 16beta1 as 16, which is what every reasonable user
+ *      expects).
+ *
+ * Exported for unit tests.
+ */
+export function parsePostgresVersion(versionString: string): string {
+  const match = versionString.match(/PostgreSQL\s+(\d+(?:\.\d+)?)/i);
+  if (match === null || match[1] === undefined) {
+    throw new Error(`Could not parse PostgreSQL version from \`${versionString}\``);
+  }
+  return match[1];
+}
+
+async function defaultProbeMongo(
+  databaseUrl: string,
+  baseDir: string,
+  overrides: ProbeOverrides,
+): Promise<DriverResult> {
+  const mongodb = requirePeer<{
+    MongoClient: new (
+      url: string,
+    ) => {
+      connect(): Promise<unknown>;
+      db(name?: string): {
+        admin(): { command(cmd: Record<string, unknown>): Promise<{ version?: string }> };
+      };
+      close(): Promise<void>;
+    };
+  }>('mongodb', baseDir, overrides);
+  const client = new mongodb.MongoClient(databaseUrl);
+  await client.connect();
+  try {
+    const buildInfo = await client.db().admin().command({ buildInfo: 1 });
+    const versionString = String(buildInfo.version ?? '');
+    if (versionString.length === 0) {
+      throw new Error('buildInfo did not include a `version` field');
+    }
+    return { serverVersion: versionString };
+  } finally {
+    await client.close().catch(() => undefined);
+  }
+}
+
+/**
+ * Loads a peer driver (`pg` / `mongodb`) from the user's project
+ * `node_modules`. We deliberately resolve from `baseDir` rather than
+ * from the CLI bundle — the CLI does not depend on `pg` or `mongodb`
+ * directly, but the user's `init`-generated `package.json` does (via
+ * the target facade). Failure to resolve is folded into a typed
+ * `DriverMissingError` so `probeServerVersion` can map it to a
+ * `driver-missing` outcome rather than letting a `MODULE_NOT_FOUND`
+ * leak as a generic connection failure.
+ */
+function requirePeer<T>(moduleId: string, baseDir: string, overrides: ProbeOverrides): T {
+  try {
+    if (overrides.requireFromBaseDir !== undefined) {
+      return overrides.requireFromBaseDir(baseDir, moduleId) as T;
+    }
+    const requireFromBase = createRequire(join(baseDir, 'package.json'));
+    return requireFromBase(moduleId) as T;
+  } catch (err) {
+    throw new DriverMissingError(
+      `\`${moduleId}\` is not installed in this project (resolved from ${baseDir}; cause: ${causeMessage(err)})`,
+    );
+  }
+}

package/src/commands/init/reinit-cleanup.ts

@@ -0,0 +1,83 @@
+import { existsSync } from 'node:fs';
+import { join } from 'pathe';
+
+/**
+ * Filenames the contract pipeline emits next to the user's schema source
+ * (`<schemaDir>/contract.json`, `<schemaDir>/contract.d.ts`, …). Mirrors
+ * `ARTEFACT_FILENAMES` in `hygiene-gitattributes.ts`; kept as a separate
+ * constant here because the cleanup contract is target-agnostic and we
+ * deliberately do not want a stale `start-contract.json` from a previous
+ * target lingering after a re-init.
+ *
+ * If a future emit pipeline produces an additional artefact, add it here
+ * **and** to the gitattributes list — the two stay in lockstep so the
+ * file `init` advertises as `linguist-generated` is exactly the file
+ * `init` is willing to delete on re-init.
+ */
+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',
+];
+
+/**
+ * Returns the schema-relative paths of stale contract artefacts the
+ * previous `init` run (or a `contract emit`) left behind in `schemaDir`.
+ * Paths are returned relative to `baseDir` so the caller can plumb them
+ * into `filesWritten`-style logging without re-deriving the path.
+ *
+ * Pure function: no filesystem mutation. Used by `runInit`'s precondition
+ * phase (FR6.2 / NFR3 atomicity) so a downstream parse failure leaves
+ * the artefacts on disk and the project byte-identical to its pre-init
+ * state.
+ */
+export function findStaleArtefacts(baseDir: string, schemaDir: string): readonly string[] {
+  const result: string[] = [];
+  for (const filename of ARTEFACT_FILENAMES) {
+    const rel = join(schemaDir, filename);
+    if (existsSync(join(baseDir, rel))) {
+      result.push(rel);
+    }
+  }
+  return result;
+}
+
+/**
+ * Drops a single key from `package.json#dependencies`, returning the new
+ * file content. Returns `null` when the dependency was already absent —
+ * the caller can skip the write to keep re-init idempotent (FR9.3).
+ *
+ * Used by `runInit` for the FR9.2 target-switch path: when the user
+ * re-inits a project from `--target postgres` to `--target mongodb` (or
+ * vice versa), the previous facade is removed from `dependencies` so the
+ * resulting project depends only on the chosen target's facade.
+ *
+ * Devs/peers/optional dep groups are intentionally *not* touched — the
+ * facades are only ever in `dependencies` (FR4 / FR7), and broadening
+ * the search would risk clobbering an unrelated dep with the same name
+ * in `peerDependencies`.
+ *
+ * Throws `SyntaxError` if `existing` is not parseable as JSON; the
+ * caller (`runInit`) already guards on that with a structured 5010
+ * error before this helper is reached.
+ */
+export function removeDependency(existing: string, depName: string): string | null {
+  const parsed = JSON.parse(existing) as Record<string, unknown>;
+  const deps = parsed['dependencies'];
+  if (deps === null || typeof deps !== 'object' || Array.isArray(deps)) {
+    return null;
+  }
+  if (!Object.hasOwn(deps as Record<string, unknown>, depName)) {
+    return null;
+  }
+  const next = { ...(deps as Record<string, unknown>) };
+  delete next[depName];
+  parsed['dependencies'] = next;
+  const trailingNewline = existing.endsWith('\n') ? '\n' : '';
+  return `${JSON.stringify(parsed, null, 2)}${trailingNewline}`;
+}

package/src/commands/init/templates/agent-skill-mongo.md

@@ -4,7 +4,7 @@ This project uses **Prisma Next** with **MongoDB** via `@prisma-next/mongo`. Pri
 
 ## Files
 
-- **Contract**: `{{schemaPath}}` — the user's data models. Edit this to add or change models.
+- **Contract**: `{{schemaPath}}` ({{authoringLabel}} authoring) — the user's data models. Edit this to add or change models.
 - **Config**: `prisma-next.config.ts` — tells the CLI where the contract is and how to connect to the database. Loads `.env` via `dotenv/config`.
 - **Database client**: `{{schemaDir}}/db.ts` — `import { db } from '{{dbImportPath}}'`. This is the entry point for all queries.
 - **Generated files** (do not edit by hand):
@@ -23,71 +23,103 @@ This project uses **Prisma Next** with **MongoDB** via `@prisma-next/mongo`. Pri
 
 ## How to write queries
 
-Always use the ORM (`db.orm`). Only fall back to `db.sql` if the user explicitly asks for raw queries or the ORM doesn't support the operation.
+Use the ORM (`db.orm`). Each root accessor is the lowercased plural form emitted by `prisma-next contract emit` (typically the `@@map`-ped collection name) — for `model User { @@map("users") }` use `db.orm.users`, for `model Post { @@map("posts") }` use `db.orm.posts`. The Mongo facade has no raw-SQL surface. Two escape hatches exist for cases the ORM can't express; both are covered under "Escape hatches" below.
 
 ```typescript
 import { db } from '{{dbImportPath}}';
 
 // Find one record
-const user = await db.orm.User
-  .where(user => user.email.eq('alice@example.com'))
+const user = await db.orm.users
+  .where({ email: 'alice@example.com' })
   .first();
-// Returns { id: ObjectId; email: string; ... } | null
+// Returns { _id: ObjectId; email: string; ... } | null
 
-// Find multiple records
-const users = await db.orm.User
-  .select('id', 'email')
+// Find multiple records — `.all()` returns an AsyncIterableResult, consume
+// either as an async iterable (below) or by `await`ing it to materialise an Array.
+for await (const user of db.orm.users
+  .select('_id', 'email')
   .take(10)
-  .all();
-// Returns Array<{ id: ObjectId; email: string }>
+  .all()) {
+  // Each `user` is { _id: ObjectId; email: string }
+}
+// Returns AsyncIterableResult<{ _id: ObjectId; email: string }>
 
 // Filter, order, limit
-const recentPosts = await db.orm.Post
-  .where(post => post.authorId.eq(userId))
-  .orderBy(post => post.createdAt.desc())
-  .select('id', 'title', 'createdAt')
+const recentPosts = await db.orm.posts
+  .where({ authorId: userId })
+  .orderBy({ createdAt: -1 })
+  .select('_id', 'title', 'createdAt')
   .take(50)
   .all();
 
-// Include relations
-const usersWithPosts = await db.orm.User
-  .select('id', 'email')
-  .include('posts', post =>
-    post.select('id', 'title').orderBy(p => p.createdAt.desc()).take(5)
-  )
+// Include relations (reference relations only — embedded relations come back automatically)
+const usersWithPosts = await db.orm.users
+  .select('_id', 'email')
+  .include('posts')
   .take(10)
   .all();
 ```
 
 ### Key ORM methods
 
-- `.where(predicate)` — filter records. Predicate receives a model accessor with `.eq()`, `.neq()`, `.ilike()`, `.lt()`, `.gt()`, etc.
+- `.where({ field: value, ... })` — filter records by an equality object. Pass a raw filter expression for `$gt`/`$in`/`$regex` etc.
 - `.select('field1', 'field2', ...)` — pick which fields to return
-- `.orderBy(accessor => accessor.field.asc()` or `.desc())` — sort results
-- `.take(n)` — limit number of results
-- `.all()` — execute and return all matching records as an array
-- `.first()` — execute and return the first matching record, or `null`
-- `.first({ id: value })` — find a single record by primary key, or `null`
-- `.include('relation', builder => ...)` — eager-load a relation
+- `.orderBy({ field: 1 | -1 })` — sort results (1 = ascending, -1 = descending)
+- `.take(n)` / `.skip(n)` — limit and offset
+- `.all()` — execute and return all matching records as an `AsyncIterableResult`
+- `.first()` — execute with limit 1 and return the first matching row, or `null`
+- `.include('relationName')` — eager-load a reference relation (`$lookup`); embedded relations are already part of the row
+- `.variant('VariantName')` — narrow a polymorphic collection to a discriminator value
+
+## Escape hatches
+
+The ORM covers the common cases. When you genuinely need something it can't express, prefer these — in order — over reaching for `db.runtime()` (which is an internal executor surface, not a `mongodb`-driver handle):
+
+1. **Typed raw aggregations — `db.query`.** The facade exposes a `db.query` builder that runs aggregation pipelines through the same runtime + middleware + codec stack as `db.orm`, so results stay typed against the contract. Use this for `$lookup`/`$facet`/`$graphLookup`/window-function pipelines that the ORM doesn't surface.
+
+2. **Direct `mongodb` driver control — `mongoClient` binding.** If you need a raw `MongoClient` (e.g. for transactions, change streams, sessions, or a driver feature Prisma Next doesn't expose), construct one yourself and pass it to `mongo({ mongoClient, dbName, contractJson })`. Your code keeps the `MongoClient` reference and uses it directly, while the same `db` object still gives you the typed ORM surface:
+
+   ```typescript
+   import { MongoClient } from 'mongodb';
+   import mongo from '@prisma-next/mongo/runtime';
+   import type { Contract } from './contract.d';
+   import contractJson from './contract.json' with { type: 'json' };
+
+   const client = new MongoClient(process.env['DATABASE_URL']!);
+   await client.connect();
+
+   export const db = mongo<Contract>({ contractJson, mongoClient: client, dbName: 'mydb' });
+
+   const session = client.startSession();
+   try {
+     await session.withTransaction(async () => {
+       await db.orm.users.createAll([{ /* ... */ }]);
+     });
+   } finally {
+     await session.endSession();
+   }
+   ```
 
 ## Rules
 
 - **Never hand-edit** `contract.json` or `contract.d.ts`. Always regenerate them with `contract emit`.
 - **Always emit after contract changes.** When you modify `{{schemaPath}}`, run `{{pkgRun}} contract emit` before writing any code that depends on the new or changed models.
-- **Don't restructure `db.ts`.** It's scaffolded by init and works as-is.
-- **Use `db.orm` for queries**, not `db.sql`. The ORM is the primary query surface.
+- **Don't restructure `db.ts`.** It's scaffolded by init and works as-is. `db` connects lazily on the first query — there is no `db.connect(...)` step.
+- **Root accessors are emitter-driven.** Use the lowercased plural collection name (e.g. `db.orm.users`, `db.orm.posts`) — not the PascalCase model name. Re-run `{{pkgRun}} contract emit` if a new model's accessor isn't appearing on `db.orm`.
 - **Connection string** is `DATABASE_URL` in `.env`. If the user reports connection errors, check this value and the `.env` file.
+- **Transactions and change streams** require a MongoDB **replica set**. The Mongo facade does not yet expose `db.transaction(...)` — for now, use the `mongoClient` escape hatch above to drive transactions/sessions directly. See the quick reference for dev-environment options; the typed transaction API is tracked under [TML-2313](https://linear.app/prisma-company/issue/TML-2313/mongo-dev-replica-set-story-is-missing-transactions-change-streams).
+- **Don't reach for `db.runtime()`** as an 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.
 
 ## Workflow for common tasks
 
 **User wants to add a new model or field:**
 1. Edit `{{schemaPath}}`
 2. Run `{{pkgRun}} contract emit`
-3. Write query code using `db.orm.ModelName`
+3. Write query code using `db.orm.<collection>` (lowercased plural, see Rules above)
 
 **User wants to query data:**
 1. Import `db` from `{{dbImportPath}}`
-2. Use `db.orm.ModelName` with `.where()`, `.select()`, `.all()`, `.first()`, etc.
+2. Use `db.orm.<collection>` with `.where()`, `.select()`, `.all()`, `.first()`, etc.
 
 **User wants to set up or change the database connection:**
 1. Edit `DATABASE_URL` in `.env`

package/src/commands/init/templates/agent-skill-postgres.md

@@ -4,7 +4,7 @@ This project uses **Prisma Next** with **PostgreSQL** via `@prisma-next/postgres
 
 ## Files
 
-- **Contract**: `{{schemaPath}}` — the user's data models. Edit this to add or change models.
+- **Contract**: `{{schemaPath}}` ({{authoringLabel}} authoring) — the user's data models. Edit this to add or change models.
 - **Config**: `prisma-next.config.ts` — tells the CLI where the contract is and how to connect to the database. Loads `.env` via `dotenv/config`.
 - **Database client**: `{{schemaDir}}/db.ts` — `import { db } from '{{dbImportPath}}'`. This is the entry point for all queries.
 - **Generated files** (do not edit by hand):

package/src/commands/init/templates/agent-skill.ts

@@ -1,18 +1,40 @@
 import { dirname } from 'pathe';
-import type { TargetId } from './code-templates';
+import type { AuthoringId, TargetId } from './code-templates';
 import { renderTemplate } from './render';
 
-export const variables = ['schemaPath', 'schemaDir', 'dbImportPath', 'pkgRun'] as const;
+export const variables = [
+  'schemaPath',
+  'schemaDir',
+  'dbImportPath',
+  'pkgRun',
+  'authoringLabel',
+] as const;
 
 type TemplateVars = Record<(typeof variables)[number], string>;
 
-export function agentSkillMd(target: TargetId, schemaPath: string, pkgRun: string): string {
+/**
+ * Renders the per-project agent skill (FR5.2). The skill template is
+ * target-specific (Postgres vs Mongo query syntax differs); the authoring
+ * style enters via:
+ *
+ * - `schemaPath` — already routed through {@link agentSkillMd}'s caller
+ *   (the AC says a TS-authoring scaffold must reference `prisma/contract.ts`).
+ * - `authoringLabel` — a short human-readable note (`PSL` / `TypeScript`)
+ *   the skill template uses when describing the contract file.
+ */
+export function agentSkillMd(
+  target: TargetId,
+  authoring: AuthoringId,
+  schemaPath: string,
+  pkgRun: string,
+): string {
   const schemaDir = dirname(schemaPath);
   const vars: TemplateVars = {
     schemaPath,
     schemaDir,
     dbImportPath: `./${schemaDir}/db`,
     pkgRun,
+    authoringLabel: authoring === 'typescript' ? 'TypeScript' : 'PSL',
   };
   const templateFile = `agent-skill-${target}.md`;
   return renderTemplate(templateFile, variables, vars);