@apso/cli 0.29.1 → 0.31.0

package/dist/lib/import/pg-to-apsorc.js

@@ -0,0 +1,399 @@
+"use strict";
+/**
+ * Database Import — conversion layer
+ *
+ * Turns an `IntrospectedSchema` (read from a live Postgres/Supabase database)
+ * into a `.apsorc`-shaped object. This is a pure function: same input always
+ * yields the same output and report, with no I/O — which keeps it exhaustively
+ * unit-testable.
+ *
+ * The reverse type map here is the inverse of `fieldTypeToColumnType`
+ * (src/lib/utils/field.ts). The FK-to-relationship logic mirrors how the
+ * platform derives FK column names in `getRelationshipIdField`
+ * (src/lib/utils/relationships/parse.ts) so imported relationships round-trip.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findUnknownEmittedTypes = exports.pgToApsorc = exports.deriveToName = exports.parseDefault = exports.pgTypeToApsorcType = void 0;
+const casing_1 = require("../utils/casing");
+const field_1 = require("../utils/field");
+const relationships_1 = require("../utils/relationships");
+/** Maps a Postgres udt_name to the closest `.apsorc` field type. */
+const udtToApsorcType = {
+    int2: "smallint",
+    int4: "integer",
+    int8: "bigint",
+    float4: "real",
+    float8: "double",
+    numeric: "numeric",
+    money: "money",
+    bool: "boolean",
+    varchar: "varchar",
+    bpchar: "char",
+    text: "text",
+    uuid: "uuid",
+    json: "json",
+    jsonb: "jsonb",
+    date: "date",
+    timestamp: "timestamp",
+    timestamptz: "timestamptz",
+    time: "time",
+    timetz: "timetz",
+    bytea: "bytea",
+    xml: "xml",
+    inet: "inet",
+    cidr: "inet",
+    interval: "interval",
+    tsvector: "tsvector",
+    int4range: "int4range",
+    // PostGIS — pass-through (these are also keys in fieldTypeToColumnType)
+    point: "point",
+    geometry: "geometry",
+    geography: "geography",
+};
+const TIMESTAMP_UDTS = new Set(["timestamp", "timestamptz"]);
+const AUTO_TIMESTAMP_DEFAULTS = new Set([
+    "now()",
+    "current_timestamp",
+    "transaction_timestamp()",
+    "clock_timestamp()",
+]);
+/**
+ * Resolve a column's `.apsorc` field type from its Postgres type. Postgres
+ * arrays (udt_name starting with "_") collapse to `array`; user enums become
+ * `enum`; unknown types fall back to `text`.
+ */
+function pgTypeToApsorcType(col) {
+    if (col.isEnum) {
+        return { type: "enum" };
+    }
+    if (col.dataType === "ARRAY" || col.udtName.startsWith("_")) {
+        return { type: "array", lossy: "array" };
+    }
+    const mapped = udtToApsorcType[col.udtName];
+    if (mapped) {
+        return { type: mapped };
+    }
+    return { type: "text", lossy: "defaulted" };
+}
+exports.pgTypeToApsorcType = pgTypeToApsorcType;
+/**
+ * Translate a raw Postgres default expression into an `.apsorc` default value.
+ * Returns `{ drop: true }` when the default cannot be represented (function
+ * calls, sequence/uuid generators). Auto-timestamp and sequence defaults are
+ * dropped silently by callers that handle them structurally.
+ */
+function parseDefault(raw, apsorcType) {
+    if (raw === null)
+        return {};
+    const expr = raw.trim();
+    const lower = expr.toLowerCase();
+    // Sequence / generator / function defaults can't be a literal .apsorc value.
+    if (lower.startsWith("nextval(") ||
+        lower.startsWith("gen_random_uuid(") ||
+        lower.startsWith("uuid_generate_v4(") ||
+        AUTO_TIMESTAMP_DEFAULTS.has(lower)) {
+        return { drop: true };
+    }
+    // Strip a trailing ::type cast, e.g. 'active'::text or 0::integer.
+    const withoutCast = expr.replace(/::[\s\w".[\]]+$/, "").trim();
+    // Quoted string literal.
+    if (withoutCast.startsWith("'") && withoutCast.endsWith("'")) {
+        const inner = withoutCast.slice(1, -1).replace(/''/g, "'");
+        return { value: inner };
+    }
+    if (lower === "true" || lower === "false") {
+        return { value: lower === "true" };
+    }
+    if (/^-?\d+(\.\d+)?$/.test(withoutCast)) {
+        if (apsorcType === "numeric" || apsorcType === "decimal") {
+            return { value: withoutCast };
+        }
+        return { value: Number(withoutCast) };
+    }
+    // Anything else (function calls, complex expressions) — drop with a warning.
+    return { drop: true };
+}
+exports.parseDefault = parseDefault;
+/**
+ * Derive the relationship `to_name` so the platform regenerates a FK column
+ * matching the source column. Returns `undefined` when the default naming
+ * (`${camelCase(target)}Id`) already produces the source column. Sets
+ * `unmapped: true` when no name round-trips to the source column.
+ */
+function deriveToName(sourceColumn, targetTable) {
+    // The platform always generates camelCase FK columns, while Postgres/Supabase
+    // columns are typically snake_case. Compare on the camelCased form so a
+    // snake_case source that is semantically identical isn't flagged as a mismatch.
+    const source = (0, casing_1.camelCase)(sourceColumn);
+    const defaultColumn = (0, relationships_1.getRelationshipIdField)({
+        name: targetTable,
+        type: "ManyToOne",
+    });
+    if (defaultColumn === source) {
+        return {};
+    }
+    // Strip a trailing Id / _id and use the remainder as the reference name.
+    const base = sourceColumn.replace(/(_id|Id)$/, "");
+    if (base && base !== sourceColumn) {
+        const candidate = (0, casing_1.camelCase)(base);
+        const roundTrip = (0, relationships_1.getRelationshipIdField)({
+            name: targetTable,
+            type: "ManyToOne",
+            referenceName: candidate,
+        });
+        if (roundTrip === source) {
+            return { toName: candidate };
+        }
+    }
+    // Best-effort: emit a reference name but flag that the generated FK column
+    // may not match the source column exactly.
+    return { toName: (0, casing_1.camelCase)(base || sourceColumn), unmapped: true };
+}
+exports.deriveToName = deriveToName;
+function emptyReport(schema) {
+    return {
+        tablesImported: [],
+        relationships: 0,
+        viewsSkipped: schema.skipped.views,
+        systemSchemasSkipped: schema.skipped.systemSchemas,
+        warnings: {
+            arraysLossy: [],
+            compositePks: [],
+            compositeFks: [],
+            nonStandardPks: [],
+            noPrimaryKey: [],
+            typesDefaulted: [],
+            fkColumnNameUnmapped: [],
+            defaultsDropped: [],
+            joinTablesDetected: [],
+        },
+    };
+}
+function isJoinTable(table) {
+    const singleColumnFkNames = table.foreignKeys
+        .filter((fk) => fk.columns.length === 1)
+        .map((fk) => fk.columns[0]);
+    return (table.foreignKeys.length === 2 &&
+        singleColumnFkNames.length === 2 &&
+        table.primaryKey.length === 2 &&
+        table.primaryKey.every((c) => singleColumnFkNames.includes(c)));
+}
+/**
+ * Convert an introspected Postgres schema into a `.apsorc`-shaped object plus a
+ * report of everything that could not be represented losslessly.
+ */
+function pgToApsorc(schema) {
+    const report = emptyReport(schema);
+    const enumLabels = new Map(schema.enums.map((e) => [e.name, e.labels]));
+    const entities = [];
+    const relationships = [];
+    for (const table of schema.tables) {
+        report.tablesImported.push(table.name);
+        if (isJoinTable(table)) {
+            report.warnings.joinTablesDetected.push(table.name);
+        }
+        const entity = { name: table.name };
+        // Columns covered by a single-column FK are materialized by the
+        // relationship, so they must not also be emitted as scalar fields.
+        const fkColumns = new Map();
+        for (const fk of table.foreignKeys) {
+            if (fk.columns.length === 1) {
+                fkColumns.set(fk.columns[0], fk);
+            }
+            else {
+                report.warnings.compositeFks.push(table.name);
+            }
+        }
+        // --- Primary key handling ---
+        const pk = table.primaryKey;
+        const pkSet = new Set(pk);
+        let pkAsField = false;
+        if (pk.length === 1) {
+            const pkCol = table.columns.find((c) => c.name === pk[0]);
+            if (pk[0] === "id" && pkCol) {
+                const t = pgTypeToApsorcType(pkCol).type;
+                if (t === "uuid")
+                    entity.primaryKeyType = "uuid";
+                else if (t === "text" || t === "varchar")
+                    entity.primaryKeyType = "text";
+                // integer/bigint/smallint id => default serial, omit primaryKeyType.
+            }
+            else {
+                // Single, non-"id" PK: emit it as a primary field.
+                pkAsField = true;
+                report.warnings.nonStandardPks.push(table.name);
+            }
+        }
+        else if (pk.length > 1) {
+            pkAsField = true;
+            report.warnings.compositePks.push(table.name);
+        }
+        else {
+            report.warnings.noPrimaryKey.push(table.name);
+        }
+        // --- created_at / updated_at detection ---
+        const autoTimestamps = new Set();
+        for (const name of ["created_at", "updated_at"]) {
+            const col = table.columns.find((c) => c.name === name);
+            if (col && TIMESTAMP_UDTS.has(col.udtName)) {
+                entity[name] = true;
+                autoTimestamps.add(name);
+            }
+        }
+        // --- Fields ---
+        const uniqueSingle = new Set();
+        const uniqueComposite = [];
+        for (const uc of table.uniqueConstraints) {
+            if (uc.columns.length === 1)
+                uniqueSingle.add(uc.columns[0]);
+            else
+                uniqueComposite.push({ fields: uc.columns, name: uc.name });
+        }
+        const indexSingle = new Set();
+        const indexComposite = [];
+        for (const idx of table.indexes) {
+            const cols = idx.columns;
+            // Skip indexes that merely back the PK or a unique constraint.
+            const backsPk = cols.length === pk.length && cols.every((c) => pkSet.has(c));
+            const backsUnique = table.uniqueConstraints.some((uc) => uc.columns.length === cols.length &&
+                uc.columns.every((c) => cols.includes(c)));
+            if (backsPk || backsUnique)
+                continue;
+            if (cols.length === 1)
+                indexSingle.add(cols[0]);
+            else
+                indexComposite.push({ fields: cols, unique: idx.unique });
+        }
+        const fields = [];
+        const sortedColumns = [...table.columns].sort((a, b) => a.ordinal - b.ordinal);
+        for (const col of sortedColumns) {
+            // Skip columns represented elsewhere.
+            if (fkColumns.has(col.name))
+                continue;
+            if (autoTimestamps.has(col.name))
+                continue;
+            if (pk.length === 1 && col.name === pk[0] && !pkAsField)
+                continue;
+            const resolved = pgTypeToApsorcType(col);
+            if (resolved.lossy === "array") {
+                report.warnings.arraysLossy.push(`${table.name}.${col.name}`);
+            }
+            else if (resolved.lossy === "defaulted") {
+                report.warnings.typesDefaulted.push({
+                    column: `${table.name}.${col.name}`,
+                    udt: col.udtName,
+                });
+            }
+            const field = {
+                name: col.name,
+                type: resolved.type,
+            };
+            if (col.nullable)
+                field.nullable = true;
+            if (uniqueSingle.has(col.name))
+                field.unique = true;
+            if (indexSingle.has(col.name))
+                field.index = true;
+            if (pkSet.has(col.name) && pkAsField)
+                field.primary = true;
+            if ((resolved.type === "varchar" || resolved.type === "char") && col.charMaxLength)
+                field.length = col.charMaxLength;
+            if (resolved.type === "numeric" || resolved.type === "decimal") {
+                if (col.numericPrecision)
+                    field.precision = col.numericPrecision;
+                if (col.numericScale !== null)
+                    field.scale = col.numericScale;
+            }
+            if (resolved.type === "enum") {
+                const labels = col.enumTypeName
+                    ? enumLabels.get(col.enumTypeName)
+                    : undefined;
+                if (labels)
+                    field.values = labels;
+            }
+            // Defaults (skip for PK columns — those are implicit/sequence-driven).
+            if (!(pkSet.has(col.name) && !pkAsField)) {
+                const parsed = parseDefault(col.default, resolved.type);
+                if (parsed.drop && col.default !== null) {
+                    report.warnings.defaultsDropped.push(`${table.name}.${col.name}`);
+                }
+                else if ("value" in parsed) {
+                    if (resolved.type === "enum") {
+                        // Only keep an enum default that is one of the allowed labels.
+                        if (field.values && field.values.includes(String(parsed.value))) {
+                            field.default = parsed.value;
+                        }
+                        else {
+                            report.warnings.defaultsDropped.push(`${table.name}.${col.name}`);
+                        }
+                    }
+                    else {
+                        field.default = parsed.value;
+                    }
+                }
+            }
+            fields.push(field);
+        }
+        if (fields.length > 0)
+            entity.fields = fields;
+        if (uniqueComposite.length > 0)
+            entity.uniques = uniqueComposite;
+        if (indexComposite.length > 0)
+            entity.indexes = indexComposite;
+        entities.push(entity);
+        // --- Foreign keys -> ManyToOne relationships ---
+        for (const fk of table.foreignKeys) {
+            if (fk.columns.length !== 1)
+                continue; // composite FK handled above
+            const sourceColumn = fk.columns[0];
+            const col = table.columns.find((c) => c.name === sourceColumn);
+            const rel = {
+                from: table.name,
+                to: fk.referencedTable,
+                type: "ManyToOne",
+            };
+            const { toName, unmapped } = deriveToName(sourceColumn, fk.referencedTable);
+            if (toName)
+                rel.to_name = toName;
+            if (unmapped) {
+                report.warnings.fkColumnNameUnmapped.push(`${table.name}.${sourceColumn}`);
+            }
+            if (col === null || col === void 0 ? void 0 : col.nullable)
+                rel.nullable = true;
+            if (fk.onDelete === "CASCADE")
+                rel.cascadeDelete = true;
+            relationships.push(rel);
+        }
+    }
+    report.relationships = relationships.length;
+    return {
+        apsorc: {
+            version: 2,
+            rootFolder: "src",
+            apiType: "rest",
+            entities,
+            relationships,
+        },
+        report,
+    };
+}
+exports.pgToApsorc = pgToApsorc;
+/**
+ * Invariant guard: every emitted field type must be a recognized `.apsorc`
+ * column type, so code generation never silently falls back to varchar.
+ * Returns the list of any offending types (empty when valid).
+ */
+function findUnknownEmittedTypes(output) {
+    var _a;
+    const unknown = [];
+    for (const entity of output.entities) {
+        for (const field of (_a = entity.fields) !== null && _a !== void 0 ? _a : []) {
+            if (field.type === "enum")
+                continue; // enum dispatched separately
+            if (!(field.type in field_1.fieldTypeToColumnType))
+                unknown.push(field.type);
+        }
+    }
+    return unknown;
+}
+exports.findUnknownEmittedTypes = findUnknownEmittedTypes;

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/dist/lib/utils/git-hooks.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The Apso co-author git trailer. Appended to commits that include
+ * Apso-generated work so Apso is credited as a co-author.
+ */
+export declare const APSO_COAUTHOR_TRAILER = "Co-authored-by: Apso <bot@apso.ai>";
+/**
+ * Relative path (from the repo top-level) where the managed hook is installed.
+ * Modern git resolves a relative `core.hooksPath` from the repository root.
+ */
+export declare const APSO_HOOKS_DIR = ".apso/hooks";
+/**
+ * Builds the `prepare-commit-msg` bash script that appends the Apso co-author
+ * trailer to commits that touch Apso-generated paths.
+ *
+ * Pure function (no side effects) so it can be unit-tested directly.
+ *
+ * Behaviour of the generated script:
+ * - Skips merge/squash commits (`$2` is `merge` or `squash`).
+ * - Honors the `APSO_NO_COAUTHOR=1` opt-out.
+ * - Only acts when the staged changes include an Apso-generated path
+ *   (a path segment named `autogen/`).
+ * - Adds the trailer idempotently via `git interpret-trailers`, which handles
+ *   trailer-block formatting + dedupe and coexists with other `Co-authored-by`
+ *   trailers (e.g. Claude).
+ */
+export declare function buildCoAuthorHookScript(): string;
+export interface InstallCoAuthorHookOptions {
+    /** When true, skip installation (e.g. `.apsorc` set `coAuthor: false`). */
+    disabled?: boolean;
+}
+export interface InstallCoAuthorHookResult {
+    installed: boolean;
+    reason?: "disabled" | "not-a-git-repo" | "custom-hookspath" | "error";
+}
+/**
+ * Installs the Apso co-author `prepare-commit-msg` hook into a project.
+ *
+ * Best-effort: never throws. Callers can log the result.
+ *
+ * - Respects the `disabled` option and the `APSO_NO_COAUTHOR=1` env opt-out.
+ * - No-ops (returns `not-a-git-repo`) outside a git work tree.
+ * - Writes `<projectRoot>/.apso/hooks/prepare-commit-msg` (mode 0755).
+ * - Sets the repo-local `core.hooksPath` to `.apso/hooks` when unset; leaves it
+ *   alone (and reports success) when it's already `.apso/hooks`; refuses to
+ *   clobber a custom `core.hooksPath` (husky etc.) and reports
+ *   `custom-hookspath` so the caller can guide the user.
+ */
+export declare function installCoAuthorHook(projectRoot: string, opts?: InstallCoAuthorHookOptions): InstallCoAuthorHookResult;