turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/cli/prisma-schema.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Hand-rolled `schema.prisma` subset parser (zero dependencies).
+ *
+ * Powers `turbine migrate-from-prisma`. It parses ONLY the constructs the
+ * name-mapper needs (models, enums, views, fields, `@map`/`@@map`, relations
+ * including implicit m2m junctions, `@@unique` including named selectors, and
+ * `@@id`) and is deliberately LENIENT everywhere else: any attribute, block, or
+ * token it does not recognize is skipped and recorded as a warning, never a
+ * fatal error. The live DATABASE is the authority for resolution, so a partial
+ * parse is still useful.
+ *
+ * It is a pure leaf like `cli/destructive.ts` - it reads a string and returns
+ * data, touches no filesystem, database, or process state, and imports nothing
+ * from the rest of the package.
+ *
+ * Where it MUST understand a construct (an unterminated block/string, a broken
+ * `@@id`/`@@unique`/`@@map`/`@relation`) it throws {@link PrismaParseError} with
+ * a 1-based line number.
+ */
+/** A parsed attribute argument: positional or `key: value`, string/array/raw. */
+export interface PrismaAttrArg {
+    /** Named-argument key (e.g. `fields`, `references`, `name`, `map`). Absent for positional args. */
+    key?: string;
+    /** `'string'` (unquoted literal), `'array'` (list of idents/strings), or `'raw'` (bare token). */
+    kind: 'string' | 'array' | 'raw';
+    /** Scalar value for string/raw kinds. */
+    value?: string;
+    /** Element list for the array kind (strings unquoted). */
+    items?: string[];
+}
+/** A field- or block-level attribute (`@map(...)`, `@@unique(...)`, ...). */
+export interface PrismaAttr {
+    /** Attribute name without the leading `@`/`@@` (e.g. `map`, `relation`, `id`, `unique`). */
+    name: string;
+    /** Parsed argument list (empty when the attribute took no parens). */
+    args: PrismaAttrArg[];
+    /** True for a block attribute (`@@name`), false for a field attribute (`@name`). */
+    block: boolean;
+    /** 1-based source line the attribute was found on. */
+    line: number;
+}
+/** A parsed field line inside a model/view/type block. */
+export interface PrismaField {
+    /** Field name as declared (the Prisma API name). */
+    name: string;
+    /** Base type with `[]` / `?` stripped (a scalar, enum, or model name). */
+    type: string;
+    /** Trailing `?` - the field is optional/nullable. */
+    optional: boolean;
+    /** Trailing `[]` - the field is a list. */
+    isList: boolean;
+    /** Field attributes in source order. */
+    attrs: PrismaAttr[];
+    /** 1-based source line. */
+    line: number;
+}
+/** A compound key derived from a `@@id` / `@@unique` block attribute. */
+export interface PrismaCompoundKey {
+    /** Prisma field names participating, in declared order. */
+    fields: string[];
+    /** Explicit `name:` selector, else undefined (caller derives the underscore-join). */
+    name?: string;
+    /** Explicit `map:` constraint name, if any. */
+    map?: string;
+    /** `'id'` (from `@@id`) or `'unique'` (from `@@unique`). */
+    kind: 'id' | 'unique';
+    /** 1-based source line of the block attribute. */
+    line: number;
+}
+/** A parsed `model` / `view` / `type` block. */
+export interface PrismaModel {
+    name: string;
+    kind: 'model' | 'view' | 'type';
+    /** `@@map("...")` target table name, if present. */
+    map?: string;
+    fields: PrismaField[];
+    /** Compound keys from `@@id` and `@@unique`. */
+    compoundKeys: PrismaCompoundKey[];
+    /** Every block attribute (`@@index`, `@@schema`, ...), recorded verbatim. */
+    blockAttrs: PrismaAttr[];
+    /** 1-based source line of the block header. */
+    line: number;
+}
+/** A parsed `enum` block. */
+export interface PrismaEnum {
+    name: string;
+    /** Value names in declared order. */
+    values: string[];
+    /** `@@map("...")` target enum-type name, if present. */
+    map?: string;
+    line: number;
+}
+/**
+ * A connection-string value inside a `datasource` block: either a literal
+ * string (`url = "postgres://..."`) or an `env("NAME")` indirection.
+ */
+export type PrismaConnectionValue = {
+    kind: 'literal';
+    value: string;
+} | {
+    kind: 'env';
+    variable: string;
+};
+/** A parsed `datasource` block. Only the connection keys are retained. */
+export interface PrismaDatasource {
+    /** Block name (`datasource db { ... }` -> `db`). */
+    name: string;
+    /** `provider = "postgresql"`, when declared as a literal. */
+    provider?: string;
+    /** `url = ...`, when declared as a literal or an `env(...)` call. */
+    url?: PrismaConnectionValue;
+    /** `directUrl = ...` (Prisma's non-pooled connection), same forms as `url`. */
+    directUrl?: PrismaConnectionValue;
+    /** 1-based source line of the block header. */
+    line: number;
+}
+/** The full parse result. */
+export interface PrismaSchemaAst {
+    models: PrismaModel[];
+    enums: PrismaEnum[];
+    /** Parsed `datasource` blocks, in source order. */
+    datasources: PrismaDatasource[];
+    /** Non-fatal notes: skipped/unknown blocks and attributes. */
+    warnings: string[];
+}
+/** Thrown for a malformed construct the parser must understand. Carries a line number. */
+export declare class PrismaParseError extends Error {
+    readonly line: number;
+    constructor(message: string, line: number);
+}
+/** Where a datasource connection string was resolved from. */
+export interface ResolvedPrismaDatasourceUrl {
+    /** The connection string itself. */
+    url: string;
+    /** Datasource block name it came from. */
+    datasource: string;
+    /** Which key supplied it. */
+    key: 'url' | 'directUrl';
+    /** The environment variable read, when the value was an `env(...)` call. */
+    variable?: string;
+}
+/** Result of {@link resolvePrismaDatasourceUrl}. */
+export interface PrismaDatasourceUrlLookup {
+    /** The first usable connection string found, if any. */
+    resolved?: ResolvedPrismaDatasourceUrl;
+    /**
+     * Environment variable names the schema declares via `env(...)` that were
+     * unset or empty, in lookup order. Surfaced in the no-URL error so the user
+     * sees exactly which variable the schema asked for.
+     */
+    missingVariables: string[];
+}
+/**
+ * Resolve the connection string a `schema.prisma` declares, reading `env(...)`
+ * indirections out of the supplied environment (pure: the environment is an
+ * argument, never `process.env` directly).
+ *
+ * Per datasource block, `url` is preferred and `directUrl` is the fallback:
+ * `url` is what Prisma itself uses for everything but migrations, and a pooled
+ * `url` introspects the same catalog as its direct twin.
+ */
+export declare function resolvePrismaDatasourceUrl(ast: Pick<PrismaSchemaAst, 'datasources'>, env: Record<string, string | undefined>): PrismaDatasourceUrlLookup;
+/**
+ * Parse a `schema.prisma` source string into a {@link PrismaSchemaAst}.
+ *
+ * Understands: model / view / type / enum blocks; field lines with `@map`,
+ * `@id`, `@unique`, `@default`, `@updatedAt`, `@ignore`, `@relation`; and block
+ * attributes `@@map`, `@@id`, `@@unique`, `@@index`, `@@schema`; plus the
+ * `provider` / `url` / `directUrl` keys of each `datasource` block (see
+ * {@link resolvePrismaDatasourceUrl}). Unknown attributes and blocks are
+ * skipped into {@link PrismaSchemaAst.warnings}.
+ *
+ * @throws {@link PrismaParseError} on an unterminated block/paren/string or a
+ *   structurally broken `@@id` / `@@unique` / `@@map`.
+ */
+export declare function parsePrismaSchema(source: string): PrismaSchemaAst;

