@njeybe/nativ 2.0.0

package/dist/db/diff.d.ts

@@ -0,0 +1,39 @@
+import type { DatabaseEngine, SchemaDiff, SchemaDiffSummary, TableDiff, TableSchema } from './types.js';
+export declare function normalizeType(type: string): string;
+export declare function normalizeDefault(value: string | null | undefined): string | null;
+export declare function diffTable(source: TableSchema, target: TableSchema): TableDiff;
+/** Computes the GET /api/diff payload for `source` applied onto `target`. */
+export declare function diffSchemas(source: TableSchema[], target: TableSchema[]): SchemaDiff;
+export type MigrationLanguage = 'sql' | 'mongodb-js' | 'firestore-json';
+export interface ContractDiffSummary extends SchemaDiffSummary {
+    addedCount: number;
+    alteredCount: number;
+    droppedCount: number;
+    unchangedCount: number;
+    /** Engine the migration script targets. */
+    engine: DatabaseEngine;
+}
+/**
+ * GET /api/diff response per .ai/api_contracts.json. The legacy *Tables keys are kept
+ * alongside the contract keys so existing studio/CLI consumers keep working.
+ */
+export interface ContractSchemaDiff extends SchemaDiff {
+    summary: ContractDiffSummary;
+    added: TableSchema[];
+    dropped: TableSchema[];
+    altered: TableDiff[];
+    unchanged: string[];
+    migrationScript: string;
+    migrationLanguage: MigrationLanguage;
+}
+export declare function toContractDiff(diff: SchemaDiff, engine: DatabaseEngine, targetLabel: string): ContractSchemaDiff;
+/** Builds the migration script for the engine being migrated (the diff target's engine). */
+export declare function generateMigrationScript(diff: SchemaDiff, engine: DatabaseEngine, targetLabel: string): {
+    script: string;
+    language: MigrationLanguage;
+};
+export declare const CONTRACT_SCHEMA_PATH: string;
+/** Engine declared in .ai/db_schema.json, if valid. */
+export declare function loadContractEngine(cwd?: string): DatabaseEngine | null;
+/** Reads table/collection definitions from .ai/db_schema.json for Live-vs-Contract drift checks. */
+export declare function loadContractTables(cwd?: string): TableSchema[];

package/dist/db/diff.js

