@apso/cli 0.29.1 → 0.31.0

package/dist/commands/generate.js

@@ -8,13 +8,14 @@ const lib_1 = require("../lib");
 const base_command_1 = tslib_1.__importDefault(require("../lib/base-command"));
 const perf_hooks_1 = require("perf_hooks");
 const file_system_1 = require("../lib/utils/file-system");
+const git_hooks_1 = require("../lib/utils/git-hooks");
 class Generate extends base_command_1.default {
     async run() {
         var _a, _b;
         const { flags } = await this.parse(Generate);
         const skipFormat = flags["skip-format"];
         const totalBuildStart = perf_hooks_1.performance.now();
-        const { rootFolder, entities, relationshipMap, apiType, auth, emitEvents, http, language: configLanguage } = (0, lib_1.parseApsorc)();
+        const { rootFolder, entities, relationshipMap, apiType, auth, emitEvents, http, coAuthor, language: configLanguage } = (0, lib_1.parseApsorc)();
         // Resolve language: flag > .apsorc > prompt
         let language;
         if (flags.language) {
@@ -235,6 +236,24 @@ class Generate extends base_command_1.default {
         }
         const totalBuildTime = perf_hooks_1.performance.now() - totalBuildStart;
         console.log(`[apso] Finished building all entities in ${totalBuildTime.toFixed(2)} ms`);
+        // Best-effort: install the commit co-author hook so commits that include
+        // Apso-generated files credit Apso as a co-author. Never fails the command.
+        try {
+            const result = (0, git_hooks_1.installCoAuthorHook)(process.cwd(), {
+                disabled: coAuthor === false,
+            });
+            if (result.installed) {
+                console.log("[apso] Commit co-author hook installed (.apso/hooks)");
+            }
+            else if (result.reason === "custom-hookspath") {
+                console.log("[apso] A custom git core.hooksPath is already configured (e.g. husky), so the Apso co-author hook was not installed.\n" +
+                    "[apso] To credit Apso on commits that include generated files, add this trailer to your existing prepare-commit-msg hook when the staged diff touches an `autogen/` path:\n" +
+                    '[apso]   git interpret-trailers --in-place --if-exists addIfDifferent --trailer "Co-authored-by: Apso <bot@apso.ai>" "$1"');
+            }
+        }
+        catch {
+            // Never let hook installation fail the generate command.
+        }
     }
 }
 Generate.description = "Generate code from .apsorc schema";

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/commands/init.d.ts

@@ -12,5 +12,11 @@ export default class Init extends BaseCommand {
     private cloneExisting;
     private createNew;
     private runOffline;
+    /**
+     * Best-effort install of the Apso commit co-author hook. Never throws, never
+     * fails the command. No `.apsorc` may exist yet at init time, so we only
+     * respect the `APSO_NO_COAUTHOR=1` env opt-out (handled inside the installer).
+     */
+    private installCoAuthorHook;
     private postSetup;
 }

package/dist/commands/init.js

@@ -13,6 +13,7 @@ const upgrade_1 = require("../lib/upgrade");
 const interactive_1 = require("../lib/utils/interactive");
 const config_2 = require("../lib/config");
 const template_1 = require("../lib/utils/template");
+const git_hooks_1 = require("../lib/utils/git-hooks");
 class Init extends base_command_1.default {
     async run() {
         const { flags } = await this.parse(Init);
@@ -119,6 +120,7 @@ class Init extends base_command_1.default {
             linkedAt: new Date().toISOString(),
         };
         config_1.projectLink.write(link, projectPath);
+        this.installCoAuthorHook(projectPath);
         this.log(`\nProject cloned to ${projectPath}`);
         this.log(`Linked to workspace "${workspace.name}" / service "${service.name}"`);
     }
@@ -286,7 +288,29 @@ class Init extends base_command_1.default {
         this.log(`Language: ${language}`);
         this.log('Run "apso login" to link this project to the Apso platform.');
     }
+    /**
+     * Best-effort install of the Apso commit co-author hook. Never throws, never
+     * fails the command. No `.apsorc` may exist yet at init time, so we only
+     * respect the `APSO_NO_COAUTHOR=1` env opt-out (handled inside the installer).
+     */
+    installCoAuthorHook(projectPath) {
+        try {
+            const result = (0, git_hooks_1.installCoAuthorHook)(projectPath);
+            if (result.installed) {
+                this.log("[apso] Commit co-author hook installed (.apso/hooks)");
+            }
+            else if (result.reason === "custom-hookspath") {
+                this.log("[apso] A custom git core.hooksPath is already configured (e.g. husky), so the Apso co-author hook was not installed.\n" +
+                    "[apso] To credit Apso on commits that include generated files, add this trailer to your existing prepare-commit-msg hook when the staged diff touches an `autogen/` path:\n" +
+                    '[apso]   git interpret-trailers --in-place --if-exists addIfDifferent --trailer "Co-authored-by: Apso <bot@apso.ai>" "$1"');
+            }
+        }
+        catch {
+            // Never let hook installation fail init.
+        }
+    }
     async postSetup(projectPath, language) {
+        this.installCoAuthorHook(projectPath);
         switch (language) {
             case "typescript": {
                 if (shelljs_1.default.which("npm")) {

package/dist/lib/apsorc-parser.d.ts

@@ -25,6 +25,12 @@ export type ApsorcType = {
      * gets a generated controller unless it opts back in with `http: true`.
      */
     http?: boolean;
+    /**
+     * Opt-out for the Apso commit co-author hook. When false, the CLI will not
+     * install the `prepare-commit-msg` hook that appends the Apso co-author
+     * trailer. Defaults to enabled.
+     */
+    coAuthor?: boolean;
 };
 type ParsedApsorcData = {
     entities: Entity[];
@@ -41,6 +47,8 @@ type ParsedApsorc = {
     emitEvents?: boolean;
     /** Top-level default for HTTP controller generation. */
     http?: boolean;
+    /** Opt-out for the Apso commit co-author hook (defaults to enabled). */
+    coAuthor?: boolean;
 };
 export declare const parseApsorcV1: (apsorc: ApsorcType) => ParsedApsorcData;
 export declare const parseApsorcV2: (apsorc: ApsorcType) => ParsedApsorcData;

package/dist/lib/apsorc-parser.js

@@ -38,6 +38,7 @@ const parseRc = () => {
     const language = apsoConfig.language;
     const emitEvents = apsoConfig.emitEvents;
     const http = apsoConfig.http;
+    const coAuthor = apsoConfig.coAuthor;
     return {
         rootFolder,
         apiType,
@@ -48,6 +49,7 @@ const parseRc = () => {
         language,
         emitEvents,
         http,
+        coAuthor,
     };
 };
 const parseApsorc = () => {
@@ -69,6 +71,7 @@ const parseApsorc = () => {
                     language: apsoConfig.language,
                     emitEvents: apsoConfig.emitEvents,
                     http: apsoConfig.http,
+                    coAuthor: apsoConfig.coAuthor,
                     ...(0, exports.parseApsorcV1)(apsoConfig),
                 };
                 if (debug) {
@@ -87,6 +90,7 @@ const parseApsorc = () => {
                     language: apsoConfig.language,
                     emitEvents: apsoConfig.emitEvents,
                     http: apsoConfig.http,
+                    coAuthor: apsoConfig.coAuthor,
                     ...(() => {
                         const relStart = perf_hooks_1.performance.now();
                         const parsed = (0, exports.parseApsorcV2)(apsoConfig);

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

@@ -0,0 +1,4 @@
+export * from "./types";
+export { pgToApsorc, findUnknownEmittedTypes } from "./pg-to-apsorc";
+export type { ApsorcImportOutput, ApsorcImportEntityOutput, ApsorcImportFieldOutput, ApsorcImportRelationshipOutput, } from "./pg-to-apsorc";
+export { PgIntrospector, redactConnectionString, buildSchema, SYSTEM_SCHEMAS } from "./introspect";

package/dist/lib/import/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_SCHEMAS = exports.buildSchema = exports.redactConnectionString = exports.PgIntrospector = exports.findUnknownEmittedTypes = exports.pgToApsorc = void 0;
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./types"), exports);
+var pg_to_apsorc_1 = require("./pg-to-apsorc");
+Object.defineProperty(exports, "pgToApsorc", { enumerable: true, get: function () { return pg_to_apsorc_1.pgToApsorc; } });
+Object.defineProperty(exports, "findUnknownEmittedTypes", { enumerable: true, get: function () { return pg_to_apsorc_1.findUnknownEmittedTypes; } });
+var introspect_1 = require("./introspect");
+Object.defineProperty(exports, "PgIntrospector", { enumerable: true, get: function () { return introspect_1.PgIntrospector; } });
+Object.defineProperty(exports, "redactConnectionString", { enumerable: true, get: function () { return introspect_1.redactConnectionString; } });
+Object.defineProperty(exports, "buildSchema", { enumerable: true, get: function () { return introspect_1.buildSchema; } });
+Object.defineProperty(exports, "SYSTEM_SCHEMAS", { enumerable: true, get: function () { return introspect_1.SYSTEM_SCHEMAS; } });

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

@@ -0,0 +1,42 @@
+/**
+ * Database Import — introspection layer
+ *
+ * Reads the schema of a live Postgres/Supabase database. This layer is
+ * deliberately thin and side-effect-light: it only issues read-only SELECTs
+ * against information_schema/pg_catalog and returns an `IntrospectedSchema`.
+ * All interpretation lives in the conversion layer (pg-to-apsorc.ts).
+ *
+ * `pg` is loaded lazily so importing this module (e.g. from the command) does
+ * not pull the driver until an actual connection is made.
+ */
+import { IntrospectedSchema, Introspector } from "./types";
+/** Supabase- and Postgres-managed schemas we never import from. */
+export declare const SYSTEM_SCHEMAS: Set<string>;
+/** Strip credentials from a connection string for safe display in errors. */
+export declare function redactConnectionString(input: string): string;
+/**
+ * Reads schema metadata from a Postgres database via a connection string.
+ * SSL is enabled by default (Supabase requires it).
+ */
+export declare class PgIntrospector implements Introspector {
+    private readonly connectionString;
+    constructor(connectionString: string);
+    private connect;
+    introspect(schema: string): Promise<IntrospectedSchema>;
+}
+interface RawRows {
+    tableRows: any[];
+    columnRows: any[];
+    pkRows: any[];
+    fkRows: any[];
+    uniqueRows: any[];
+    indexRows: any[];
+    enumRows: any[];
+    schemaRows: any[];
+}
+/**
+ * Assemble raw query rows into an IntrospectedSchema. Exported (separate from
+ * the DB connection) so it can be unit-tested with fixture rows.
+ */
+export declare function buildSchema(schema: string, raw: RawRows): IntrospectedSchema;
+export {};