@prisma-next/cli 0.3.0-pr.99.6 → 0.3.0

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

@@ -0,0 +1,93 @@
+# Welcome to Prisma Next!
+
+Prisma Next lets you query your database in simple, easy-to-read TypeScript. Define what your data looks like, and Prisma Next gives you a fully typed client — with autocomplete for every collection, field, and relation.
+
+This project is set up for MongoDB. Prisma Next also supports other databases.
+
+## 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")
+}
+```
+
+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
+  .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
+```
+
+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
+- **`contract.d.ts`** — this powers autocomplete and type checking in your editor
+
+Commit both files to git. When you change your contract, run `{{pkgRun}} contract emit` to update them.
+
+If you use a framework like Next.js or Vite, the Prisma Next plugin will do this for you automatically.
+
+## Configuration
+
+[`prisma-next.config.ts`](prisma-next.config.ts) tells the CLI where your contract lives and how to connect to your database. It loads environment variables from `.env` automatically:
+
+```typescript
+import 'dotenv/config';
+import { defineConfig } from '@prisma-next/mongo/config';
+
+export default defineConfig({
+  contract: './{{schemaPath}}',
+  db: {
+    connection: process.env['DATABASE_URL']!,
+  },
+});
+```
+
+Notice the `DATABASE_URL` above? It's defined in your [`.env`](./.env) file:
+
+```env
+DATABASE_URL="mongodb://localhost:27017/mydb"
+```
+
+You can customize how your environment variables are loaded by changing or removing the `import 'dotenv/config'` line.
+
+## Quick reference
+
+### Commands
+
+```bash
+{{pkgRun}} contract emit       # Update contract.json and contract.d.ts
+{{pkgRun}} db init             # Create collections in the database
+{{pkgRun}} migration status    # Show migration status
+```
+
+### Files
+
+| File | Purpose |
+|---|---|
+| [`{{schemaPath}}`]({{schemaPath}}) | Your data contract — define your models here |
+| [`prisma-next.config.ts`](prisma-next.config.ts) | CLI configuration |
+| [`{{schemaDir}}/db.ts`]({{schemaDir}}/db.ts) | Database client — `import { db } from '{{dbImportPath}}'` |
+| `{{schemaDir}}/contract.json` | Compiled contract (generated) |
+| `{{schemaDir}}/contract.d.ts` | Contract types (generated) |
+
+### Workflow
+
+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.

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