package/dist/cjs/cli/prisma-schema.js

@@ -20,6 +20,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PrismaParseError = void 0;
+exports.resolvePrismaDatasourceUrl = resolvePrismaDatasourceUrl;
 exports.parsePrismaSchema = parsePrismaSchema;
 // ---------------------------------------------------------------------------
 // Error
@@ -437,6 +438,78 @@ function parseEnumBody(block, src) {
     }
     return en;
 }
+/**
+ * Parse a `datasource` block value: a quoted literal, or an `env("NAME")` call.
+ * Returns null for any other form (e.g. an interpolated expression), which the
+ * caller records as "declared but not usable" rather than guessing.
+ */
+function parseConnectionValue(raw) {
+    if (/^"(?:[^"\\]|\\.)*"$/.test(raw))
+        return { kind: 'literal', value: unquote(raw) };
+    const envCall = raw.match(/^env\(\s*("(?:[^"\\]|\\.)*")\s*\)$/);
+    if (envCall) {
+        const variable = unquote(envCall[1]);
+        return variable ? { kind: 'env', variable } : null;
+    }
+    return null;
+}
+/**
+ * Parse a `datasource` block. Only `provider`, `url`, and `directUrl` are kept;
+ * every other key (`shadowDatabaseUrl`, `relationMode`, `extensions`, ...) is
+ * irrelevant to name mapping and skipped silently, as before.
+ */
+function parseDatasourceBody(block, src) {
+    const ds = { name: block.name, line: block.headerLine };
+    for (const { text } of bodyLines(block.body, block.bodyOffset, src)) {
+        const m = text.match(/^([A-Za-z_]\w*)\s*=\s*(.+)$/);
+        if (!m)
+            continue;
+        const key = m[1];
+        const raw = m[2].trim();
+        if (key === 'provider') {
+            const value = parseConnectionValue(raw);
+            if (value?.kind === 'literal')
+                ds.provider = value.value;
+        }
+        else if (key === 'url' || key === 'directUrl') {
+            const value = parseConnectionValue(raw);
+            if (value)
+                ds[key] = value;
+        }
+    }
+    return ds;
+}
+/**
+ * Resolve the connection string a `schema.prisma` declares, reading `env(...)`
+ * indirections out of the supplied environment (pure: the environment is an
+ * argument, never `process.env` directly).
+ *
+ * Per datasource block, `url` is preferred and `directUrl` is the fallback:
+ * `url` is what Prisma itself uses for everything but migrations, and a pooled
+ * `url` introspects the same catalog as its direct twin.
+ */
+function resolvePrismaDatasourceUrl(ast, env) {
+    const missingVariables = [];
+    for (const ds of ast.datasources) {
+        for (const key of ['url', 'directUrl']) {
+            const value = ds[key];
+            if (!value)
+                continue;
+            if (value.kind === 'literal') {
+                if (value.value)
+                    return { resolved: { url: value.value, datasource: ds.name, key }, missingVariables };
+                continue;
+            }
+            const fromEnv = env[value.variable];
+            if (fromEnv) {
+                return { resolved: { url: fromEnv, datasource: ds.name, key, variable: value.variable }, missingVariables };
+            }
+            if (!missingVariables.includes(value.variable))
+                missingVariables.push(value.variable);
+        }
+    }
+    return { missingVariables };
+}
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
@@ -445,15 +518,17 @@ function parseEnumBody(block, src) {
  *
  * Understands: model / view / type / enum blocks; field lines with `@map`,
  * `@id`, `@unique`, `@default`, `@updatedAt`, `@ignore`, `@relation`; and block
- * attributes `@@map`, `@@id`, `@@unique`, `@@index`, `@@schema`. Unknown
- * attributes and blocks are skipped into {@link PrismaSchemaAst.warnings}.
+ * attributes `@@map`, `@@id`, `@@unique`, `@@index`, `@@schema`; plus the
+ * `provider` / `url` / `directUrl` keys of each `datasource` block (see
+ * {@link resolvePrismaDatasourceUrl}). Unknown attributes and blocks are
+ * skipped into {@link PrismaSchemaAst.warnings}.
  *
  * @throws {@link PrismaParseError} on an unterminated block/paren/string or a
  *   structurally broken `@@id` / `@@unique` / `@@map`.
  */
 function parsePrismaSchema(source) {
     const src = stripComments(source);
-    const ast = { models: [], enums: [], warnings: [] };
+    const ast = { models: [], enums: [], datasources: [], warnings: [] };
     for (const block of scanBlocks(src)) {
         switch (block.keyword) {
             case 'model':
@@ -472,8 +547,11 @@ function parsePrismaSchema(source) {
                 ast.enums.push(parseEnumBody(block, src));
                 break;
             case 'datasource':
+                // Not a table, but it declares the connection string the CLI can reuse.
+                ast.datasources.push(parseDatasourceBody(block, src));
+                break;
             case 'generator':
-                // Configuration blocks - irrelevant to name mapping.
+                // Configuration block - irrelevant to name mapping.
                 break;
             default:
                 ast.warnings.push(`Skipped unsupported block "${block.keyword} ${block.name}".`);

package/dist/cjs/cli/rate-limit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * turbine-orm CLI: fixed-window rate limiter
+ *
+ * A pure leaf module (same role as `cli/destructive.ts`): no imports beyond a
+ * Node type, no I/O, no state of its own. Both local servers, Studio and
+ * Observe, throttle through it so they behave identically without either one
+ * importing the other. Studio in particular statically pulls in the embedded
+ * UI, the demo store, PII redaction and QueryInterface, none of which Observe
+ * has any use for.
+ */
+import type { IncomingMessage } from 'node:http';
+export declare const RATE_LIMIT_WINDOW_MS = 60000;
+export declare const RATE_LIMIT_MAX_REQUESTS = 100;
+/**
+ * Bucket identity for one caller. These are loopback tools with a single shared
+ * token, so the remote address is the only thing that distinguishes one client
+ * from another; requests with no socket (in-process dispatch) share one key.
+ */
+export declare function callerKey(req: IncomingMessage): string;
+export interface RateLimitResult {
+    allowed: boolean;
+    resetAt: number;
+}
+/**
+ * Fixed-window counter. `limiter` is the caller's own state map (each server
+ * owns one, so exhausting one server's budget never touches the other's) and
+ * `token` is the bucket key, not a credential.
+ */
+export declare function checkRateLimit(limiter: Map<string, {
+    count: number;
+    resetAt: number;
+}>, token: string): RateLimitResult;

package/dist/cjs/cli/rate-limit.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * turbine-orm CLI: fixed-window rate limiter
+ *
+ * A pure leaf module (same role as `cli/destructive.ts`): no imports beyond a
+ * Node type, no I/O, no state of its own. Both local servers, Studio and
+ * Observe, throttle through it so they behave identically without either one
+ * importing the other. Studio in particular statically pulls in the embedded
+ * UI, the demo store, PII redaction and QueryInterface, none of which Observe
+ * has any use for.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RATE_LIMIT_MAX_REQUESTS = exports.RATE_LIMIT_WINDOW_MS = void 0;
+exports.callerKey = callerKey;
+exports.checkRateLimit = checkRateLimit;
+exports.RATE_LIMIT_WINDOW_MS = 60_000; // 60 seconds
+exports.RATE_LIMIT_MAX_REQUESTS = 100;
+/**
+ * Bucket identity for one caller. These are loopback tools with a single shared
+ * token, so the remote address is the only thing that distinguishes one client
+ * from another; requests with no socket (in-process dispatch) share one key.
+ */
+function callerKey(req) {
+    return req.socket?.remoteAddress ?? 'unknown';
+}
+/**
+ * Fixed-window counter. `limiter` is the caller's own state map (each server
+ * owns one, so exhausting one server's budget never touches the other's) and
+ * `token` is the bucket key, not a credential.
+ */
+function checkRateLimit(limiter, token) {
+    const now = Date.now();
+    const entry = limiter.get(token);
+    if (!entry || now >= entry.resetAt) {
+        // Start a new window
+        const resetAt = now + exports.RATE_LIMIT_WINDOW_MS;
+        limiter.set(token, { count: 1, resetAt });
+        return { allowed: true, resetAt };
+    }
+    entry.count++;
+    if (entry.count > exports.RATE_LIMIT_MAX_REQUESTS) {
+        return { allowed: false, resetAt: entry.resetAt };
+    }
+    return { allowed: true, resetAt: entry.resetAt };
+}

package/dist/cjs/cli/studio-demo.d.ts

@@ -0,0 +1,43 @@
+/**
+ * turbine-orm CLI: Studio demo mode (`turbine studio --demo`)
+ *
+ * Boots Studio with NO database and NO DATABASE_URL: a baked-in, seeded sample
+ * dataset served from an in-memory engine. It is the "feel the product in 10
+ * seconds" experience: read mode, PII redaction, and the single-row write flow,
+ * all safely fake.
+ *
+ * The store is backed by Turbine's OWN SQLite engine over `node:sqlite`'s
+ * `:memory:` database (a built-in on Node >= 22.5, zero new dependency). Because
+ * `:memory:` is per-handle, the store dies with the process and every launch
+ * starts pristine: writes genuinely apply (edits stick, a refresh shows them)
+ * but nothing is ever persisted anywhere.
+ *
+ * This module lives under `src/cli/` (coverage-excluded, never imported by
+ * library code) and reuses `SqlitePool` + `sqliteDialect` from `../sqlite.js`;
+ * it never writes its own SQL evaluator.
+ */
+import type { PgCompatPool } from '../client.js';
+import type { Dialect } from '../dialect.js';
+import type { SchemaMetadata } from '../schema.js';
+/**
+ * The seeded sample schema. Four tables with realistic relations; `email` and
+ * `phone` are tagged `pii` so Studio's redaction path is exercised out of the
+ * box.
+ */
+export declare const DEMO_SCHEMA: SchemaMetadata;
+export interface DemoContext {
+    /** In-memory SQLite pool (pg-compatible) backing the demo store. */
+    pool: PgCompatPool;
+    /** The seeded sample schema metadata. */
+    metadata: SchemaMetadata;
+    /** The SQLite dialect the Studio handlers compile against in demo mode. */
+    dialect: Dialect;
+}
+/**
+ * Open a fresh, seeded in-memory demo store and return the pool + metadata +
+ * dialect Studio needs. Each call yields an independent, pristine database
+ * (`:memory:` is per-handle), so demo launches never share state.
+ *
+ * @throws Error on Node < 22.5 (no built-in `node:sqlite`).
+ */
+export declare function createDemoContext(): DemoContext;

package/dist/cjs/cli/studio-ui.generated.d.ts

@@ -0,0 +1 @@
+export declare const STUDIO_HTML: string;

package/dist/cjs/cli/studio.d.ts

@@ -0,0 +1,207 @@
+/**
+ * turbine-orm CLI: Studio
+ *
+ * A local web UI for browsing databases, exploring relations, and composing
+ * queries visually. ORM-native since v0.19: there is no raw-SQL input surface.
+ * The Query tab builds `findMany` args that are validated against introspected
+ * metadata and compiled by QueryInterface (`/api/builder`). Pure Node (built-in
+ * `http` module), no runtime dependencies beyond `pg`. CLI defaults to 127.0.0.1
+ * and refuses non-loopback hosts unless `npx turbine studio --allow-remote`.
+ *
+ * Read-only by default. `turbine studio --write` opts in to single-row writes
+ * (see the write model below); without the flag the write API routes do not
+ * exist (they 404) and the UI renders no write affordances.
+ *
+ * Security model:
+ *   • Loopback by default; CLI refuses non-loopback without --allow-remote
+ *   • Random auth token generated per process, required in Cookie header
+ *   • No SQL input surface at all: every identifier in a builder or write
+ *     request is validated against the introspected schema; all values are
+ *     $N params compiled through the query builders
+ *   • Read routes run in a READ ONLY transaction (belt-and-suspenders)
+ *   • Write routes (only when `--write` is set) run in a plain BEGIN/COMMIT
+ *     transaction, require a matching Origin header (CSRF), and address every
+ *     row by its full primary key (single row, or a capped `rows` array of
+ *     PK-addressed statements run atomically)
+ *   • 30s statement timeout via parameterized set_config()
+ *   • Per-session rate limiting, cross-origin refusal, security headers, and a
+ *     per-request CSP nonce for the inline script (no `unsafe-inline`)
+ *
+ * PII: columns tagged `pii` in code-first metadata are redacted server-side in
+ * every row-bearing response (the literal `•• redacted ••`) unless the server
+ * was started with `--show-pii`.
+ *
+ * Write model (opt-in): update a single row; insert/delete one row or a capped
+ * list of PK-addressed rows in one all-or-nothing transaction. DDL and
+ * predicate-based (unconditional) writes are deliberately unsupported. Use the
+ * CLI or migrate for schema changes and true bulk operations.
+ */
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import type { PgCompatPool } from '../client.js';
+import type { Dialect } from '../dialect.js';
+import type { SchemaMetadata, TableMetadata } from '../schema.js';
+export interface StudioOptions {
+    url: string;
+    schema: string;
+    port: number;
+    host: string;
+    openBrowser: boolean;
+    include?: string[];
+    exclude?: string[];
+    /** Directory where studio-queries.json is persisted. Defaults to `.turbine/` in cwd. */
+    stateDir?: string;
+    /** Database adapter for dialect-specific behavior (e.g. statement timeout syntax). */
+    adapter?: import('../adapters/index.js').DatabaseAdapter;
+    /**
+     * Opt in to single-row write routes (`/api/row/update|insert|delete`) and the
+     * write UI. Default `false`: read-only, with the write routes absent (404).
+     */
+    write?: boolean;
+    /**
+     * Reveal PII-tagged column values instead of redacting them. Default `false`.
+     */
+    showPii?: boolean;
+    /**
+     * Boot with a seeded, in-memory sample database instead of connecting to a
+     * real one (no DATABASE_URL required). Backed by Turbine's own SQLite engine
+     * over `node:sqlite` `:memory:`; nothing is ever persisted. Enables the live
+     * three-mode switcher (`/api/demo/mode`). Default `false`.
+     */
+    demo?: boolean;
+    /**
+     * Directory holding generated Turbine metadata (`turbine generate`'s `out`).
+     * PII tags are code-first declarations that introspection never sets, so
+     * without this Studio's redaction has nothing to redact against a real
+     * database. Read as text; nothing from it is executed. See `pii-tags.ts`.
+     */
+    metadataDir?: string;
+}
+export interface StudioHandle {
+    /** Shut down the server + pool cleanly. */
+    dispose: () => Promise<void>;
+    /**
+     * Where PII tags came from, so the CLI can say so at startup. `null` when no
+     * generated metadata was found: redaction is then inert and the user needs to
+     * know that rather than assume protection.
+     */
+    piiTags: {
+        path: string;
+        applied: number;
+    } | null;
+    /** Random per-process session token the UI sends via cookie. */
+    authToken: string;
+    /** Full URL including `?token=...`, safe to print for the user. */
+    url: string;
+}
+export interface StudioContext {
+    /**
+     * The pg-compatible pool. A real `pg.Pool` in normal mode, a `SqlitePool`
+     * over an in-memory database in demo mode. Typed as the minimal
+     * `PgCompatPool` contract so both shapes work through one code path (pg.Pool
+     * satisfies it; the query builders take `pg.Pool` via a cast, matching the
+     * external-pool seam in client.ts).
+     */
+    pool: PgCompatPool;
+    metadata: SchemaMetadata;
+    options: StudioOptions;
+    authToken: string;
+    stateDir: string;
+    /** Resolved statement timeout (adapter-aware): parameterized SQL + values. */
+    statementTimeout: {
+        sql: string;
+        params: unknown[];
+    };
+    /** Rate limiter state: tracks requests per authenticated session. */
+    rateLimiter: Map<string, {
+        count: number;
+        resetAt: number;
+    }>;
+    /**
+     * True when write mode is enabled (`--write`): the `/api/row/*` routes exist
+     * and the UI renders write affordances. Absent/false → read-only. In demo
+     * mode this is toggled live by the `/api/demo/mode` switcher.
+     */
+    writable?: boolean;
+    /** True when PII redaction is disabled (`--show-pii`). Absent/false → redact. */
+    showPii?: boolean;
+    /**
+     * True when Studio is running against the seeded in-memory demo store
+     * (`--demo`). Branches the handful of Postgres-specific statements onto their
+     * SQLite equivalents and enables the `/api/demo/mode` live switcher.
+     */
+    demo?: boolean;
+    /**
+     * SQL dialect the builder/write handlers compile against. Absent → Postgres
+     * (the default). Set to the SQLite dialect in demo mode.
+     */
+    dialect?: Dialect;
+    /**
+     * Demo mode only: saved queries live here instead of on disk, honoring the
+     * "nothing you do here is saved anywhere" promise. Absent in normal mode
+     * (saved queries persist to `<stateDir>/studio-queries.json`).
+     */
+    memorySavedQueries?: SavedQueriesFile;
+}
+/**
+ * Start the Studio server. Returns a handle with the session token, a pre-built
+ * URL (including the token) that the CLI can print, and a disposer.
+ *
+ * Typical usage from the CLI:
+ *   const studio = await startStudio(options);
+ *   console.log(studio.url);
+ *   process.on('SIGINT', () => studio.dispose().then(() => process.exit(0)));
+ */
+export declare function startStudio(options: StudioOptions): Promise<StudioHandle>;
+export declare function handleRequest(req: IncomingMessage, res: ServerResponse, ctx: StudioContext): Promise<void>;
+export declare function apiDemoMode(req: IncomingMessage, res: ServerResponse, ctx: StudioContext): Promise<void>;
+/** One clickable reference from a column on this table to a row in another. */
+export interface ForeignKeyLink {
+    /** Column on THIS table whose cell becomes the link. */
+    column: string;
+    /** Relation the link was derived from. */
+    relation: string;
+    /** Table the reference points at. */
+    targetTable: string;
+    /** Column on the target table the value is matched against. */
+    targetColumn: string;
+}
+/** One reverse jump: rows in a child table that reference this table. */
+export interface ReferencedByLink {
+    /** Column on THIS table whose value the child column matches (usually the PK). */
+    column: string;
+    /** Relation the link was derived from. */
+    relation: string;
+    /** Child table holding the referencing rows. */
+    targetTable: string;
+    /** Referencing column on the child table. */
+    targetColumn: string;
+}
+export declare function relationLinksForTable(table: TableMetadata, metadata: SchemaMetadata, showPii: boolean): {
+    foreignKeys: ForeignKeyLink[];
+    referencedBy: ReferencedByLink[];
+};
+export declare function apiTableRows(res: ServerResponse, ctx: StudioContext, rawTableName: string, params: URLSearchParams): Promise<void>;
+export declare function resolveColumnName(table: TableMetadata, nameOrField: string): string | null;
+export declare function isTextishType(pgType: string): boolean;
+export declare function escapeLikePattern(s: string): string;
+export declare function apiBuilder(req: IncomingMessage, res: ServerResponse, ctx: StudioContext): Promise<void>;
+export declare function apiRowWrite(req: IncomingMessage, res: ServerResponse, ctx: StudioContext, op: 'update' | 'insert' | 'delete'): Promise<void>;
+interface SavedQuery {
+    id: string;
+    table: string;
+    name: string;
+    /** Studio only saves visual-builder queries: there is no raw-SQL surface. */
+    kind: 'builder';
+    args?: unknown;
+    createdAt: string;
+}
+interface SavedQueriesFile {
+    version: 1;
+    queries: SavedQuery[];
+}
+export declare function apiListSavedQueries(res: ServerResponse, ctx: StudioContext, params: URLSearchParams): void;
+export declare function apiCreateSavedQuery(req: IncomingMessage, res: ServerResponse, ctx: StudioContext): Promise<void>;
+export declare function apiDeleteSavedQuery(res: ServerResponse, ctx: StudioContext, id: string): void;
+/** The literal replacement value for a redacted PII cell. */
+export declare const PII_REDACTED = "\u2022\u2022 redacted \u2022\u2022";
+export {};