feat(cli): write PSL from db introspect by default (#244)

## Summary
- add a new `@prisma-next/psl-printer` package that renders
`SqlSchemaIR` into deterministic PSL, including models, relations,
enums, named types, and defaults
- change `prisma-next db introspect` to write `schema.prisma` by
default, move the tree preview behind `--dry-run`, and surface the
written PSL path in JSON output
- add integration coverage for the brownfield PSL flow and land
follow-up fixes for output-path resolution, storage UUID defaults,
inferred relation-name escaping, and colliding normalized field aliases

## Limitations
- generated PSL does not support enum value `@map(...)` annotations yet

## Testing
- `pnpm --filter @prisma-next/cli test --
test/commands/db-introspect-paths.test.ts`
- `pnpm test` in `packages/1-framework/2-authoring/psl-printer`
- `pnpm typecheck` in `packages/1-framework/2-authoring/psl-printer`

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* CLI: db introspect now writes PSL (.prisma) files by default, supports
--output and --dry-run, and reports "Schema written to"; overwrite
warnings can be suppressed with --quiet.
* **New Features**
* New PSL printer: deterministic conversion of introspected schemas into
Prisma Schema Language output.
* **Enhancements**
* Generated schemas include enums, named/parameterized types, relations,
indexes, composite keys, preserved defaults, and stable naming.
* **Tests**
* Extensive unit and E2E coverage for printing, parsing, naming, type
mapping, relation inference, and CLI flows.
* **Documentation**
  * README added for the PSL printer.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>

Author: jkomyno

docs/products/psl/README.md

@@ -36,8 +36,9 @@ For package-level responsibilities and supported defaults, see:
 
 This is a deliberate “strict subset” choice: PSL v1 is bounded by the current TS authoring surface + contract model and prefers “fail loudly” over silent partial interpretation.
 
-- **Native type attributes (`@db.`*) are mostly unsupported** today.
-  - The only parameterized attribute surface currently mapped for parity is `@pgvector.column(...)`.
+- **Selected Postgres native type attributes (`@db.`*) are supported on named types** for brownfield round-trips.
+  - Current support covers the printer/provider subset needed to preserve native storage shape for inferred PSL: `@db.Char`, `@db.VarChar`, `@db.Numeric`, `@db.Uuid`, `@db.SmallInt`, `@db.Real`, `@db.Timestamp`, `@db.Timestamptz`, `@db.Date`, `@db.Time`, `@db.Timetz`, and `@db.Json`.
+  - The extension-pack parity surface still includes `@pgvector.column(...)` when the corresponding pack is composed.
 - **Typed JSON schema parameterization is unsupported** (PSL has no way to encode TS `typeParams` schema payloads in v1).
 
 ### Relations
@@ -88,7 +89,7 @@ This is a deliberate “strict subset” choice: PSL v1 is bounded by the curren
 
 These are recurring “next” areas implied by the above limitations:
 
-- **Broader parameterized native types** (`@db.`* parity beyond pgvector)
+- **Broader `@db.` parity** beyond the current brownfield round-trip subset
 - **Richer index / constraint features** (names, methods, predicates) gated by target/packs
 - **Tooling-friendly inline language blocks** (tagged template literals like `sql\`...`) for SQL snippets, with explicit rules (e.g. no interpolation) and parser-agnostic tag configuration
 

packages/1-framework/2-authoring/psl-parser/src/parser.ts

@@ -238,6 +238,7 @@ function parseModelBlock(context: ParserContext, name: string, bounds: BlockBoun
 
 function parseEnumBlock(context: ParserContext, name: string, bounds: BlockBounds): PslEnum {
   const values: PslEnumValue[] = [];
+  const attributes: PslAttribute[] = [];
 
   for (let lineIndex = bounds.startLine + 1; lineIndex < bounds.endLine; lineIndex += 1) {
     const raw = context.lines[lineIndex] ?? '';
@@ -246,6 +247,14 @@ function parseEnumBlock(context: ParserContext, name: string, bounds: BlockBound
       continue;
     }
 
+    if (line.startsWith('@@')) {
+      const attribute = parseEnumAttribute(context, line, lineIndex);
+      if (attribute) {
+        attributes.push(attribute);
+      }
+      continue;
+    }
+
     const valueMatch = line.match(/^([A-Za-z_]\w*)$/);
     if (!valueMatch) {
       pushDiagnostic(context, {
@@ -267,6 +276,7 @@ function parseEnumBlock(context: ParserContext, name: string, bounds: BlockBound
     kind: 'enum',
     name,
     values,
+    attributes,
     span: createLineRangeSpan(context, bounds.startLine, bounds.endLine),
   };
 }
@@ -367,6 +377,50 @@ function parseModelAttribute(
   });
 }
 
+function parseEnumAttribute(
+  context: ParserContext,
+  line: string,
+  lineIndex: number,
+): PslAttribute | undefined {
+  const rawLine = context.lines[lineIndex] ?? '';
+  const tokenParse = extractAttributeTokensWithSpans(
+    context,
+    lineIndex,
+    line,
+    firstNonWhitespaceColumn(rawLine),
+  );
+  if (!tokenParse.ok || tokenParse.tokens.length !== 1) {
+    pushDiagnostic(context, {
+      code: 'PSL_INVALID_ENUM_MEMBER',
+      message: `Invalid enum value declaration "${line}"`,
+      span: createTrimmedLineSpan(context, lineIndex),
+    });
+    return undefined;
+  }
+  const token = tokenParse.tokens[0];
+  if (!token) {
+    return undefined;
+  }
+  const parsed = parseAttributeToken(context, {
+    token: token.text,
+    target: 'enum',
+    lineIndex,
+    span: token.span,
+  });
+  if (!parsed) {
+    return undefined;
+  }
+  if (parsed.name !== 'map') {
+    pushDiagnostic(context, {
+      code: 'PSL_INVALID_ENUM_MEMBER',
+      message: `Invalid enum value declaration "${line}"`,
+      span: createTrimmedLineSpan(context, lineIndex),
+    });
+    return undefined;
+  }
+  return parsed;
+}
+
 function parseField(context: ParserContext, line: string, lineIndex: number): PslField | undefined {
   const fieldMatch = line.match(/^([A-Za-z_]\w*)\s+([A-Za-z_]\w*(?:\[\])?)(\?)?(.*)$/);
   if (!fieldMatch) {
@@ -442,24 +496,25 @@ function parseAttributeToken(
     readonly span: PslSpan;
   },
 ): PslAttribute | undefined {
-  const expectsModelPrefix = input.target === 'model';
-  if (expectsModelPrefix && !input.token.startsWith('@@')) {
+  const expectsBlockPrefix = input.target === 'model' || input.target === 'enum';
+  const targetLabel = input.target === 'enum' ? 'Enum' : 'Model';
+  if (expectsBlockPrefix && !input.token.startsWith('@@')) {
     pushDiagnostic(context, {
       code: 'PSL_INVALID_ATTRIBUTE_SYNTAX',
-      message: `Model attribute "${input.token}" must use @@ prefix`,
+      message: `${targetLabel} attribute "${input.token}" must use @@ prefix`,
       span: input.span,
     });
     return undefined;
   }
-  if (!expectsModelPrefix && !input.token.startsWith('@')) {
+  if (!expectsBlockPrefix && !input.token.startsWith('@')) {
     pushDiagnostic(context, {
       code: 'PSL_INVALID_ATTRIBUTE_SYNTAX',
       message: `Attribute "${input.token}" must use @ prefix`,
       span: input.span,
     });
     return undefined;
   }
-  if (!expectsModelPrefix && input.token.startsWith('@@')) {
+  if (!expectsBlockPrefix && input.token.startsWith('@@')) {
     pushDiagnostic(context, {
       code: 'PSL_INVALID_ATTRIBUTE_SYNTAX',
       message: `Attribute "${input.token}" is not valid in ${input.target} context`,
@@ -468,7 +523,7 @@ function parseAttributeToken(
     return undefined;
   }
 
-  const rawBody = expectsModelPrefix ? input.token.slice(2) : input.token.slice(1);
+  const rawBody = expectsBlockPrefix ? input.token.slice(2) : input.token.slice(1);
   const openParen = rawBody.indexOf('(');
   const closeParen = rawBody.lastIndexOf(')');
   const hasArgs = openParen >= 0 || closeParen >= 0;
@@ -504,7 +559,7 @@ function parseAttributeToken(
     const argsRaw = rawBody.slice(openParen + 1, closeParen);
     const parsedArgs = parseAttributeArguments(context, {
       argsRaw,
-      argsOffset: input.span.start.column - 1 + (expectsModelPrefix ? 2 : 1) + openParen + 1,
+      argsOffset: input.span.start.column - 1 + (expectsBlockPrefix ? 2 : 1) + openParen + 1,
       lineIndex: input.lineIndex,
       token: input.token,
       span: input.span,

packages/1-framework/2-authoring/psl-parser/src/types.ts

@@ -41,7 +41,7 @@ export interface PslDefaultLiteralValue {
 
 export type PslDefaultValue = PslDefaultFunctionValue | PslDefaultLiteralValue;
 
-export type PslAttributeTarget = 'field' | 'model' | 'namedType';
+export type PslAttributeTarget = 'field' | 'model' | 'enum' | 'namedType';
 
 export interface PslAttributePositionalArgument {
   readonly kind: 'positional';
@@ -113,6 +113,7 @@ export interface PslEnum {
   readonly kind: 'enum';
   readonly name: string;
   readonly values: readonly PslEnumValue[];
+  readonly attributes: readonly PslAttribute[];
   readonly span: PslSpan;
 }
 

packages/1-framework/2-authoring/psl-parser/test/parser.test.ts

@@ -171,6 +171,30 @@ model Account {
     });
   });
 
+  it('parses enum @@map through generic attributes', () => {
+    const schema = `
+enum UserRole {
+  USER
+  ADMIN
+  @@map("user_role")
+}
+`;
+
+    const result = parsePslDocument({
+      schema,
+      sourceId: 'schema.prisma',
+    });
+
+    expect(result.ok).toBe(true);
+    const userRole = result.ast.enums.find((enumBlock) => enumBlock.name === 'UserRole');
+    expect(userRole?.attributes.find((attribute) => attribute.name === 'map')).toMatchObject({
+      kind: 'attribute',
+      target: 'enum',
+      name: 'map',
+      args: [{ kind: 'positional', value: '"user_role"' }],
+    });
+  });
+
   it('returns diagnostics for malformed attribute syntax', () => {
     const schema = `
 model User {

packages/1-framework/2-authoring/psl-printer/README.md

@@ -0,0 +1,30 @@
+# @prisma-next/psl-printer
+
+Prints Prisma Schema Language (PSL) from introspected SQL schema IR.
+
+## Overview
+
+`@prisma-next/psl-printer` converts `SqlSchemaIR` into deterministic PSL text for brownfield authoring and database introspection flows. It is intentionally printer-only: database inspection, semantic verification, and contract emission stay in adjacent packages.
+
+## Responsibilities
+
+- Convert `SqlSchemaIR` tables, relations, enums, defaults, and indexes into valid PSL output.
+- Normalize database names into stable PSL identifiers while preserving original names with `@map` and `@@map`.
+- Preserve storage-level defaults when PSL client-side defaults would change semantics.
+- Generate deterministic output so round-tripping and snapshot-based tests remain stable.
+- Surface unsupported types and raw defaults in a way that keeps the emitted PSL readable.
+
+## Dependencies
+
+- **Depends on**
+  - `@prisma-next/contract`
+  - `@prisma-next/sql-schema-ir`
+  - `@prisma-next/utils`
+- **Used by**
+  - `@prisma-next/cli` for `db introspect`
+  - future authoring and emit flows that need PSL output from SQL schema IR
+
+## Related Docs
+
+- `docs/Architecture Overview.md`
+- `docs/architecture docs/subsystems/2. Contract Emitter & Types.md`

packages/1-framework/2-authoring/psl-printer/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@prisma-next/psl-printer",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "PSL printer: converts SqlSchemaIR to Prisma Schema Language (.prisma) files",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  },
+  "dependencies": {
+    "@prisma-next/contract": "workspace:*",
+    "@prisma-next/sql-schema-ir": "workspace:*",
+    "@prisma-next/utils": "workspace:*"
+  },
+  "devDependencies": {
+    "@prisma-next/tsconfig": "workspace:*",
+    "@prisma-next/tsdown": "workspace:*",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.mts",
+      "import": "./dist/postgres.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/1-framework/2-authoring/psl-printer"
+  }
+}

packages/1-framework/2-authoring/psl-printer/src/default-mapping.ts

@@ -0,0 +1,85 @@
+import type { ColumnDefault } from '@prisma-next/contract/types';
+
+const DEFAULT_FUNCTION_ATTRIBUTES: Readonly<Record<string, string>> = {
+  'autoincrement()': '@default(autoincrement())',
+  'now()': '@default(now())',
+};
+
+type TaggedBigInt = {
+  readonly $type: 'bigint';
+  readonly value: string;
+};
+
+export interface DefaultMappingOptions {
+  readonly functionAttributes?: Readonly<Record<string, string>>;
+  readonly fallbackFunctionAttribute?: ((expression: string) => string | undefined) | undefined;
+}
+
+/**
+ * Result of mapping a ColumnDefault to a PSL @default expression.
+ */
+export type DefaultMappingResult = { readonly attribute: string } | { readonly comment: string };
+
+/**
+ * Maps a normalized ColumnDefault to a PSL @default(...) attribute string,
+ * or a comment for unrecognized expressions.
+ */
+export function mapDefault(
+  columnDefault: ColumnDefault,
+  options?: DefaultMappingOptions,
+): DefaultMappingResult {
+  switch (columnDefault.kind) {
+    case 'literal':
+      return { attribute: `@default(${formatLiteralValue(columnDefault.value)})` };
+    case 'function': {
+      const attribute =
+        options?.functionAttributes?.[columnDefault.expression] ??
+        DEFAULT_FUNCTION_ATTRIBUTES[columnDefault.expression] ??
+        options?.fallbackFunctionAttribute?.(columnDefault.expression);
+      return attribute
+        ? { attribute }
+        : { comment: `// Raw default: ${columnDefault.expression.replace(/[\r\n]+/g, ' ')}` };
+    }
+  }
+}
+
+/**
+ * Formats a literal value for use in @default(...).
+ */
+function formatLiteralValue(value: unknown): string {
+  if (value === null) {
+    return 'null';
+  }
+  if (isTaggedBigInt(value)) {
+    return value.value;
+  }
+
+  switch (typeof value) {
+    case 'boolean':
+    case 'number':
+    case 'bigint':
+      return String(value);
+    case 'string':
+      return quoteString(value);
+    default:
+      // Fallback for complex types (arrays, objects) — not representable in PSL @default
+      return quoteString(JSON.stringify(value));
+  }
+}
+
+function isTaggedBigInt(value: unknown): value is TaggedBigInt {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '$type' in value &&
+    (value as Record<string, unknown>)['$type'] === 'bigint'
+  );
+}
+
+function quoteString(str: string): string {
+  return `"${escapeString(str)}"`;
+}
+
+function escapeString(str: string): string {
+  return JSON.stringify(str).slice(1, -1);
+}

packages/1-framework/2-authoring/psl-printer/src/exports/index.ts

@@ -0,0 +1,8 @@
+export { printPsl } from '../print-psl';
+export type {
+  PslPrintableSqlColumn,
+  PslPrintableSqlSchemaIR,
+  PslPrintableSqlTable,
+} from '../schema-validation';
+export { validatePrintableSqlSchemaIR } from '../schema-validation';
+export type { EnumInfo, PslPrinterOptions, PslTypeMap, PslTypeResolution } from '../types';

packages/1-framework/2-authoring/psl-printer/src/exports/postgres.ts

@@ -0,0 +1,8 @@
+export { createPostgresDefaultMapping } from '../postgres-default-mapping';
+export {
+  createPostgresTypeMap,
+  extractEnumDefinitions,
+  extractEnumInfo,
+  extractEnumTypeNames,
+} from '../postgres-type-map';
+export { parseRawDefault } from '../raw-default-parser';