@apso/cli 0.30.0 → 0.32.0

package/dist/lib/import/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Database Import — intermediate model
+ *
+ * These types are the contract between the introspection layer (which reads a
+ * live Postgres database) and the conversion layer (which turns that into a
+ * `.apsorc`). Keeping the introspector behind the `Introspector` interface lets
+ * the conversion logic and the command be unit-tested with a fake source,
+ * without a real database connection.
+ */
+/** ON DELETE referential action of a foreign key. */
+export type OnDeleteAction = "CASCADE" | "RESTRICT" | "SET NULL" | "NO ACTION" | "SET DEFAULT";
+/** A single introspected column. */
+export interface IntrospectedColumn {
+    name: string;
+    /** pg_catalog udt_name, e.g. "int4", "varchar", "_text", "timestamptz". */
+    udtName: string;
+    /** information_schema.data_type, used to detect "USER-DEFINED" (enum) and "ARRAY". */
+    dataType: string;
+    nullable: boolean;
+    /** Raw default expression, e.g. "nextval('...')", "now()", "'active'::text". */
+    default: string | null;
+    charMaxLength: number | null;
+    numericPrecision: number | null;
+    numericScale: number | null;
+    ordinal: number;
+    /** True when the column's type is a user-defined enum. */
+    isEnum: boolean;
+    /** Links to IntrospectedEnum.name when isEnum is true. */
+    enumTypeName?: string;
+}
+/** A foreign key constraint (may be composite). */
+export interface IntrospectedFk {
+    /** Local column(s) participating in the FK. */
+    columns: string[];
+    referencedTable: string;
+    referencedColumns: string[];
+    onDelete: OnDeleteAction;
+}
+/** A unique constraint (may be composite). */
+export interface IntrospectedUnique {
+    name: string;
+    columns: string[];
+}
+/** A secondary index (may be composite). */
+export interface IntrospectedIndex {
+    name: string;
+    columns: string[];
+    unique: boolean;
+}
+/** A user-defined enum type and its labels (in sort order). */
+export interface IntrospectedEnum {
+    name: string;
+    labels: string[];
+}
+/** A single introspected base table. */
+export interface IntrospectedTable {
+    name: string;
+    columns: IntrospectedColumn[];
+    /** Ordered primary-key column names ([] if the table has no primary key). */
+    primaryKey: string[];
+    foreignKeys: IntrospectedFk[];
+    uniqueConstraints: IntrospectedUnique[];
+    indexes: IntrospectedIndex[];
+}
+/** The full result of introspecting one Postgres schema. */
+export interface IntrospectedSchema {
+    schema: string;
+    tables: IntrospectedTable[];
+    enums: IntrospectedEnum[];
+    /** Objects intentionally not imported, surfaced in the summary report. */
+    skipped: {
+        views: string[];
+        systemSchemas: string[];
+    };
+}
+/**
+ * The boundary the command depends on. The real implementation
+ * (PgIntrospector) connects to Postgres; tests provide a fake.
+ */
+export interface Introspector {
+    introspect(schema: string): Promise<IntrospectedSchema>;
+}
+/**
+ * Everything the import couldn't represent losslessly, plus counts, used to
+ * print a summary the user can review before/after writing the `.apsorc`.
+ */
+export interface ImportReport {
+    tablesImported: string[];
+    relationships: number;
+    viewsSkipped: string[];
+    systemSchemasSkipped: string[];
+    warnings: {
+        /** "table.column" whose Postgres array type was reduced to text. */
+        arraysLossy: string[];
+        /** Tables with composite primary keys (emitted as primary:true fields). */
+        compositePks: string[];
+        /** Tables with composite foreign keys (kept as scalar columns, no relationship). */
+        compositeFks: string[];
+        /** Tables whose single PK is not named "id" (emitted as a primary:true field). */
+        nonStandardPks: string[];
+        /** Tables with no primary key at all. */
+        noPrimaryKey: string[];
+        /** Columns whose type was unknown and defaulted to text. */
+        typesDefaulted: Array<{
+            column: string;
+            udt: string;
+        }>;
+        /** FK columns whose name could not be round-tripped to a relationship name. */
+        fkColumnNameUnmapped: string[];
+        /** "table.column" defaults that were dropped (unsupported expressions). */
+        defaultsDropped: string[];
+        /** Tables that look like pure join tables (candidates for manual ManyToMany). */
+        joinTablesDetected: string[];
+    };
+}

