@akshythere/pg-sync 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pg-sync contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,152 @@
-# Temporary Holding Version
+# pg-sync
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+> PostgreSQL schema introspection that turns your database into useful code and documentation.
+
+<p align="left">
+  <a href="https://www.npmjs.com/package/pg-sync"><img src="https://img.shields.io/npm/v/pg-sync?color=cb3837&logo=npm" alt="npm version"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0%2B-3178C6?logo=typescript&logoColor=white" alt="TypeScript 5.0+"></a>
+  <a href="https://www.postgresql.org/"><img src="https://img.shields.io/badge/PostgreSQL-12%2B-336791?logo=postgresql&logoColor=white" alt="PostgreSQL 12+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT license"></a>
+</p>
+
+`pg-sync` connects directly to PostgreSQL, reads its catalog metadata, and generates artifacts from a normalized schema model. Use it as `pg-sync` or the shorter `pgs` command.
+
+## Why pg-sync?
+
+Keep generated types, framework schemas, and architecture documentation aligned with the database that actually runs your application.
+
+- No ORM runtime dependency
+- Direct queries against `pg_catalog` and `information_schema`
+- Foreign keys and partitioned tables included in the schema model
+- Prettier-formatted TypeScript output
+- Interactive setup with a connection check
+
+## Outputs
+
+| Target       | Output                     | Best for                                            |
+| ------------ | -------------------------- | --------------------------------------------------- |
+| `typescript` | `schema.ts`                | Typed application code with zero runtime dependency |
+| `frappe`     | One JSON DocType per table | Frappe custom DocTypes and field configuration      |
+| `erd`        | `ERD.md` with Mermaid      | Schema reviews, technical docs, and onboarding      |
+
+The generators understand nullable columns, defaults, arrays, primary keys, foreign keys, and common PostgreSQL types. Frappe output also maps relationships to `Link` fields and common numeric, date, and boolean types to suitable field types.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[(PostgreSQL)] --> B[Catalog introspection]
+    B --> C[Normalized schema IR]
+    C --> D[TypeScript]
+    C --> E[Frappe DocTypes]
+    C --> F[Mermaid ERD]
+    D --> G[(Local files)]
+    E --> G
+    F --> G
+```
+
+## Install
+
+### Use globally
+
+```bash
+npm install -g pg-sync
+pgs --help
+```
+
+### Build from source
+
+```bash
+git clone https://github.com/akshitbhardwajhere/pg-sync.git
+cd pg-sync
+npm install
+npm run build
+npm link
+```
+
+## Quick start
+
+### 1. Create a configuration
+
+The wizard asks for your connection details, verifies the database connection, and writes `pg-sync.config.json`.
+
+```bash
+pgs init
+```
+
+Choose TypeScript interfaces, Frappe DocTypes, or Mermaid ERD documentation. The wizard defaults to `./src/types`, `./doctypes`, or `./docs` respectively.
+
+Example configuration:
+
+```json
+{
+  "connectionString": "postgresql://postgres:postgres@localhost:5432/mydb",
+  "schema": "public",
+  "target": "typescript",
+  "outputDir": "./src/types"
+}
+```
+
+### 2. Generate files
+
+```bash
+pgs generate
+```
+
+Command-line options override values from the config file:
+
+```bash
+# TypeScript definitions
+pgs generate -u "postgresql://user:pass@localhost:5432/mydb" \
+  -t typescript -o ./src/types
+
+# Frappe DocTypes
+pgs generate -t frappe -o ./doctypes
+
+# Mermaid ERD documentation
+pgs generate -t erd -o ./docs
+```
+
+`DATABASE_URL` is also supported when no connection string is supplied through a flag or configuration file.
+
+## Configuration
+
+Create `pg-sync.config.json` in the project root, or pass a custom file with `-c`.
+
+| Property           | Type     | Default          | Description                      |
+| ------------------ | -------- | ---------------- | -------------------------------- |
+| `connectionString` | `string` | Required         | PostgreSQL connection URI        |
+| `schema`           | `string` | `public`         | PostgreSQL schema to inspect     |
+| `target`           | `string` | `typescript`     | `typescript`, `frappe`, or `erd` |
+| `outputDir`        | `string` | Target-dependent | Directory for generated files    |
+
+Useful flags:
+
+```text
+-u, --url <url>      PostgreSQL connection string
+-s, --schema <name>  Database schema to inspect
+-o, --output <dir>   Output directory
+-t, --target <type>  typescript | frappe | erd
+-c, --config <file>  Custom configuration path
+```
+
+## Development
+
+```bash
+npm run build          # Compile TypeScript
+npm test               # Run the test suite
+npm run test:coverage  # Generate coverage metrics
+npm run test:watch    # Watch tests during development
+```
+
+Integration tests expect a reachable PostgreSQL instance. The CI workflow runs them against a PostgreSQL service container.
+
+## Requirements
+
+- Node.js 18+
+- PostgreSQL 12+
+- A database user with permission to read the target schema metadata
+
+## License
+
+Distributed under the [MIT License](https://opensource.org/licenses/MIT).

package/dist/commands/generate.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import ora from "ora";
+import pc from "picocolors";
+import { createDatabasePool } from "../engine/db.js";
+import { introspectDatabase } from "../engine/introspector.js";
+import { generateTypeScriptDefinitions } from "../generators/typescript.js";
+import { generateFrappeDocTypes } from "../generators/frappe.js";
+import { loadConfig } from "../utils/config.js";
+import { generateMermaidERD } from "../generators/erd.js";
+export async function runGenerate(options) {
+    const fileConfig = await loadConfig(options.configFile);
+    const connectionString = options.connectionString ||
+        process.env.DATABASE_URL ||
+        fileConfig?.connectionString;
+    if (!connectionString) {
+        console.error(pc.red("Error: No connection string provided."));
+        console.log(`Run ${pc.cyan("pg-sync init")} or supply ${pc.yellow("-u <connectionString>")}`);
+        process.exit(1);
+    }
+    const schema = options.schema || fileConfig?.schema || "public";
+    const target = options.target || fileConfig?.target || "typescript";
+    const rawOutputDir = options.outputDir ||
+        fileConfig?.outputDir ||
+        (target === "typescript" ? "./generated" : "./doctypes");
+    const outputDir = path.resolve(process.cwd(), rawOutputDir);
+    const spinner = ora("Connecting to PostgreSQL database...").start();
+    const pool = createDatabasePool(connectionString);
+    try {
+        spinner.text = "Introspecting database catalog and schema tables...";
+        const schemaIR = await introspectDatabase(pool, schema);
+        spinner.succeed(pc.green(`Introspection complete! Found ${schemaIR.tables.length} tables.`));
+        for (const table of schemaIR.tables) {
+            const partitionInfo = table.isPartitioned
+                ? pc.magenta(` [Partitioned: ${table.partitionStrategy}]`)
+                : "";
+            console.log(` • ${pc.bold(table.tableName)}${partitionInfo} (${table.columns.length} columns)`);
+        }
+        await fs.mkdir(outputDir, { recursive: true });
+        if (target === "typescript") {
+            const genSpinner = ora("Generating TypeScript definitions...").start();
+            const formattedCode = await generateTypeScriptDefinitions(schemaIR);
+            const outputPath = path.join(outputDir, "schema.ts");
+            await fs.writeFile(outputPath, formattedCode, "utf-8");
+            genSpinner.succeed(pc.green(`TypeScript types saved to: ${pc.bold(outputPath)}`));
+        }
+        else if (target === "frappe") {
+            const genSpinner = ora("Generating Frappe DocType schemas...").start();
+            const docTypes = await generateFrappeDocTypes(schemaIR);
+            for (const dt of docTypes) {
+                const docTypeDir = path.join(outputDir, dt.docTypeName.toLowerCase());
+                await fs.mkdir(docTypeDir, { recursive: true });
+                const filePath = path.join(docTypeDir, `${dt.docTypeName.toLowerCase()}.json`);
+                await fs.writeFile(filePath, dt.content, "utf-8");
+            }
+            genSpinner.succeed(pc.green(`Generated ${docTypes.length} Frappe DocType schemas in: ${pc.bold(outputDir)}`));
+        }
+        else if (target === "erd") {
+            const genSpinner = ora("Generating Mermaid ERD documentation...").start();
+            const erdMarkdown = generateMermaidERD(schemaIR);
+            const outputPath = path.join(outputDir, "ERD.md");
+            await fs.writeFile(outputPath, erdMarkdown, "utf-8");
+            genSpinner.succeed(pc.green(`ERD documentation saved to: ${pc.bold(outputPath)}`));
+        }
+    }
+    catch (err) {
+        spinner.fail(pc.red("Generation failed."));
+        console.error(pc.red(err.message));
+        process.exit(1);
+    }
+    finally {
+        await pool.end();
+    }
+}

package/dist/commands/init.js

@@ -0,0 +1,62 @@
+import { input, select } from "@inquirer/prompts";
+import ora from "ora";
+import pc from "picocolors";
+import { createDatabasePool } from "../engine/db.js";
+import { saveConfig } from "../utils/config.js";
+export async function runInit() {
+    console.log(pc.bold(pc.cyan("\n⚙️  pg-sync Initialization Wizard\n")));
+    const connectionString = await input({
+        message: "Enter PostgreSQL connection string:",
+        default: "postgresql://postgres:admin@localhost:5432/postgres",
+        validate: (val) => val.startsWith("postgresql://") || val.startsWith("postgres://")
+            ? true
+            : "Invalid PostgreSQL URI format",
+    });
+    const schema = await input({
+        message: "Schema to introspect:",
+        default: "public",
+    });
+    const target = await select({
+        message: "Select output generator target:",
+        choices: [
+            {
+                name: "TypeScript Interfaces (Universal / Next.js / Node)",
+                value: "typescript",
+            },
+            { name: "Frappe Custom DocType JSONs", value: "frappe" },
+            { name: "Mermaid ERD Documentation", value: "erd" },
+        ],
+    });
+    const outputDir = await input({
+        message: "Target output directory:",
+        default: target === "typescript"
+            ? "./src/types"
+            : target === "frappe"
+                ? "./doctypes"
+                : "./docs",
+    });
+    // Verify connection before saving
+    const spinner = ora("Testing database connection...").start();
+    const pool = createDatabasePool(connectionString);
+    try {
+        const client = await pool.connect();
+        client.release();
+        spinner.succeed(pc.green("Database connection verified successfully!"));
+    }
+    catch (err) {
+        spinner.fail(pc.red(`Failed to connect: ${err.message}`));
+        console.log(pc.yellow("Writing config anyway, but double-check your credentials.\n"));
+    }
+    finally {
+        await pool.end();
+    }
+    const config = {
+        connectionString,
+        schema,
+        outputDir,
+        target, // Ensure this says target, not format
+    };
+    const savedPath = await saveConfig(config);
+    console.log(pc.green(`\n✔ Configuration written to ${pc.bold(savedPath)}`));
+    console.log(`You can now run ${pc.cyan("pg-sync generate")} or ${pc.cyan("pgs generate")} to create your files.\n`);
+}

package/dist/engine/db.js

@@ -0,0 +1,12 @@
+import pg from "pg";
+const { Pool } = pg;
+export function createDatabasePool(connectionString) {
+    return new Pool({
+        connectionString,
+        ssl: connectionString.includes("localhost") ||
+            connectionString.includes("127.0.0.1")
+            ? false
+            : { rejectUnauthorized: false },
+        connectionTimeoutMillis: 5000,
+    });
+}

package/dist/engine/introspector.js

@@ -0,0 +1,111 @@
+export async function introspectDatabase(pool, targetSchema = "public") {
+    const client = await pool.connect();
+    try {
+        // 1. Fetch tables and partition info
+        const tablesQuery = `
+      SELECT 
+        c.relname AS table_name,
+        c.relkind,
+        pt.partstrat AS partition_strategy
+      FROM pg_catalog.pg_class c
+      JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+      LEFT JOIN pg_catalog.pg_partitioned_table pt ON pt.partrelid = c.oid
+      WHERE n.nspname = $1
+        AND c.relkind IN ('r', 'p')
+      ORDER BY c.relname;
+    `;
+        const { rows: tableRows } = await client.query(tablesQuery, [targetSchema]);
+        // 2. Fetch columns
+        const columnsQuery = `
+      SELECT 
+        table_name,
+        column_name,
+        data_type,
+        udt_name,
+        is_nullable,
+        column_default
+      FROM information_schema.columns
+      WHERE table_schema = $1
+      ORDER BY table_name, ordinal_position;
+    `;
+        const { rows: columnRows } = await client.query(columnsQuery, [
+            targetSchema,
+        ]);
+        // 3. Fetch primary keys
+        const pkQuery = `
+      SELECT 
+        kcu.table_name,
+        kcu.column_name
+      FROM information_schema.table_constraints tc
+      JOIN information_schema.key_column_usage kcu 
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+      WHERE tc.constraint_type = 'PRIMARY KEY' 
+        AND tc.table_schema = $1;
+    `;
+        const { rows: pkRows } = await client.query(pkQuery, [targetSchema]);
+        // 4. Fetch foreign keys
+        const fkQuery = `
+      SELECT
+        kcu.table_name,
+        kcu.column_name,
+        ccu.table_name AS foreign_table_name,
+        ccu.column_name AS foreign_column_name
+      FROM information_schema.table_constraints tc
+      JOIN information_schema.key_column_usage kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+      JOIN information_schema.constraint_column_usage ccu
+        ON ccu.constraint_name = tc.constraint_name
+        AND ccu.table_schema = tc.table_schema
+      WHERE tc.constraint_type = 'FOREIGN KEY'
+        AND tc.table_schema = $1;
+    `;
+        const { rows: fkRows } = await client.query(fkQuery, [targetSchema]);
+        // Construct the Schema Intermediate Representation
+        const tables = tableRows.map((t) => {
+            const currentTableColumns = columnRows.filter((c) => c.table_name === t.table_name);
+            const currentTablePKs = pkRows
+                .filter((pk) => pk.table_name === t.table_name)
+                .map((pk) => pk.column_name);
+            const currentTableFKs = fkRows
+                .filter((fk) => fk.table_name === t.table_name)
+                .map((fk) => ({
+                columnName: fk.column_name,
+                foreignTableName: fk.foreign_table_name,
+                foreignColumnName: fk.foreign_column_name,
+            }));
+            const columns = currentTableColumns.map((col) => ({
+                name: col.column_name,
+                dbType: col.data_type,
+                udtName: col.udt_name,
+                isNullable: col.is_nullable === "YES",
+                isPrimaryKey: currentTablePKs.includes(col.column_name),
+                defaultValue: col.column_default,
+            }));
+            const partitionStrategyMap = {
+                r: "RANGE",
+                l: "LIST",
+                h: "HASH",
+            };
+            return {
+                tableName: t.table_name,
+                schema: targetSchema,
+                isPartitioned: t.relkind === "p",
+                partitionStrategy: t.partition_strategy
+                    ? partitionStrategyMap[t.partition_strategy]
+                    : undefined,
+                columns,
+                primaryKeys: currentTablePKs,
+                foreignKeys: currentTableFKs,
+            };
+        });
+        return {
+            extractedAt: new Date().toISOString(),
+            tables,
+        };
+    }
+    finally {
+        client.release();
+    }
+}

package/dist/engine/mapper.js

@@ -0,0 +1,55 @@
+export function mapPgTypeToTs(dbType, udtName) {
+    const normalizedType = dbType.toLowerCase();
+    const normalizedUdt = udtName.toLowerCase();
+    // Check for PostgreSQL array types (udt_name typically starts with an underscore, e.g., _text)
+    const isArray = normalizedType === "array" || normalizedUdt.startsWith("_");
+    const baseUdt = isArray && normalizedUdt.startsWith("_")
+        ? normalizedUdt.slice(1)
+        : normalizedUdt;
+    let tsType;
+    switch (baseUdt) {
+        case "int2":
+        case "int4":
+        case "int8":
+        case "float4":
+        case "float8":
+        case "numeric":
+        case "money":
+            tsType = "number";
+            break;
+        case "bool":
+            tsType = "boolean";
+            break;
+        case "varchar":
+        case "char":
+        case "text":
+        case "uuid":
+        case "citext":
+            tsType = "string";
+            break;
+        case "timestamp":
+        case "timestamptz":
+        case "date":
+        case "time":
+        case "timetz":
+            tsType = "Date | string";
+            break;
+        case "json":
+        case "jsonb":
+            tsType = "Record<string, unknown>";
+            break;
+        case "bytea":
+            tsType = "Buffer";
+            break;
+        default:
+            tsType = "unknown";
+            break;
+    }
+    return isArray ? `${tsType}[]` : tsType;
+}
+export function toPascalCase(str) {
+    return str
+        .split(/[-_]/)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join("");
+}

package/dist/engine/types.js

@@ -0,0 +1 @@
+export {};

package/dist/generators/erd.js

@@ -0,0 +1,35 @@
+export function generateMermaidERD(schemaIR) {
+    const lines = [];
+    lines.push("# Database Entity-Relationship Diagram");
+    lines.push(`> Extracted at: ${schemaIR.extractedAt}\n`);
+    lines.push("```mermaid");
+    lines.push("erDiagram");
+    // 1. Define entities and their attributes
+    for (const table of schemaIR.tables) {
+        // Skip partitioned child tables to keep the diagram clean
+        if (table.tableName.includes("_y20") || table.tableName.includes("_p20")) {
+            continue;
+        }
+        const tableNameUpper = table.tableName.toUpperCase();
+        lines.push(`    ${tableNameUpper} {`);
+        for (const col of table.columns) {
+            const isFK = table.foreignKeys.some((fk) => fk.columnName === col.name);
+            const keyAnnotation = col.isPrimaryKey ? "PK" : isFK ? "FK" : "";
+            // Mermaid requires sanitized type identifiers (no spaces or special chars)
+            const cleanType = col.udtName.replace(/[^a-zA-Z0-9]/g, "");
+            lines.push(`        ${cleanType} ${col.name} ${keyAnnotation}`.trimEnd());
+        }
+        lines.push("    }");
+    }
+    lines.push("");
+    // 2. Define relationships from foreign keys
+    for (const table of schemaIR.tables) {
+        for (const fk of table.foreignKeys) {
+            const source = fk.foreignTableName.toUpperCase();
+            const target = table.tableName.toUpperCase();
+            lines.push(`    ${source} ||--o{ ${target} : "${fk.columnName}"`);
+        }
+    }
+    lines.push("```\n");
+    return lines.join("\n");
+}