@@ -0,0 +1,91 @@
+# Welcome to Prisma Next!
+
+Prisma Next lets you query your database in simple, easy-to-read TypeScript. Define what your data looks like, and Prisma Next gives you a fully typed client — with autocomplete for every table, column, and relation.
+
+This project is set up for PostgreSQL. Prisma Next also supports other databases.
+
+## 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())
+}
+```
+
+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:
+
+```typescript
+import { db } from '{{dbImportPath}}';
+
+const user = await db.orm.User
+  .where({ email: 'alice@example.com' })
+  .first();
+
+// Your editor will show the type of user as
+// { id: number; email: string; createdAt: Date, name: string, posts: Post[] } | null
+```
+
+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
+- **`contract.d.ts`** — this powers autocomplete and type checking in your editor
+
+Commit both files to git. When you change your contract, run `{{pkgRun}} contract emit` to update them.
+
+If you use a framework like Next.js or Vite, the Prisma Next plugin will do this for you automatically.
+
+## Configuration
+
+[`prisma-next.config.ts`](prisma-next.config.ts) tells the CLI where your contract lives and how to connect to your database. It loads environment variables from `.env` automatically:
+
+```typescript
+import 'dotenv/config';
+import { defineConfig } from '@prisma-next/postgres/config';
+
+export default defineConfig({
+  contract: './{{schemaPath}}',
+  db: {
+    connection: process.env['DATABASE_URL']!,
+  },
+});
+```
+
+Notice the `DATABASE_URL` above? It's defined in your [`.env`](./.env) file:
+
+```env
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+```
+
+You can customize how your environment variables are loaded by changing or removing the `import 'dotenv/config'` line.
+
+## Quick reference
+
+### Commands
+
+```bash
+{{pkgRun}} contract emit       # Update contract.json and contract.d.ts
+{{pkgRun}} db init             # Create tables in the database
+{{pkgRun}} migration status    # Show migration status
+```
+
+### Files
+
+| File | Purpose |
+|---|---|
+| [`{{schemaPath}}`]({{schemaPath}}) | Your data contract — define your models here |
+| [`prisma-next.config.ts`](prisma-next.config.ts) | CLI configuration |
+| [`{{schemaDir}}/db.ts`]({{schemaDir}}/db.ts) | Database client — `import { db } from '{{dbImportPath}}'` |
+| `{{schemaDir}}/contract.json` | Compiled contract (generated) |
+| `{{schemaDir}}/contract.d.ts` | Contract types (generated) |
+
+### Workflow
+
+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.

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

@@ -0,0 +1,19 @@
+import { dirname } from 'pathe';
+import type { TargetId } from './code-templates';
+import { renderTemplate } from './render';
+
+export const variables = ['schemaPath', 'schemaDir', 'dbImportPath', 'pkgRun'] as const;
+
+type TemplateVars = Record<(typeof variables)[number], string>;
+
+export function quickReferenceMd(target: TargetId, schemaPath: string, pkgRun: string): string {
+  const schemaDir = dirname(schemaPath);
+  const vars: TemplateVars = {
+    schemaPath,
+    schemaDir,
+    dbImportPath: `./${schemaDir}/db`,
+    pkgRun,
+  };
+  const templateFile = `quick-reference-${target}.md`;
+  return renderTemplate(templateFile, variables, vars);
+}

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

@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'pathe';
+
+export function renderTemplate(
+  templateFile: string,
+  variableNames: readonly string[],
+  vars: Record<string, string>,
+): string {
+  const templatePath = join(import.meta.dirname, templateFile);
+  const raw = readFileSync(templatePath, 'utf-8');
+  let result = raw;
+  for (const key of variableNames) {
+    const value = vars[key];
+    if (value === undefined) {
+      throw new Error(`Template variable '${key}' is not defined`);
+    }
+    result = result.replaceAll(`{{${key}}}`, value);
+  }
+  return result;
+}

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

@@ -0,0 +1,35 @@
+export const REQUIRED_COMPILER_OPTIONS: Record<string, string | boolean> = {
+  module: 'preserve',
+  moduleResolution: 'bundler',
+  resolveJsonModule: true,
+};
+
+export function defaultTsConfig(): string {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        target: 'ES2022',
+        ...REQUIRED_COMPILER_OPTIONS,
+        strict: true,
+        skipLibCheck: true,
+        esModuleInterop: true,
+        outDir: 'dist',
+      },
+      include: ['**/*.ts'],
+    },
+    null,
+    2,
+  );
+}
+
+export function mergeTsConfig(existing: string): string {
+  const config = JSON.parse(existing) as Record<string, unknown>;
+  const compilerOptions = (config['compilerOptions'] ?? {}) as Record<string, unknown>;
+
+  for (const [key, value] of Object.entries(REQUIRED_COMPILER_OPTIONS)) {
+    compilerOptions[key] = value;
+  }
+
+  config['compilerOptions'] = compilerOptions;
+  return JSON.stringify(config, null, 2);
+}

package/src/commands/inspect-live-schema.ts

@@ -0,0 +1,170 @@
+import type { CoreSchemaView } from '@prisma-next/framework-components/control';
+import { validatePrintableSqlSchemaIR } from '@prisma-next/psl-printer';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { relative, resolve } from 'pathe';
+import { loadConfig } from '../config-loader';
+import { createControlClient } from '../control-api/client';
+import {
+  CliStructuredError,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorUnexpected,
+} from '../utils/cli-errors';
+import { maskConnectionUrl, sanitizeErrorMessage } from '../utils/command-helpers';
+import { formatStyledHeader } from '../utils/formatters/styled';
+import type { CommonCommandOptions, GlobalFlags } from '../utils/global-flags';
+import { createProgressAdapter } from '../utils/progress-adapter';
+import type { TerminalUI } from '../utils/terminal-ui';
+
+export interface InspectLiveSchemaOptions extends CommonCommandOptions {
+  readonly db?: string;
+  readonly config?: string;
+}
+
+interface InspectLiveSchemaContext {
+  readonly commandName: string;
+  readonly description: string;
+  readonly url: string;
+}
+
+type LoadedCliConfig = Awaited<ReturnType<typeof loadConfig>>;
+
+export interface InspectLiveSchemaResult {
+  readonly config: LoadedCliConfig;
+  readonly schema: unknown;
+  readonly schemaView: CoreSchemaView | undefined;
+  readonly target: {
+    readonly familyId: string;
+    readonly id: string;
+  };
+  readonly meta: {
+    readonly configPath?: string;
+    readonly dbUrl?: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+
+export async function inspectLiveSchema(
+  options: InspectLiveSchemaOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+  startTime: number,
+  context: InspectLiveSchemaContext,
+): Promise<Result<InspectLiveSchemaResult, CliStructuredError>> {
+  let config: LoadedCliConfig;
+  try {
+    config = await loadConfig(options.config);
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: 'Failed to load config',
+      }),
+    );
+  }
+
+  const configPath = options.config
+    ? relative(process.cwd(), resolve(options.config))
+    : 'prisma-next.config.ts';
+
+  if (!flags.json && !flags.quiet) {
+    const details: Array<{ label: string; value: string }> = [
+      { label: 'config', value: configPath },
+    ];
+
+    if (options.db) {
+      details.push({ label: 'database', value: maskConnectionUrl(options.db) });
+    } else if (config.db?.connection && typeof config.db.connection === 'string') {
+      details.push({ label: 'database', value: maskConnectionUrl(config.db.connection) });
+    }
+
+    ui.stderr(
+      formatStyledHeader({
+        command: context.commandName,
+        description: context.description,
+        url: context.url,
+        details,
+        flags,
+      }),
+    );
+  }
+
+  const dbConnection = options.db ?? config.db?.connection;
+  if (!dbConnection) {
+    return notOk(
+      errorDatabaseConnectionRequired({
+        why: `Database connection is required for ${context.commandName} (set db.connection in ${configPath}, or pass --db <url>)`,
+        commandName: context.commandName,
+      }),
+    );
+  }
+
+  if (!config.driver) {
+    return notOk(
+      errorDriverRequired({
+        why: `Config.driver is required for ${context.commandName}`,
+      }),
+    );
+  }
+
+  const client = createControlClient({
+    family: config.family,
+    target: config.target,
+    adapter: config.adapter,
+    driver: config.driver,
+    extensionPacks: config.extensionPacks ?? [],
+  });
+  const onProgress = createProgressAdapter({ ui, flags });
+
+  try {
+    const schemaIR = await client.introspect({
+      connection: dbConnection,
+      onProgress,
+    });
+    // TODO(TML-2251): Remove SQL-specific branching — SQL should use the same family-agnostic path as Mongo.
+    const schema =
+      config.family.familyId === 'sql' ? validatePrintableSqlSchemaIR(schemaIR) : schemaIR;
+    const schemaView = client.toSchemaView(schema);
+
+    const dbUrl = typeof dbConnection === 'string' ? maskConnectionUrl(dbConnection) : undefined;
+
+    return ok({
+      config,
+      schema,
+      schemaView,
+      target: {
+        familyId: config.family.familyId,
+        id: config.target.targetId,
+      },
+      meta: {
+        configPath,
+        ...(dbUrl ? { dbUrl } : {}),
+      },
+      timings: {
+        total: Date.now() - startTime,
+      },
+    });
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const safeMessage = sanitizeErrorMessage(
+      rawMessage,
+      typeof dbConnection === 'string' ? dbConnection : undefined,
+    );
+    return notOk(
+      errorUnexpected(safeMessage, {
+        why: `Unexpected error during ${context.commandName}: ${safeMessage}`,
+      }),
+    );
+  } finally {
+    await client.close();
+  }
+}