@apso/cli 0.30.0 → 0.32.0

package/dist/commands/import/data.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="node" />
+import BaseCommand from "../../lib/base-command";
+import { CopyResult } from "../../lib/import";
+/** Resolve the target connection string from flag/env, else undefined. */
+export declare function resolveTargetConnectionString(flagValue: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+/** Render a copy result (or dry-run plan) as a human-readable summary. */
+export declare function formatCopyResult(result: CopyResult): string;
+export default class ImportData extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        source: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        target: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        schema: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        tables: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        "batch-size": import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        "dry-run": import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    private promptConnection;
+    run(): Promise<void>;
+}

package/dist/commands/import/data.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCopyResult = exports.resolveTargetConnectionString = void 0;
+const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
+const inquirer_1 = tslib_1.__importDefault(require("inquirer"));
+const base_command_1 = tslib_1.__importDefault(require("../../lib/base-command"));
+const import_1 = require("../../lib/import");
+const supabase_1 = require("./supabase");
+/** Resolve the target connection string from flag/env, else undefined. */
+function resolveTargetConnectionString(flagValue, env = process.env) {
+    return flagValue || env.TARGET_DATABASE_URL || env.APSO_DATABASE_URL || undefined;
+}
+exports.resolveTargetConnectionString = resolveTargetConnectionString;
+/** Render a copy result (or dry-run plan) as a human-readable summary. */
+function formatCopyResult(result) {
+    const lines = [];
+    const total = result.perTable.reduce((sum, t) => sum + t.rows, 0);
+    lines.push(result.dryRun
+        ? `Plan: ${result.perTable.length} table(s), ${total} source row(s) to copy.`
+        : `Copied ${total} row(s) across ${result.perTable.length} table(s).`);
+    for (const t of result.perTable) {
+        lines.push(`  ${t.table}: ${t.rows} row(s)`);
+    }
+    if (result.missingTargetTables.length > 0) {
+        lines.push(`  Skipped (no matching target table): ${result.missingTargetTables.join(", ")}`);
+    }
+    if (result.cyclicTables.length > 0) {
+        lines.push(`  FK cycle (copied best-effort, may need a second pass): ${result.cyclicTables.join(", ")}`);
+    }
+    if (result.skippedColumns.length > 0) {
+        lines.push("  Skipped columns:");
+        for (const s of result.skippedColumns) {
+            lines.push(`    - ${s.table}.${s.column} (${s.reason})`);
+        }
+    }
+    if (result.dryRun && result.blockedTables.length > 0) {
+        lines.push(`  WARNING: target table(s) already have rows and would block a real run: ${result.blockedTables.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+exports.formatCopyResult = formatCopyResult;
+class ImportData extends base_command_1.default {
+    async promptConnection(role) {
+        const answer = await inquirer_1.default.prompt([
+            {
+                type: "password",
+                name: "value",
+                mask: "*",
+                message: `${role} Postgres connection string:`,
+                validate: (input) => input.trim().length > 0 || "A connection string is required",
+            },
+        ]);
+        return answer.value.trim();
+    }
+    async run() {
+        const { flags } = await this.parse(ImportData);
+        const sourceConn = (0, supabase_1.resolveConnectionString)(flags.source) ||
+            (await this.promptConnection("Source"));
+        const targetConn = resolveTargetConnectionString(flags.target) ||
+            (await this.promptConnection("Target"));
+        const tableFilter = flags.tables
+            ? flags.tables.split(",").map((t) => t.trim()).filter(Boolean)
+            : undefined;
+        let sourceReader;
+        let targetWriter;
+        try {
+            this.log("Introspecting source and target schemas...");
+            const sourceSchema = await new import_1.PgIntrospector(sourceConn).introspect(flags.schema);
+            const targetSchema = await new import_1.PgIntrospector(targetConn).introspect(flags.schema);
+            const plan = (0, import_1.planCopy)(sourceSchema, (0, import_1.targetColumnsFromSchema)(targetSchema), tableFilter);
+            if (plan.tables.length === 0) {
+                this.warn("No tables to copy (no source/target table overlap).");
+                return;
+            }
+            sourceReader = await import_1.PgSourceReader.connect(sourceConn, flags.schema);
+            targetWriter = await import_1.PgTargetWriter.connect(targetConn, flags.schema);
+            if (flags["dry-run"]) {
+                const result = await (0, import_1.executeCopy)(plan, sourceReader, targetWriter, {
+                    batchSize: flags["batch-size"],
+                    dryRun: true,
+                });
+                this.log("");
+                this.log(formatCopyResult(result));
+                this.log("");
+                this.log("Dry run — no rows written.");
+                return;
+            }
+            if (!flags.yes) {
+                const tableList = plan.tables.map((t) => t.targetTable).join(", ");
+                const { confirm } = await inquirer_1.default.prompt([
+                    {
+                        type: "confirm",
+                        name: "confirm",
+                        message: `Copy data into ${plan.tables.length} target table(s) (${tableList})?`,
+                        default: false,
+                    },
+                ]);
+                if (!confirm) {
+                    this.log("Data copy cancelled.");
+                    return;
+                }
+            }
+            this.log("Copying data...");
+            const result = await (0, import_1.executeCopy)(plan, sourceReader, targetWriter, {
+                batchSize: flags["batch-size"],
+            });
+            this.log("");
+            this.log(formatCopyResult(result));
+            this.log("Done.");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const redacted = (0, import_1.redactConnectionString)(message.split(sourceConn).join("****").split(targetConn).join("****"));
+            this.error(redacted);
+        }
+        finally {
+            if (sourceReader)
+                await sourceReader.close();
+            if (targetWriter)
+                await targetWriter.close();
+        }
+    }
+}
+ImportData.description = "Copy table data from a source Supabase (Postgres) database into the target database rebuilt from the imported schema. Reads the source read-only; inserts into empty target tables.";
+ImportData.examples = [
+    `$ apso import data -s "postgresql://...source..." -t "postgresql://...target..."`,
+    `$ apso import data --dry-run`,
+    `$ apso import data --tables users,orders`,
+];
+ImportData.flags = {
+    source: core_1.Flags.string({
+        char: "s",
+        description: "Source connection string. Falls back to SUPABASE_DB_URL or DATABASE_URL, then prompts.",
+    }),
+    target: core_1.Flags.string({
+        char: "t",
+        description: "Target connection string. Falls back to TARGET_DATABASE_URL or APSO_DATABASE_URL, then prompts.",
+    }),
+    schema: core_1.Flags.string({ description: "Database schema", default: "public" }),
+    tables: core_1.Flags.string({
+        description: "Comma-separated list of source tables to copy (default: all)",
+    }),
+    "batch-size": core_1.Flags.integer({
+        description: "Rows per insert batch",
+        default: 500,
+    }),
+    "dry-run": core_1.Flags.boolean({
+        description: "Plan and report row counts without writing",
+        default: false,
+    }),
+    yes: core_1.Flags.boolean({
+        char: "y",
+        description: "Skip the confirmation prompt",
+        default: false,
+    }),
+};
+exports.default = ImportData;

package/dist/commands/import/supabase.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="node" />
+import BaseCommand from "../../lib/base-command";
+import { ApsorcImportOutput, ImportReport, Introspector } from "../../lib/import";
+/**
+ * Resolve the Postgres connection string from an explicit flag or, failing
+ * that, the SUPABASE_DB_URL / DATABASE_URL environment variables. Returns
+ * undefined if none is set (the command then prompts interactively).
+ */
+export declare function resolveConnectionString(flagValue: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Run the full introspect -> convert -> validate pipeline against any
+ * Introspector. Throws if the generated relationships fail to parse. Pure of
+ * file/console I/O so it can be unit-tested with a fake Introspector.
+ */
+export declare function importFromIntrospector(introspector: Introspector, schema: string): Promise<{
+    apsorc: ApsorcImportOutput;
+    report: ImportReport;
+    unknownTypes: string[];
+}>;
+/** Render the import report as a human-readable summary (contains no secrets). */
+export declare function formatReport(report: ImportReport): string;
+/**
+ * Write the generated .apsorc to disk, backing up any existing file first.
+ * Returns the backup path if one was made.
+ */
+export declare function writeApsorcFile(apsorc: ApsorcImportOutput, outPath: string): {
+    backupPath?: string;
+};
+export default class ImportSupabase extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        "connection-string": import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        schema: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        out: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        "dry-run": import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    /** Overridable for testing. */
+    protected makeIntrospector(connectionString: string): Introspector;
+    run(): Promise<void>;
+}

package/dist/commands/import/supabase.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeApsorcFile = exports.formatReport = exports.importFromIntrospector = exports.resolveConnectionString = void 0;
+const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const inquirer_1 = tslib_1.__importDefault(require("inquirer"));
+const base_command_1 = tslib_1.__importDefault(require("../../lib/base-command"));
+const config_1 = require("../../lib/config");
+const apsorc_parser_1 = require("../../lib/apsorc-parser");
+const relationships_1 = require("../../lib/utils/relationships");
+const import_1 = require("../../lib/import");
+/**
+ * Resolve the Postgres connection string from an explicit flag or, failing
+ * that, the SUPABASE_DB_URL / DATABASE_URL environment variables. Returns
+ * undefined if none is set (the command then prompts interactively).
+ */
+function resolveConnectionString(flagValue, env = process.env) {
+    return flagValue || env.SUPABASE_DB_URL || env.DATABASE_URL || undefined;
+}
+exports.resolveConnectionString = resolveConnectionString;
+/**
+ * Run the full introspect -> convert -> validate pipeline against any
+ * Introspector. Throws if the generated relationships fail to parse. Pure of
+ * file/console I/O so it can be unit-tested with a fake Introspector.
+ */
+async function importFromIntrospector(introspector, schema) {
+    const introspected = await introspector.introspect(schema);
+    const { apsorc, report } = (0, import_1.pgToApsorc)(introspected);
+    // Validate by running the generated relationships through the real parser.
+    (0, relationships_1.parseRelationships)(apsorc.relationships);
+    return {
+        apsorc,
+        report,
+        unknownTypes: (0, import_1.findUnknownEmittedTypes)(apsorc),
+    };
+}
+exports.importFromIntrospector = importFromIntrospector;
+/** Render the import report as a human-readable summary (contains no secrets). */
+function formatReport(report) {
+    const lines = [];
+    lines.push(`Imported ${report.tablesImported.length} table(s) and ${report.relationships} relationship(s).`);
+    if (report.tablesImported.length > 0) {
+        lines.push(`  Tables: ${report.tablesImported.join(", ")}`);
+    }
+    if (report.viewsSkipped.length > 0) {
+        lines.push(`  Skipped views: ${report.viewsSkipped.join(", ")}`);
+    }
+    if (report.systemSchemasSkipped.length > 0) {
+        lines.push(`  Skipped system schemas: ${report.systemSchemasSkipped.join(", ")}`);
+    }
+    const w = report.warnings;
+    const review = [];
+    if (w.compositePks.length > 0)
+        review.push(`  - Composite primary keys (review): ${w.compositePks.join(", ")}`);
+    if (w.nonStandardPks.length > 0)
+        review.push(`  - Non-"id" primary keys (kept as fields): ${w.nonStandardPks.join(", ")}`);
+    if (w.noPrimaryKey.length > 0)
+        review.push(`  - Tables with no primary key: ${w.noPrimaryKey.join(", ")}`);
+    if (w.compositeFks.length > 0)
+        review.push(`  - Composite foreign keys (kept as columns, no relationship): ${w.compositeFks.join(", ")}`);
+    if (w.fkColumnNameUnmapped.length > 0)
+        review.push(`  - Foreign keys whose generated column may differ: ${w.fkColumnNameUnmapped.join(", ")}`);
+    if (w.joinTablesDetected.length > 0)
+        review.push(`  - Join tables (could be modeled as ManyToMany): ${w.joinTablesDetected.join(", ")}`);
+    if (w.arraysLossy.length > 0)
+        review.push(`  - Array columns reduced to text: ${w.arraysLossy.join(", ")}`);
+    if (w.typesDefaulted.length > 0)
+        review.push(`  - Unknown types defaulted to text: ${w.typesDefaulted
+            .map((t) => `${t.column} (${t.udt})`)
+            .join(", ")}`);
+    if (w.defaultsDropped.length > 0)
+        review.push(`  - Column defaults dropped: ${w.defaultsDropped.join(", ")}`);
+    if (review.length > 0) {
+        lines.push("", "Review the following (not fully represented):", ...review);
+    }
+    return lines.join("\n");
+}
+exports.formatReport = formatReport;
+/**
+ * Write the generated .apsorc to disk, backing up any existing file first.
+ * Returns the backup path if one was made.
+ */
+function writeApsorcFile(apsorc, outPath) {
+    let backupPath;
+    if (fs.existsSync(outPath)) {
+        backupPath = (0, config_1.createBackup)(outPath);
+    }
+    fs.writeFileSync(outPath, JSON.stringify(apsorc, null, 2), "utf-8");
+    return { backupPath };
+}
+exports.writeApsorcFile = writeApsorcFile;
+class ImportSupabase extends base_command_1.default {
+    /** Overridable for testing. */
+    makeIntrospector(connectionString) {
+        return new import_1.PgIntrospector(connectionString);
+    }
+    async run() {
+        var _a, _b;
+        const { flags } = await this.parse(ImportSupabase);
+        let connectionString = resolveConnectionString(flags["connection-string"]);
+        if (!connectionString) {
+            const answer = await inquirer_1.default.prompt([
+                {
+                    type: "password",
+                    name: "connectionString",
+                    mask: "*",
+                    message: "Supabase Postgres connection string:",
+                    validate: (input) => input.trim().length > 0 || "A connection string is required",
+                },
+            ]);
+            connectionString = answer.connectionString.trim();
+        }
+        try {
+            this.log("Connecting and introspecting schema (read-only)...");
+            const introspector = this.makeIntrospector(connectionString);
+            const { apsorc, report, unknownTypes } = await importFromIntrospector(introspector, flags.schema);
+            this.log("");
+            this.log(formatReport(report));
+            if (unknownTypes.length > 0) {
+                this.warn(`Some column types were not recognized and defaulted to text: ${[
+                    ...new Set(unknownTypes),
+                ].join(", ")}`);
+            }
+            if (report.tablesImported.length === 0) {
+                this.warn(`No base tables found in schema "${flags.schema}". Nothing to write.`);
+                return;
+            }
+            if (flags["dry-run"]) {
+                this.log("");
+                this.log("Dry run — no file written.");
+                return;
+            }
+            const outPath = (_b = (_a = flags.out) !== null && _a !== void 0 ? _a : (0, apsorc_parser_1.findConfigPath)()) !== null && _b !== void 0 ? _b : path.join(process.cwd(), ".apsorc");
+            if (fs.existsSync(outPath) && !flags.yes) {
+                const { confirm } = await inquirer_1.default.prompt([
+                    {
+                        type: "confirm",
+                        name: "confirm",
+                        message: `Overwrite ${outPath} with the imported schema?`,
+                        default: false,
+                    },
+                ]);
+                if (!confirm) {
+                    this.log("Import cancelled.");
+                    return;
+                }
+            }
+            const { backupPath } = writeApsorcFile(apsorc, outPath);
+            if (backupPath)
+                this.log(`Backup created: ${backupPath}`);
+            this.log(`Schema written to ${outPath}`);
+            this.log("");
+            this.log("Next steps:");
+            this.log("  - Review the .apsorc, especially any items flagged above");
+            this.log("  - Run 'apso migrate' to validate the schema locally");
+            this.log("  - Run 'apso generate' to scaffold code");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // Defense-in-depth: never surface the connection string in an error.
+            this.error((0, import_1.redactConnectionString)(message.split(connectionString).join("****")));
+        }
+    }
+}
+ImportSupabase.description = "Introspect an existing Supabase (Postgres) database and generate a local .apsorc schema. Read-only: it never writes to the source database.";
+ImportSupabase.examples = [
+    `$ apso import supabase`,
+    `$ apso import supabase -c "postgresql://postgres:[pw]@db.[ref].supabase.co:5432/postgres"`,
+    `$ SUPABASE_DB_URL="postgresql://..." apso import supabase --dry-run`,
+];
+ImportSupabase.flags = {
+    "connection-string": core_1.Flags.string({
+        char: "c",
+        description: "Postgres connection string. Falls back to SUPABASE_DB_URL or DATABASE_URL, then prompts.",
+    }),
+    schema: core_1.Flags.string({
+        description: "Database schema to import",
+        default: "public",
+    }),
+    out: core_1.Flags.string({
+        char: "o",
+        description: "Path to write the .apsorc (default: existing .apsorc or ./.apsorc)",
+    }),
+    "dry-run": core_1.Flags.boolean({
+        description: "Introspect and print a summary without writing any file",
+        default: false,
+    }),
+    yes: core_1.Flags.boolean({
+        char: "y",
+        description: "Skip the overwrite confirmation prompt",
+        default: false,
+    }),
+};
+exports.default = ImportSupabase;

package/dist/lib/import/copy-data.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Database Import — data copy (phase 2)
+ *
+ * Plans and executes a row copy from a source Postgres/Supabase database into a
+ * target database that was rebuilt from the imported schema (phase 1). The
+ * planning logic is pure and fully unit-testable; the actual reads/writes go
+ * through the injectable `SourceReader` / `TargetWriter` interfaces so the
+ * executor can be tested with fakes (mirroring phase 1's `Introspector`).
+ *
+ * Mapping rules mirror phase 1 exactly:
+ *  - target table name  = snakeCase(entity name) = snakeCase(source table name)
+ *  - single-column FK   = renamed to the platform's camelCase `<ref>Id`
+ *  - every other column = copied under its original name
+ */
+import { IntrospectedSchema, IntrospectedTable } from "./types";
+export interface ColumnMapping {
+    sourceColumn: string;
+    targetColumn: string;
+}
+export interface TableCopyPlan {
+    sourceTable: string;
+    targetTable: string;
+    /** Kept source columns (those whose mapped target column exists), in order. */
+    sourceColumns: string[];
+    /** Target column names, parallel to sourceColumns. */
+    targetColumns: string[];
+    /** Source PK column used to order paged reads (null when there is no PK). */
+    orderBy: string | null;
+    /** Target PK column whose sequence to reset after copy (null if not serial). */
+    serialPkColumn: string | null;
+}
+export interface CopyPlan {
+    tables: TableCopyPlan[];
+    skippedColumns: Array<{
+        table: string;
+        column: string;
+        reason: string;
+    }>;
+    /** Source tables with no corresponding target table (skipped entirely). */
+    missingTargetTables: string[];
+    /** Tables involved in a FK cycle (copied best-effort, after acyclic tables). */
+    cyclicTables: string[];
+}
+/** The target table name the generator produces for a given source table. */
+export declare function targetTableName(sourceTable: string): string;
+/** Map every source column to its target column name (FK rename or identity). */
+export declare function buildColumnMapping(table: IntrospectedTable): ColumnMapping[];
+/**
+ * Order tables so each is copied after the tables it references via FK
+ * (parents before children). Self-references are ignored; tables in a cycle are
+ * reported and appended best-effort at the end.
+ */
+export declare function topoSortTables(tables: IntrospectedTable[]): {
+    order: string[];
+    cyclic: string[];
+};
+/**
+ * Build a full copy plan from the source schema and the set of columns that
+ * actually exist in each target table. Source columns whose mapped target
+ * column is missing are dropped (and reported); source tables with no target
+ * table are skipped entirely.
+ */
+export declare function planCopy(source: IntrospectedSchema, targetColumnsByTable: Map<string, Set<string>>, tableFilter?: string[]): CopyPlan;
+/** Coerce a value read from pg into something safe to bind on insert. */
+export declare function coerceValue(value: unknown): unknown;
+/** Build a parameterized multi-row INSERT statement for a batch. */
+export declare function buildInsertSql(table: string, columns: string[], rows: unknown[][], schema?: string): {
+    text: string;
+    values: unknown[];
+};
+export interface SourceReader {
+    totalRows(table: string): Promise<number>;
+    readBatch(table: string, columns: string[], orderBy: string | null, offset: number, limit: number): Promise<unknown[][]>;
+}
+export interface TargetWriter {
+    rowCount(table: string): Promise<number>;
+    insertBatch(table: string, columns: string[], rows: unknown[][]): Promise<void>;
+    resetSequence(table: string, column: string): Promise<void>;
+    begin(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}
+export interface CopyResult {
+    dryRun: boolean;
+    perTable: Array<{
+        table: string;
+        rows: number;
+    }>;
+    skippedColumns: CopyPlan["skippedColumns"];
+    missingTargetTables: string[];
+    cyclicTables: string[];
+    /** Target tables that already had rows (blocks a real, insert-only run). */
+    blockedTables: string[];
+}
+export interface ExecuteOptions {
+    batchSize?: number;
+    dryRun?: boolean;
+}
+/**
+ * Execute a copy plan. Insert-only: if any target table already has rows the
+ * run aborts before writing anything. The whole copy runs in one transaction
+ * on the target, so a failure rolls everything back.
+ */
+export declare function executeCopy(plan: CopyPlan, source: SourceReader, target: TargetWriter, options?: ExecuteOptions): Promise<CopyResult>;
+/** Build the target column lookup used by planCopy from an introspected target. */
+export declare function targetColumnsFromSchema(target: IntrospectedSchema): Map<string, Set<string>>;