@@ -0,0 +1,420 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Schema diff & drift engine.
+ *
+ * Direction: `source` is the desired schema (Dev, or a live DB when comparing to the contract),
+ * `target` is the schema it would be applied to (Prod, or .ai/db_schema.json).
+ *   - addedTables:   exist in source only
+ *   - droppedTables: exist in target only (applying source would drop them → destructive)
+ *   - alteredTables: exist in both but differ
+ * For altered columns, `before` is the target definition and `after` the source definition.
+ */
+// ─── Normalization ─────────────────────────────────────────────────────────────
+const TYPE_ALIASES = {
+    INT: 'INTEGER',
+    INT4: 'INTEGER',
+    INT2: 'SMALLINT',
+    INT8: 'BIGINT',
+    SERIAL: 'INTEGER',
+    SERIAL4: 'INTEGER',
+    BIGSERIAL: 'BIGINT',
+    SERIAL8: 'BIGINT',
+    BOOL: 'BOOLEAN',
+    FLOAT4: 'REAL',
+    FLOAT8: 'DOUBLE PRECISION',
+    DECIMAL: 'NUMERIC',
+    TIMESTAMPTZ: 'TIMESTAMP WITH TIME ZONE',
+    'TIMESTAMP WITHOUT TIME ZONE': 'TIMESTAMP',
+    TIMETZ: 'TIME WITH TIME ZONE',
+    'TIME WITHOUT TIME ZONE': 'TIME',
+    'CHARACTER VARYING': 'VARCHAR',
+    CHARACTER: 'CHAR',
+};
+export function normalizeType(type) {
+    const upper = type.trim().toUpperCase().replace(/\s+/g, ' ').replace(/\s*\(\s*/g, '(').replace(/\s*,\s*/g, ',').replace(/\s*\)/g, ')');
+    const match = upper.match(/^([A-Z0-9_ ]+?)(\(.*\))?(\[\])?$/);
+    if (!match)
+        return upper;
+    const [, base, args = '', array = ''] = match;
+    return `${TYPE_ALIASES[base] ?? base}${args}${array}`;
+}
+export function normalizeDefault(value) {
+    if (value == null)
+        return null;
+    let v = value.trim();
+    if (!v || v.toUpperCase() === 'NULL')
+        return null;
+    // Strip Postgres casts like 'user'::character varying or '{}'::jsonb.
+    v = v.replace(/::[a-z_][a-z0-9_ ]*(\[\])?(\([^)]*\))?/gi, '');
+    while (v.startsWith('(') && v.endsWith(')'))
+        v = v.slice(1, -1).trim();
+    const lower = v.toLowerCase();
+    if (lower === 'current_timestamp' || lower === 'current_timestamp()' || lower === 'now()')
+        return 'now()';
+    return lower;
+}
+const key = (name) => name.toLowerCase();
+function indexBy(items, keyOf) {
+    const map = new Map();
+    for (const item of items)
+        map.set(keyOf(item), item);
+    return map;
+}
+// ─── Comparison ────────────────────────────────────────────────────────────────
+/** A field counts as an image field when flagged by introspection or declared as IMAGE_URL. */
+const isMediaColumn = (c) => c.isMedia === true || normalizeType(c.type) === 'IMAGE_URL';
+function compareColumns(before, after) {
+    const changedFields = [];
+    if (normalizeType(before.type) !== normalizeType(after.type))
+        changedFields.push('type');
+    if (before.nullable !== after.nullable)
+        changedFields.push('nullable');
+    if (before.primaryKey !== after.primaryKey)
+        changedFields.push('primaryKey');
+    if (normalizeDefault(before.default) !== normalizeDefault(after.default))
+        changedFields.push('default');
+    if (isMediaColumn(before) !== isMediaColumn(after))
+        changedFields.push('isMedia');
+    return changedFields.length ? { name: after.name, before, after, changedFields } : null;
+}
+/**
+ * Changes that can lose data or fail against existing rows. Document stores have no
+ * NOT NULL constraint, so nullability changes are only destructive for SQL tables.
+ */
+function isDestructiveColumnChange(change, isCollection) {
+    return (change.changedFields.includes('type') ||
+        change.changedFields.includes('primaryKey') ||
+        (!isCollection && change.changedFields.includes('nullable') && change.before.nullable && !change.after.nullable));
+}
+const indexSignature = (idx) => `${idx.unique ? 'U' : 'N'}:${idx.columns.map(key).join(',')}`;
+// FK names are engine-specific (SQLite synthesizes them), so match on structure instead.
+const fkSignature = (fk) => `${key(fk.column)}->${key(fk.referencedTable)}.${key(fk.referencedColumn)}:${(fk.onDelete ?? 'NO ACTION').toUpperCase()}`;
+export function diffTable(source, target) {
+    const sourceCols = indexBy(source.columns, (c) => key(c.name));
+    const targetCols = indexBy(target.columns, (c) => key(c.name));
+    const addedColumns = source.columns.filter((c) => !targetCols.has(key(c.name)));
+    const droppedColumns = target.columns.filter((c) => !sourceCols.has(key(c.name)));
+    const alteredColumns = [];
+    for (const col of source.columns) {
+        const before = targetCols.get(key(col.name));
+        const change = before && compareColumns(before, col);
+        if (change)
+            alteredColumns.push(change);
+    }
+    // Indexes match by name; a same-named index with a different definition is dropped and re-added.
+    const sourceIdx = indexBy(source.indexes ?? [], (i) => key(i.name));
+    const targetIdx = indexBy(target.indexes ?? [], (i) => key(i.name));
+    const addedIndexes = (source.indexes ?? []).filter((i) => {
+        const t = targetIdx.get(key(i.name));
+        return !t || indexSignature(t) !== indexSignature(i);
+    });
+    const droppedIndexes = (target.indexes ?? []).filter((i) => {
+        const s = sourceIdx.get(key(i.name));
+        return !s || indexSignature(s) !== indexSignature(i);
+    });
+    const sourceFks = new Set((source.foreignKeys ?? []).map(fkSignature));
+    const targetFks = new Set((target.foreignKeys ?? []).map(fkSignature));
+    const addedForeignKeys = (source.foreignKeys ?? []).filter((fk) => !targetFks.has(fkSignature(fk)));
+    const droppedForeignKeys = (target.foreignKeys ?? []).filter((fk) => !sourceFks.has(fkSignature(fk)));
+    const isCollection = source.entityType === 'collection' || target.entityType === 'collection';
+    // Adding a NOT NULL column without a default fails on populated SQL tables; schemaless stores don't care.
+    const addsRequiredColumn = !isCollection && addedColumns.some((c) => !c.nullable && normalizeDefault(c.default) === null && !c.primaryKey);
+    return {
+        name: source.name,
+        addedColumns,
+        droppedColumns,
+        alteredColumns,
+        addedIndexes,
+        droppedIndexes,
+        addedForeignKeys,
+        droppedForeignKeys,
+        isDestructive: droppedColumns.length > 0 || alteredColumns.some((c) => isDestructiveColumnChange(c, isCollection)) || addsRequiredColumn,
+    };
+}
+function hasChanges(diff) {
+    return (diff.addedColumns.length +
+        diff.droppedColumns.length +
+        diff.alteredColumns.length +
+        diff.addedIndexes.length +
+        diff.droppedIndexes.length +
+        diff.addedForeignKeys.length +
+        diff.droppedForeignKeys.length >
+        0);
+}
+/** Computes the GET /api/diff payload for `source` applied onto `target`. */
+export function diffSchemas(source, target) {
+    const sourceMap = indexBy(source, (t) => key(t.name));
+    const targetMap = indexBy(target, (t) => key(t.name));
+    const addedTables = source.filter((t) => !targetMap.has(key(t.name)));
+    const droppedTables = target.filter((t) => !sourceMap.has(key(t.name)));
+    const alteredTables = [];
+    const unchangedTables = [];
+    for (const table of source) {
+        const counterpart = targetMap.get(key(table.name));
+        if (!counterpart)
+            continue;
+        const diff = diffTable(table, counterpart);
+        if (hasChanges(diff))
+            alteredTables.push(diff);
+        else
+            unchangedTables.push(table.name);
+    }
+    const byName = (a, b) => a.name.localeCompare(b.name);
+    addedTables.sort(byName);
+    droppedTables.sort(byName);
+    alteredTables.sort(byName);
+    unchangedTables.sort((a, b) => a.localeCompare(b));
+    return {
+        summary: {
+            addedTablesCount: addedTables.length,
+            alteredTablesCount: alteredTables.length,
+            droppedTablesCount: droppedTables.length,
+            unchangedTablesCount: unchangedTables.length,
+            hasDestructiveChanges: droppedTables.length > 0 || alteredTables.some((t) => t.isDestructive),
+        },
+        addedTables,
+        droppedTables,
+        alteredTables,
+        unchangedTables,
+    };
+}
+export function toContractDiff(diff, engine, targetLabel) {
+    const { script, language } = generateMigrationScript(diff, engine, targetLabel);
+    return {
+        ...diff,
+        summary: {
+            ...diff.summary,
+            addedCount: diff.summary.addedTablesCount,
+            alteredCount: diff.summary.alteredTablesCount,
+            droppedCount: diff.summary.droppedTablesCount,
+            unchangedCount: diff.summary.unchangedTablesCount,
+            engine,
+        },
+        added: diff.addedTables,
+        dropped: diff.droppedTables,
+        altered: diff.alteredTables,
+        unchanged: diff.unchangedTables,
+        migrationScript: script,
+        migrationLanguage: language,
+    };
+}
+// ─── Migration script generation (SQL DDL / MongoDB shell / Firestore index JSON) ──
+function hasDrift(d) {
+    return d.addedTables.length + d.alteredTables.length + d.droppedTables.length > 0;
+}
+function generateSql(d, dialect, targetLabel) {
+    const q = (name) => (dialect === 'mysql' ? `\`${name.split('`').join('``')}\`` : `"${name.split('"').join('""')}"`);
+    const colDef = (c) => `${q(c.name)} ${c.type}${c.nullable ? '' : ' NOT NULL'}${c.default != null ? ` DEFAULT ${c.default}` : ''}`;
+    const fkDef = (f) => `CONSTRAINT ${q(f.name)} FOREIGN KEY (${q(f.column)}) REFERENCES ${q(f.referencedTable)} (${q(f.referencedColumn)})${f.onDelete ? ` ON DELETE ${f.onDelete}` : ''}`;
+    const idxDef = (t, i) => `CREATE ${i.unique ? 'UNIQUE ' : ''}INDEX ${q(i.name)} ON ${q(t)} (${i.columns.map(q).join(', ')});`;
+    const dropIdx = (t, i) => (dialect === 'mysql' ? `DROP INDEX ${q(i.name)} ON ${q(t)};` : `DROP INDEX ${q(i.name)};`);
+    const label = dialect === 'postgresql' ? 'PostgreSQL' : dialect === 'mysql' ? 'MySQL' : 'SQLite';
+    const out = [
+        `-- nativ migration preview: Dev → ${targetLabel} (${label} dialect)`,
+        '-- Generated from structural metadata only. Review carefully; nothing is executed automatically.',
+        '',
+    ];
+    for (const t of d.addedTables) {
+        const lines = t.columns.map((c) => `  ${colDef(c)}`);
+        const pks = t.columns.filter((c) => c.primaryKey).map((c) => q(c.name));
+        if (pks.length)
+            lines.push(`  PRIMARY KEY (${pks.join(', ')})`);
+        for (const f of t.foreignKeys ?? [])
+            lines.push(`  ${fkDef(f)}`);
+        out.push(`-- [NEW TABLE] ${t.name}`, `CREATE TABLE ${q(t.name)} (\n${lines.join(',\n')}\n);`);
+        for (const i of t.indexes ?? [])
+            out.push(idxDef(t.name, i));
+        out.push('');
+    }
+    for (const t of d.alteredTables) {
+        const T = `ALTER TABLE ${q(t.name)} `;
+        out.push(`-- [ALTERED] ${t.name}${t.isDestructive ? '  ⚠ DESTRUCTIVE' : ''}`);
+        for (const f of t.droppedForeignKeys) {
+            out.push(dialect === 'sqlite' ? `-- SQLite cannot drop constraints in place; rebuild ${t.name} to remove FK ${f.name}` : `${T}${dialect === 'mysql' ? 'DROP FOREIGN KEY' : 'DROP CONSTRAINT'} ${q(f.name)};`);
+        }
+        for (const i of t.droppedIndexes)
+            out.push(dropIdx(t.name, i));
+        for (const c of t.addedColumns)
+            out.push(`${T}ADD COLUMN ${colDef(c)};`);
+        for (const ch of t.alteredColumns) {
+            const c = ch.after;
+            const f = ch.changedFields.filter((x) => x !== 'isMedia');
+            if (!f.length)
+                continue;
+            if (dialect === 'mysql') {
+                out.push(`${T}MODIFY COLUMN ${colDef(c)};`);
+                continue;
+            }
+            if (dialect === 'sqlite') {
+                out.push(`-- SQLite cannot ALTER COLUMN ${t.name}.${c.name} (${f.join(', ')}); a table rebuild is required.`);
+                continue;
+            }
+            if (f.includes('type'))
+                out.push(`${T}ALTER COLUMN ${q(c.name)} TYPE ${c.type} USING ${q(c.name)}::${c.type};`);
+            if (f.includes('nullable'))
+                out.push(`${T}ALTER COLUMN ${q(c.name)} ${c.nullable ? 'DROP NOT NULL' : 'SET NOT NULL'};`);
+            if (f.includes('default'))
+                out.push(`${T}ALTER COLUMN ${q(c.name)} ${c.default == null ? 'DROP DEFAULT' : `SET DEFAULT ${c.default}`};`);
+            if (f.includes('primaryKey'))
+                out.push(`-- Primary key membership changed for ${t.name}.${c.name}; recreate the PRIMARY KEY constraint manually.`);
+        }
+        for (const c of t.droppedColumns)
+            out.push('-- ⚠ DESTRUCTIVE: drops column data', `${T}DROP COLUMN ${q(c.name)};`);
+        for (const i of t.addedIndexes)
+            out.push(idxDef(t.name, i));
+        for (const f of t.addedForeignKeys) {
+            out.push(dialect === 'sqlite' ? `-- SQLite cannot add constraints in place; rebuild ${t.name} to add FK ${f.column} → ${f.referencedTable}` : `${T}ADD ${fkDef(f)};`);
+        }
+        out.push('');
+    }
+    for (const t of d.droppedTables) {
+        out.push(`-- ⚠ DESTRUCTIVE [DROPPED] ${t.name}: permanently deletes the table and all rows`, `DROP TABLE ${q(t.name)};`, '');
+    }
+    if (!hasDrift(d))
+        out.push('-- No schema drift. Nothing to migrate.');
+    return `${out.join('\n').replace(/\n+$/, '')}\n`;
+}
+function generateMongo(d, targetLabel) {
+    const coll = (name) => `db.getCollection(${JSON.stringify(name)})`;
+    const keySpec = (i) => `{ ${i.columns.map((c) => `${JSON.stringify(c)}: 1`).join(', ')} }`;
+    const createIdx = (t, i) => `${coll(t)}.createIndex(${keySpec(i)}, { name: ${JSON.stringify(i.name)}${i.unique ? ', unique: true' : ''} });`;
+    const out = [
+        `// nativ migration preview: Dev → ${targetLabel} (MongoDB shell)`,
+        '// Generated from structural metadata only. Review carefully; nothing is executed automatically.',
+        '',
+    ];
+    for (const t of d.addedTables) {
+        out.push(`// [NEW COLLECTION] ${t.name}`, `db.createCollection(${JSON.stringify(t.name)});`);
+        for (const i of t.indexes ?? [])
+            out.push(createIdx(t.name, i));
+        out.push('');
+    }
+    for (const t of d.alteredTables) {
+        out.push(`// [ALTERED] ${t.name}${t.isDestructive ? '  ⚠ DESTRUCTIVE' : ''}`);
+        for (const i of t.droppedIndexes)
+            out.push(`${coll(t.name)}.dropIndex(${JSON.stringify(i.name)});`);
+        for (const c of t.addedColumns) {
+            if (c.isSubcollection) {
+                out.push(`// + subcollection ${JSON.stringify(c.name)} (Firestore-only concept; model as a separate collection or embedded array)`);
+                continue;
+            }
+            const f = JSON.stringify(c.name);
+            out.push(`// + field ${f} (${c.type}): schemaless, no DDL needed. Optional backfill:`, `// ${coll(t.name)}.updateMany({ ${f}: { $exists: false } }, { $set: { ${f}: null } });`);
+        }
+        for (const ch of t.alteredColumns) {
+            out.push(`// ~ field ${JSON.stringify(ch.name)}: ${ch.before.type} → ${ch.after.type} (${ch.changedFields.join(', ')}); convert existing values with a data migration.`);
+        }
+        for (const c of t.droppedColumns) {
+            out.push('// ⚠ DESTRUCTIVE: removes field data from every document', `${coll(t.name)}.updateMany({}, { $unset: { ${JSON.stringify(c.name)}: "" } });`);
+        }
+        for (const i of t.addedIndexes)
+            out.push(createIdx(t.name, i));
+        out.push('');
+    }
+    for (const t of d.droppedTables) {
+        out.push(`// ⚠ DESTRUCTIVE [DROPPED] ${t.name}: permanently deletes the collection and all documents`, `${coll(t.name)}.drop();`, '');
+    }
+    if (!hasDrift(d))
+        out.push('// No schema drift. Nothing to migrate.');
+    return `${out.join('\n').replace(/\n+$/, '')}\n`;
+}
+/** Firestore: deployable index definitions (firestore.indexes.json shape) plus data-migration steps. */
+function generateFirestore(d, targetLabel) {
+    const indexes = [];
+    const fieldOverrides = [];
+    const steps = [];
+    const warnings = [];
+    const addIndex = (collection, i) => {
+        if (i.unique) {
+            warnings.push(`Firestore has no unique indexes: enforce uniqueness of ${collection}.${i.columns.join('+')} (${i.name}) in application code or security rules.`);
+        }
+        if (i.columns.length > 1) {
+            indexes.push({ collectionGroup: collection, queryScope: 'COLLECTION', fields: i.columns.map((f) => ({ fieldPath: f, order: 'ASCENDING' })) });
+        }
+        else if (i.columns.length === 1) {
+            fieldOverrides.push({ collectionGroup: collection, fieldPath: i.columns[0], indexes: [{ order: 'ASCENDING', queryScope: 'COLLECTION' }] });
+        }
+    };
+    for (const t of d.addedTables) {
+        steps.push({ op: 'createCollection', collection: t.name, note: 'Collections are created implicitly by the first document write.' });
+        for (const i of t.indexes ?? [])
+            addIndex(t.name, i);
+    }
+    for (const t of d.alteredTables) {
+        for (const c of t.addedColumns) {
+            steps.push(c.isSubcollection ? { op: 'addSubcollection', collection: t.name, subcollection: c.name } : { op: 'addField', collection: t.name, field: c.name, type: c.type });
+        }
+        for (const ch of t.alteredColumns) {
+            steps.push({ op: 'changeField', collection: t.name, field: ch.name, from: ch.before.type, to: ch.after.type, changed: ch.changedFields });
+        }
+        for (const c of t.droppedColumns)
+            steps.push({ op: 'deleteField', collection: t.name, field: c.name, destructive: true });
+        for (const i of t.addedIndexes)
+            addIndex(t.name, i);
+        for (const i of t.droppedIndexes)
+            steps.push({ op: 'removeIndex', collection: t.name, index: i.name, fields: i.columns });
+    }
+    for (const t of d.droppedTables) {
+        steps.push({ op: 'deleteCollection', collection: t.name, destructive: true, note: 'Permanently deletes every document (e.g. firebase firestore:delete --recursive).' });
+    }
+    const doc = {
+        _nativ: `Preview Dev → ${targetLabel} (Firestore). Nothing runs automatically.`,
+        _deploy: 'indexes + fieldOverrides: firebase deploy --only firestore:indexes; dataMigrations: apply with a script',
+        indexes,
+        fieldOverrides,
+        dataMigrations: steps,
+    };
+    if (warnings.length)
+        doc.warnings = warnings;
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}
+/** Builds the migration script for the engine being migrated (the diff target's engine). */
+export function generateMigrationScript(diff, engine, targetLabel) {
+    switch (engine) {
+        case 'mongodb':
+            return { script: generateMongo(diff, targetLabel), language: 'mongodb-js' };
+        case 'firestore':
+            return { script: generateFirestore(diff, targetLabel), language: 'firestore-json' };
+        default:
+            return { script: generateSql(diff, engine, targetLabel), language: 'sql' };
+    }
+}
+// ─── Contract source ──────────────────────────────────────────────────────────
+export const CONTRACT_SCHEMA_PATH = path.join('.ai', 'db_schema.json');
+/** Engine declared in .ai/db_schema.json, if valid. */
+export function loadContractEngine(cwd = process.cwd()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(cwd, CONTRACT_SCHEMA_PATH), 'utf8'));
+        const engines = ['postgresql', 'mysql', 'sqlite', 'mongodb', 'firestore'];
+        return engines.includes(parsed.engine) ? parsed.engine : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Reads table/collection definitions from .ai/db_schema.json for Live-vs-Contract drift checks. */
+export function loadContractTables(cwd = process.cwd()) {
+    const filePath = path.join(cwd, CONTRACT_SCHEMA_PATH);
+    if (!fs.existsSync(filePath))
+        return [];
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return (parsed.tables ?? [])
+        .filter((t) => typeof t?.name === 'string')
+        .map((t) => ({
+        name: t.name,
+        ...(t.entityType === 'collection' || t.entityType === 'table' ? { entityType: t.entityType } : {}),
+        ...(t.description ? { description: t.description } : {}),
+        columns: (t.columns ?? []).map((c) => ({
+            name: c.name,
+            type: c.type,
+            primaryKey: Boolean(c.primaryKey),
+            nullable: c.nullable !== false,
+            default: c.default ?? null,
+            ...(c.isMedia ? { isMedia: true } : {}),
+            ...(c.isSubcollection ? { isSubcollection: true } : {}),
+        })),
+        indexes: t.indexes ?? [],
+        foreignKeys: t.foreignKeys ?? [],
+    }));
+}