package/dist/lib/import/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Database Import — intermediate model
+ *
+ * These types are the contract between the introspection layer (which reads a
+ * live Postgres database) and the conversion layer (which turns that into a
+ * `.apsorc`). Keeping the introspector behind the `Introspector` interface lets
+ * the conversion logic and the command be unit-tested with a fake source,
+ * without a real database connection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@apso/cli",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@apso/cli",
-      "version": "0.30.0",
+      "version": "0.32.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@biomejs/biome": "^1.9.4",
@@ -22,6 +22,7 @@
         "eta": "^2.0.0",
         "inquirer": "^8.2.7",
         "ora": "^5.4.1",
+        "pg": "^8.21.0",
         "pluralize": "^8.0.0",
         "posthog-node": "^5.21.2",
         "rc": "^1.2.8",
@@ -41,6 +42,7 @@
         "@types/inquirer": "^8.2.12",
         "@types/mocha": "^10",
         "@types/node": "^20.19.43",
+        "@types/pg": "^8.20.0",
         "@types/pluralize": "^0.0.29",
         "@types/rc": "^1.2.1",
         "@types/shelljs": "^0.8.15",
@@ -2877,6 +2879,18 @@
       "integrity": "sha512-Gj7cI7z+98M282Tqmp2K5EIsoouUEzbBJhQQzDE3jSIRk6r9gsz0oUokqIUR4u1R3dMHo0pDHM7sNOHyhulypw==",
       "dev": true
     },
+    "node_modules/@types/pg": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/@types/pg/-/pg-8.20.0.tgz",
+      "integrity": "sha512-bEPFOaMAHTEP1EzpvHTbmwR8UsFyHSKsRisLIHVMXnpNefSbGA1bD6CVy+qKjGSqmZqNqBDV2azOBo8TgkcVow==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "pg-protocol": "*",
+        "pg-types": "^2.2.0"
+      }
+    },
     "node_modules/@types/pluralize": {
       "version": "0.0.29",
       "resolved": "https://registry.npmjs.org/@types/pluralize/-/pluralize-0.0.29.tgz",
@@ -13612,6 +13626,95 @@
         "node": "*"
       }
     },
