@indiekitai/pg-complete 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @indiekitai/pg-complete
+
+Smart PostgreSQL autocomplete engine for Node.js — ported from [pgcli](https://github.com/dbcli/pgcli).
+
+## Features
+
+- **SQL keyword completion** — context-aware keyword suggestions
+- **Table/view name completion** — suggests tables and views from your database
+- **Column name completion** — context-aware, knows which table you're referencing
+- **Schema-qualified completion** — `public.users`, `inventory.products`
+- **Function name completion** — built-in + database functions
+- **JOIN ON suggestions** — FK-based and name-based join conditions
+- **Alias awareness** — works with table aliases (`FROM users u`)
+- **Fuzzy matching** — type `ur` to match `users`, `user_roles`
+
+## Installation
+
+```bash
+npm install @indiekitai/pg-complete
+```
+
+## Usage
+
+### With database connection
+
+```typescript
+import { PgCompleter } from '@indiekitai/pg-complete';
+
+const completer = new PgCompleter('postgresql://localhost/mydb');
+await completer.refresh(); // Load schema metadata
+
+const results = completer.complete('SELECT * FROM us');
+// → [{ text: 'users', type: 'table' }, { text: 'user_roles', type: 'table' }]
+
+const results2 = completer.complete('SELECT users.');
+// → [{ text: 'id', type: 'column' }, { text: 'name', type: 'column' }, ...]
+```
+
+### With pre-loaded metadata
+
+```typescript
+import { PgCompleter } from '@indiekitai/pg-complete';
+
+const completer = new PgCompleter();
+completer.setMetadata({
+  tables: {
+    public: {
+      users: [
+        { name: 'id', datatype: 'integer', hasDefault: true, default_: null, foreignKeys: [] },
+        { name: 'name', datatype: 'text', hasDefault: false, default_: null, foreignKeys: [] },
+      ],
+    },
+  },
+  views: {},
+  functions: {},
+  datatypes: {},
+});
+
+const results = completer.complete('SELECT * FROM ');
+```
+
+### CLI
+
+```bash
+# Interactive mode with database
+npx @indiekitai/pg-complete postgresql://localhost/mydb
+
+# Type \c <partial-sql> to see completions
+sql> \c SELECT * FROM us
+  users                          [table]
+  user_roles                     [table]
+```
+
+### MCP Server
+
+```bash
+npx pg-complete-mcp
+```
+
+Exposes `pg_complete` and `pg_connect` tools over MCP stdio protocol.
+
+## API
+
+### `PgCompleter`
+
+#### `constructor(connectionString?: string | PgCompleterOptions)`
+
+Create a new completer. Optionally provide a connection string or options.
+
+#### `async refresh(): Promise<void>`
+
+Connect to the database and load schema metadata.
+
+#### `complete(text: string, cursorPos?: number): Completion[]`
+
+Get completions for the given SQL text at the cursor position.
+
+#### `setMetadata(meta: SchemaMetadata, searchPath?: string[]): void`
+
+Set metadata directly (for testing or pre-loaded scenarios).
+
+### `Completion`
+
+```typescript
+interface Completion {
+  text: string;        // The completion text
+  type: CompletionType; // 'keyword' | 'table' | 'view' | 'column' | 'function' | 'schema' | ...
+  meta?: string;       // Additional info (e.g. column datatype)
+}
+```
+
+## License
+
+MIT