package/dist/db/env-parser.d.ts

@@ -0,0 +1,86 @@
+import type { ComponentEngine, ConnectionComponents, DatabaseEngine, DatabaseEnv, FirestoreConfig, FragmentedConfig, TemplateDetectionResult } from './types.js';
+/**
+ * Safe environment parser.
+ * Reads .env files locally so connection strings stay in-memory inside the nativ
+ * process. Nothing returned here for display purposes contains credentials —
+ * always pass URLs through maskConnectionString() before rendering them.
+ */
+export declare const MASK = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+/** Template files scanned to detect project-specific connection variables. */
+export declare const EXAMPLE_ENV_FILES: string[];
+export interface ResolvedConnection {
+    env: DatabaseEnv;
+    /** Raw URL. Never log, print, or serialize this value. */
+    url: string;
+    engine: DatabaseEngine;
+    maskedUrl: string;
+    sourceKey: string;
+    detectedFromExample?: boolean;
+    exampleFile?: string | null;
+    suggestion?: string | null;
+    /** True when assembled from fragmented DB_HOST/DB_DATABASE-style keys. */
+    synthesized?: boolean;
+}
+/** Parses dotenv-formatted text into key/value pairs without touching process.env. */
+export declare function parseEnvContent(content: string): Record<string, string>;
+/** Loads and merges all known .env files in `cwd`. Missing/unreadable files are skipped. */
+export declare function loadEnvFiles(cwd?: string): Record<string, string>;
+/** Infers the database engine from a connection URL or file path. */
+export declare function detectEngine(url: string): DatabaseEngine | null;
+/** Resolves a SQLite URL (`sqlite:./x.db`, `file:./x.db`, or plain path) to a filesystem path. */
+export declare function sqlitePathFromUrl(url: string, cwd?: string): string;
+/**
+ * Firestore connection URL: `firestore://<projectId>[/<databaseId>][?emulator=<host:port>]`.
+ * Credentials are never part of it: real projects use Application Default Credentials.
+ */
+export declare function parseFirestoreUrl(url: string): FirestoreConfig;
+export declare function firestoreUrlFromConfig(config: FirestoreConfig): string;
+/**
+ * Redacts credentials from a connection string.
+ * `postgres://user:secret@host:5432/db?password=x` -> `postgres://user:••••••••@host:5432/db?password=••••••••`
+ */
+export declare function maskConnectionString(url: string | null | undefined): string;
+/** Redacts signed-URL tokens from a media URL (e.g. Firebase Storage `?token=`, GCS `X-Goog-Signature`). */
+export declare function redactMediaUrl(url: string): string;
+/** Extracts the database name (or SQLite file name / Firestore project) from a connection URL for display. */
+export declare function databaseNameFromUrl(url: string): string;
+/**
+ * Scans template environment files (.env.example, .env.sample, .env.template, .env.defaults, .env.dist)
+ * to detect project-specific connection string variables, implied database engines, and whether
+ * the variables are configured in the current environment.
+ */
+export declare function detectExampleDbKeys(cwd?: string): TemplateDetectionResult;
+export declare const DEFAULT_PORTS: Record<ComponentEngine, number>;
+/** Maps a DB_CONNECTION-style driver name (mysql, mariadb, pgsql, postgres…) to an engine. */
+export declare function componentEngineFromDriver(driver: string | null | undefined): ComponentEngine | null;
+/**
+ * Assembles a connection URL from discrete parameters, percent-encoding credentials and database name.
+ * The result contains the raw password: pass it through maskConnectionString() before display.
+ */
+export declare function connectionUrlFromComponents(components: ConnectionComponents): string;
+export interface SynthesizedConnection {
+    /** Raw URL. Never log, print, or serialize this value. */
+    url: string;
+    engine: ComponentEngine;
+    /** Primary key shown as the source (the host or database key). */
+    sourceKey: string;
+    config: FragmentedConfig;
+}
+/**
+ * Detects fragmented DB_HOST / DB_PORT / DB_DATABASE / DB_USERNAME / DB_PASSWORD / DB_CONNECTION keys
+ * (plus MYSQL_* and POSTGRES_* / PG* families) and assembles a MySQL or PostgreSQL URL in-memory.
+ * Returns null when no family has a host or database configured, or the driver is not MySQL/PostgreSQL
+ * (e.g. Laravel's DB_CONNECTION=sqlite).
+ */
+export declare function synthesizeConnectionFromComponents(vars: Record<string, string>, env?: DatabaseEnv): SynthesizedConnection | null;
+export interface ResolvedConnectionsResult {
+    dev: ResolvedConnection | null;
+    prod: ResolvedConnection | null;
+    templateInfo: TemplateDetectionResult;
+}
+/**
+ * Resolves Dev and Prod connection URLs from .env files, with process.env taking precedence
+ * and template files (.env.example) dynamically prioritizing custom keys.
+ * Returns null for an environment with no configured or recognizable URL.
+ */
+export declare function resolveConnections(cwd?: string): ResolvedConnectionsResult;