+    "node_modules/pg": {
+      "version": "8.22.0",
+      "resolved": "https://registry.npmjs.org/pg/-/pg-8.22.0.tgz",
+      "integrity": "sha512-8wih1vVIBMxoUM2oB4soJsD9tDnDpLv4OXBJ+EJzFsvycD+lfyIreC2gGHq78f8jbLLt+bvlPTFdFZfJkOuzAA==",
+      "license": "MIT",
+      "dependencies": {
+        "pg-connection-string": "^2.14.0",
+        "pg-pool": "^3.14.0",
+        "pg-protocol": "^1.15.0",
+        "pg-types": "2.2.0",
+        "pgpass": "1.0.5"
+      },
+      "engines": {
+        "node": ">= 16.0.0"
+      },
+      "optionalDependencies": {
+        "pg-cloudflare": "^1.4.0"
+      },
+      "peerDependencies": {
+        "pg-native": ">=3.0.1"
+      },
+      "peerDependenciesMeta": {
+        "pg-native": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/pg-cloudflare": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/pg-cloudflare/-/pg-cloudflare-1.4.0.tgz",
+      "integrity": "sha512-Vo7z/6rrQYxpNRylp4Tlob2elzbh+N/MOQbxFVWCxS7oEx6jF53GTJFxK2WWpKuBRkmiin4Mt+xofFDjx09R0A==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/pg-connection-string": {
+      "version": "2.14.0",
+      "resolved": "https://registry.npmjs.org/pg-connection-string/-/pg-connection-string-2.14.0.tgz",
+      "integrity": "sha512-XwWDGcLRGCXAR8F/AM5bG7Q+A3Wm2s6QeEjlOKZLlH3UYcguiqCWKyWXVag5TLTIjR7oOJUY8kcADaZgWPyLeg==",
+      "license": "MIT"
+    },
+    "node_modules/pg-int8": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/pg-int8/-/pg-int8-1.0.1.tgz",
+      "integrity": "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/pg-pool": {
+      "version": "3.14.0",
+      "resolved": "https://registry.npmjs.org/pg-pool/-/pg-pool-3.14.0.tgz",
+      "integrity": "sha512-gKtPkFdQPU3DksooVLi9LsjZxrsBUZIpa+7aVx+LV5pNh0KzP4Zleud2po+ConrxbuXGBJ6Hfer6hdgpIBpBaw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "pg": ">=8.0"
+      }
+    },
+    "node_modules/pg-protocol": {
+      "version": "1.15.0",
+      "resolved": "https://registry.npmjs.org/pg-protocol/-/pg-protocol-1.15.0.tgz",
+      "integrity": "sha512-cq9sECI5s0+uPUXjbz8ioyPJni6RzsRib0US67i5IoTZKw8fNeYlVE7u8F4dG7vEJJtc5wdD1K189lCCUwqWTQ==",
+      "license": "MIT"
+    },
+    "node_modules/pg-types": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/pg-types/-/pg-types-2.2.0.tgz",
+      "integrity": "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==",
+      "license": "MIT",
+      "dependencies": {
+        "pg-int8": "1.0.1",
+        "postgres-array": "~2.0.0",
+        "postgres-bytea": "~1.0.0",
+        "postgres-date": "~1.0.4",
+        "postgres-interval": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/pgpass": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/pgpass/-/pgpass-1.0.5.tgz",
+      "integrity": "sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug==",
+      "license": "MIT",
+      "dependencies": {
+        "split2": "^4.1.0"
+      }
+    },
     "node_modules/picocolors": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.0.0.tgz",
@@ -13736,6 +13839,45 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/postgres-array": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/postgres-array/-/postgres-array-2.0.0.tgz",
+      "integrity": "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/postgres-bytea": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/postgres-bytea/-/postgres-bytea-1.0.1.tgz",
+      "integrity": "sha512-5+5HqXnsZPE65IJZSMkZtURARZelel2oXUEO8rH83VS/hxH5vv1uHquPg5wZs8yMAfdv971IU+kcPUczi7NVBQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/postgres-date": {
+      "version": "1.0.7",
+      "resolved": "https://registry.npmjs.org/postgres-date/-/postgres-date-1.0.7.tgz",
+      "integrity": "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/postgres-interval": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/postgres-interval/-/postgres-interval-1.2.0.tgz",
+      "integrity": "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==",
+      "license": "MIT",
+      "dependencies": {
+        "xtend": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/posthog-node": {
       "version": "5.21.2",
       "resolved": "https://registry.npmjs.org/posthog-node/-/posthog-node-5.21.2.tgz",
@@ -15482,6 +15624,15 @@
       "integrity": "sha512-XkD+zwiqXHikFZm4AX/7JSCXA98U5Db4AFd5XUg/+9UNtnH75+Z9KxtpYiJZx36mUDVOwH83pl7yvCer6ewM3w==",
       "dev": true
     },
+    "node_modules/split2": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz",
+      "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">= 10.x"
+      }
+    },
     "node_modules/sprintf-js": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz",
@@ -17275,7 +17426,6 @@
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz",
       "integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==",
-      "dev": true,
       "engines": {
         "node": ">=0.4"
       }

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.30.0",
+  "version": "0.32.0",
   "commands": {
     "config": {
       "id": "config",
@@ -627,6 +627,123 @@
       },
       "args": {}
     },