package/dist/generators/frappe.js

@@ -0,0 +1,101 @@
+import prettier from "prettier";
+import { toPascalCase } from "../engine/mapper.js";
+function mapPgToFrappeFieldType(col, table) {
+    // Check if this column is a Foreign Key -> Map to Link fieldtype
+    const foreignKey = table.foreignKeys.find((fk) => fk.columnName === col.name);
+    if (foreignKey) {
+        return {
+            fieldtype: "Link",
+            options: toPascalCase(foreignKey.foreignTableName),
+        };
+    }
+    const baseUdt = col.udtName.toLowerCase();
+    switch (baseUdt) {
+        case "int2":
+        case "int4":
+        case "int8":
+            return { fieldtype: "Int" };
+        case "numeric":
+        case "money":
+            return { fieldtype: "Currency" };
+        case "float4":
+        case "float8":
+            return { fieldtype: "Float" };
+        case "bool":
+            return { fieldtype: "Check" };
+        case "text":
+            return { fieldtype: "Text" };
+        case "date":
+            return { fieldtype: "Date" };
+        case "time":
+        case "timetz":
+            return { fieldtype: "Time" };
+        case "timestamp":
+        case "timestamptz":
+            return { fieldtype: "Datetime" };
+        case "json":
+        case "jsonb":
+            return { fieldtype: "Code", options: "JSON" };
+        default:
+            return { fieldtype: "Data" };
+    }
+}
+function toLabel(name) {
+    return name
+        .split("_")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+export async function generateFrappeDocTypes(schemaIR, moduleName = "Core") {
+    const generatedFiles = [];
+    for (const table of schemaIR.tables) {
+        // Skip internal partition child tables if partitioned
+        if (table.tableName.includes("_y20") || table.tableName.includes("_p20")) {
+            continue;
+        }
+        const docTypeName = toPascalCase(table.tableName);
+        const fields = [];
+        for (const col of table.columns) {
+            // Frappe provides its own primary key 'name' field
+            if (col.isPrimaryKey && (col.name === "id" || col.name === "name")) {
+                continue;
+            }
+            const { fieldtype, options } = mapPgToFrappeFieldType(col, table);
+            const fieldDef = {
+                fieldname: col.name,
+                label: toLabel(col.name),
+                fieldtype,
+                reqd: !col.isNullable && col.defaultValue === null ? 1 : 0,
+            };
+            if (options) {
+                fieldDef.options = options;
+            }
+            fields.push(fieldDef);
+        }
+        const docTypePayload = {
+            name: docTypeName,
+            doctype: "DocType",
+            module: moduleName,
+            custom: 1,
+            is_submittable: 0,
+            fields,
+            permissions: [
+                {
+                    role: "System Manager",
+                    read: 1,
+                    write: 1,
+                    create: 1,
+                },
+            ],
+        };
+        const formattedJson = await prettier.format(JSON.stringify(docTypePayload), {
+            parser: "json",
+            tabWidth: 2,
+        });
+        generatedFiles.push({
+            docTypeName,
+            content: formattedJson,
+        });
+    }
+    return generatedFiles;
+}

package/dist/generators/typescript.js

@@ -0,0 +1,47 @@
+import prettier from "prettier";
+import { mapPgTypeToTs, toPascalCase } from "../engine/mapper.js";
+export async function generateTypeScriptDefinitions(schemaIR) {
+    const buffer = [];
+    buffer.push("/**");
+    buffer.push(" * Auto-generated by pg-sync");
+    buffer.push(` * Extracted at: ${schemaIR.extractedAt}`);
+    buffer.push(" * Do not edit this file directly.");
+    buffer.push(" */\n");
+    for (const table of schemaIR.tables) {
+        const interfaceName = toPascalCase(table.tableName);
+        buffer.push("/**");
+        buffer.push(` * Table: ${table.schema}.${table.tableName}`);
+        if (table.isPartitioned) {
+            buffer.push(` * Partition Strategy: ${table.partitionStrategy}`);
+        }
+        if (table.foreignKeys.length > 0) {
+            buffer.push(" * Relations:");
+            for (const fk of table.foreignKeys) {
+                buffer.push(` * - ${fk.columnName} -> ${fk.foreignTableName}(${fk.foreignColumnName})`);
+            }
+        }
+        buffer.push(" */");
+        buffer.push(`export interface ${interfaceName} {`);
+        for (const col of table.columns) {
+            const tsType = mapPgTypeToTs(col.dbType, col.udtName);
+            const nullableFlag = col.isNullable ? " | null" : "";
+            const optionalFlag = col.isNullable || col.defaultValue !== null ? "?" : "";
+            buffer.push(`  ${col.name}${optionalFlag}: ${tsType}${nullableFlag};`);
+        }
+        buffer.push("}\n");
+    }
+    // Generate a master schema lookup map
+    buffer.push("export interface DatabaseSchema {");
+    for (const table of schemaIR.tables) {
+        const interfaceName = toPascalCase(table.tableName);
+        buffer.push(`  ${table.tableName}: ${interfaceName};`);
+    }
+    buffer.push("}\n");
+    const rawCode = buffer.join("\n");
+    return await prettier.format(rawCode, {
+        parser: "typescript",
+        singleQuote: true,
+        semi: true,
+        tabWidth: 2,
+    });
+}

package/dist/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import pc from "picocolors";
+import { runGenerate } from "./commands/generate.js";
+import { runInit } from "./commands/init.js";
+const program = new Command();
+program
+    .name("pg-sync")
+    .description(pc.cyan("PostgreSQL Schema Introspector & Code Generator"))
+    .version("1.0.0");
+program
+    .command("init")
+    .description("Launch interactive setup wizard and generate configuration")
+    .action(async () => {
+    await runInit();
+});
+program
+    .command("generate")
+    .description("Introspect database and generate output files")
+    .option("-u, --url <url>", "PostgreSQL connection string")
+    .option("-s, --schema <schema>", "Database schema to inspect")
+    .option("-o, --output <dir>", "Output directory for generated files")
+    .option("-t, --target <type>", "Output generator target (typescript | frappe)")
+    .option("-c, --config <file>", "Custom configuration file path")
+    .action(async (options) => {
+    await runGenerate({
+        connectionString: options.url,
+        schema: options.schema,
+        outputDir: options.output,
+        target: options.target,
+        configFile: options.config,
+    });
+});
+program.parse(process.argv);

package/dist/utils/config.js

@@ -0,0 +1,18 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const CONFIG_FILENAME = "pg-sync.config.json";
+export async function loadConfig(customPath) {
+    const targetPath = path.resolve(process.cwd(), customPath || CONFIG_FILENAME);
+    try {
+        const raw = await fs.readFile(targetPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveConfig(config, customPath) {
+    const targetPath = path.resolve(process.cwd(), customPath || CONFIG_FILENAME);
+    await fs.writeFile(targetPath, JSON.stringify(config, null, 2), "utf-8");
+    return targetPath;
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@akshythere/pg-sync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "PostgreSQL Schema Introspector",
+  "main": "dist/index.js",
+  "bin": {
+    "pg-sync": "./dist/index.js",
+    "pgs": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "@inquirer/prompts": "^8.7.3",
+    "commander": "^15.0.0",
+    "ejs": "^7.0.1",
+    "ora": "^9.4.1",
+    "pg": "^8.23.1",
+    "picocolors": "^1.1.1",
+    "prettier": "^3.9.9"
+  },
+  "devDependencies": {
+    "@types/ejs": "^3.1.5",
+    "@types/node": "^26.6.4",
+    "@types/pg": "^8.23.1",
+    "@vitest/coverage-v8": "^5.0.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  }
 }