+    "import:data": {
+      "id": "import:data",
+      "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.",
+      "strict": true,
+      "pluginName": "@apso/cli",
+      "pluginAlias": "@apso/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "examples": [
+        "$ apso import data -s \"postgresql://...source...\" -t \"postgresql://...target...\"",
+        "$ apso import data --dry-run",
+        "$ apso import data --tables users,orders"
+      ],
+      "flags": {
+        "source": {
+          "name": "source",
+          "type": "option",
+          "char": "s",
+          "description": "Source connection string. Falls back to SUPABASE_DB_URL or DATABASE_URL, then prompts.",
+          "multiple": false
+        },
+        "target": {
+          "name": "target",
+          "type": "option",
+          "char": "t",
+          "description": "Target connection string. Falls back to TARGET_DATABASE_URL or APSO_DATABASE_URL, then prompts.",
+          "multiple": false
+        },
+        "schema": {
+          "name": "schema",
+          "type": "option",
+          "description": "Database schema",
+          "multiple": false,
+          "default": "public"
+        },
+        "tables": {
+          "name": "tables",
+          "type": "option",
+          "description": "Comma-separated list of source tables to copy (default: all)",
+          "multiple": false
+        },
+        "batch-size": {
+          "name": "batch-size",
+          "type": "option",
+          "description": "Rows per insert batch",
+          "multiple": false,
+          "default": 500
+        },
+        "dry-run": {
+          "name": "dry-run",
+          "type": "boolean",
+          "description": "Plan and report row counts without writing",
+          "allowNo": false
+        },
+        "yes": {
+          "name": "yes",
+          "type": "boolean",
+          "char": "y",
+          "description": "Skip the confirmation prompt",
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
+    "import:supabase": {
+      "id": "import:supabase",
+      "description": "Introspect an existing Supabase (Postgres) database and generate a local .apsorc schema. Read-only: it never writes to the source database.",
+      "strict": true,
+      "pluginName": "@apso/cli",
+      "pluginAlias": "@apso/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "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"
+      ],
+      "flags": {
+        "connection-string": {
+          "name": "connection-string",
+          "type": "option",
+          "char": "c",
+          "description": "Postgres connection string. Falls back to SUPABASE_DB_URL or DATABASE_URL, then prompts.",
+          "multiple": false
+        },
+        "schema": {
+          "name": "schema",
+          "type": "option",
+          "description": "Database schema to import",
+          "multiple": false,
+          "default": "public"
+        },
+        "out": {
+          "name": "out",
+          "type": "option",
+          "char": "o",
+          "description": "Path to write the .apsorc (default: existing .apsorc or ./.apsorc)",
+          "multiple": false
+        },
+        "dry-run": {
+          "name": "dry-run",
+          "type": "boolean",
+          "description": "Introspect and print a summary without writing any file",
+          "allowNo": false
+        },
+        "yes": {
+          "name": "yes",
+          "type": "boolean",
+          "char": "y",
+          "description": "Skip the overwrite confirmation prompt",
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
     "mcp:serve": {
       "id": "mcp:serve",
       "description": "Start an MCP server exposing Apso tools over stdio. Used by AI coding agents (Claude Code, Cursor, etc.) to design schemas, generate APIs, and deploy backends.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apso/cli",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "mcpName": "io.github.apsoai/apso",
   "description": "Apso CLI",
   "author": "Apso by Mavric - @mavric",
@@ -37,6 +37,7 @@
     "eta": "^2.0.0",
     "inquirer": "^8.2.7",
     "ora": "^5.4.1",
+    "pg": "^8.21.0",
     "pluralize": "^8.0.0",
     "posthog-node": "^5.21.2",
     "rc": "^1.2.8",
@@ -53,6 +54,7 @@
     "@types/inquirer": "^8.2.12",
     "@types/mocha": "^10",
     "@types/node": "^20.19.43",
+    "@types/pg": "^8.20.0",
     "@types/pluralize": "^0.0.29",
     "@types/rc": "^1.2.1",
     "@types/shelljs": "^0.8.15",
@@ -98,6 +100,9 @@
       },
       "mcp": {
         "description": "MCP server for AI coding agents"
+      },
+      "import": {
+        "description": "Import an existing database into a local .apsorc schema"
       }
     },
     "update": {