supatool 0.4.0 → 0.4.1

package/README.md

@@ -1,97 +1,109 @@
 # Supatool
 
-CLI for Supabase: **extract** schema to files with **llms.txt** for LLMs, and **seed** export as AI-friendly JSON. Deploy and CRUD (deprecated) also available.
+**The AI-Native Schema Management CLI for Supabase.** Extract database schemas into LLM-friendly structures, generate `llms.txt` catalogs, and manage seeds without drowning your AI's context.
 
-## Features
+[![npm version](https://img.shields.io/npm/v/supatool.svg)](https://www.npmjs.com/package/supatool)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-- **Extract** – Tables, views, RLS, functions, triggers from DB into files. One file per table (DDL + RLS + triggers). Multi-schema: `--schema public,agent` → `schemas/public/`, `schemas/agent/`.
-- **llms.txt** – Catalog with OBJECTS, RELATIONS, RPC_TABLES, ALL_SCHEMAS. README in output links to it.
-- **Seed** – Export table data to JSON; llms.txt index in `supabase/seeds/`.
-- **Deploy** – Push local schema to remote (`supatool deploy --dry-run`).
-- CRUD code gen is **deprecated** (`supatool crud`, `gen:crud`); prefer writing code with an LLM.
+## Why Supatool?
 
-See [CHANGELOG.md](./CHANGELOG.md) for version history.
+Modern AI coding tools (Cursor, Claude, MCP) often struggle with large database schemas. Typical issues include:
+- **Token Waste:** Reading the entire schema at once consumes 10k+ tokens.
+- **Lost Context:** Frequent API calls to fetch table details via MCP lead to fragmented reasoning.
+- **Inaccuracy:** AI misses RLS policies or complex FK relations split across multiple files.
 
-## Install
+**Supatool solves this** by reorganizing your Supabase schema into a highly searchable, indexed, and modular structure that helps AI "understand" your DB with minimal tokens.
 
-```bash
-npm install -g supatool
-# or: yarn global add supatool  |  pnpm add -g supatool
-```
+---
 
-## Extract
+## Key Features
 
-Set connection (e.g. in `.env.local`):
+- **Extract (AI-Optimized)** – DDL, RLS, and Triggers are bundled into **one file per table**. AI gets the full picture of a table by opening just one file.
+- **llms.txt Catalog** – Automatically generates a standard `llms.txt` listing all OBJECTS, RELATIONS (FKs), and RPC dependencies. This serves as the "Map" for AI agents.
+- **Multi-Schema Support** – Group objects by schema (e.g., `public`, `agent`, `auth`) with proper schema-qualification in SQL.
+- **Seed for AI** – Export table data as JSON. Includes a dedicated `llms.txt` for seeds so AI can see real data structures.
+- **Safe Deploy** – Push local schema changes with `--dry-run` to preview DDL before execution.
+- **CRUD (Deprecated)** – Legacy code generation is still available but discouraged in favor of LLM-native development.
 
-```bash
-echo "SUPABASE_CONNECTION_STRING=postgresql://..." >> .env.local
-```
+---
 
-Extract all objects:
+## Quick Start
 
 ```bash
-supatool extract --all -o supabase/schemas
-# Optional: --schema public,agent  |  -t "user_*"  |  -c "postgresql://..."
-# With --force: clears output dir then writes (no orphan files).
-```
+npm install -g supatool
+# Set your connection string
+export SUPABASE_CONNECTION_STRING="postgresql://postgres:[password]@db.[ref].supabase.co:5432/postgres"
 
-**Output:**
+# Extract schema and generate AI-ready docs
+supatool extract --schema public,auth -o supabase/schemas
 
 ```
+
+### Output Structure
+
+```text
 supabase/schemas/
-├── README.md         # Points to llms.txt
-├── llms.txt          # OBJECTS, RELATIONS, RPC_TABLES, ALL_SCHEMAS (read this first for AI)
-├── schema_index.json # Same as llms.txt, for agents that parse JSON
-├── schema_summary.md # One-file overview: tables, relations, RPCs
-├── tables/
-├── views/
-├── rpc/
-├── cron/
-└── types/
+├── llms.txt          # 🗺️ THE ENTRY POINT: Read this first to understand the DB map
+├── schema_index.json # 🤖 For JSON-parsing agents
+├── schema_summary.md # 📄 Single-file overview for quick human/AI scanning
+├── README.md         # Navigation guide
+└── [schema_name]/
+    ├── tables/       # table_name.sql (DDL + RLS + Triggers)
+    ├── views/
+    └── rpc/
+
 ```
 
-Multi-schema: `schemas/public/`, `schemas/agent/`, etc., each with tables/, views/, rpc/.
+---
 
-**Env:** `SUPABASE_CONNECTION_STRING` or `DATABASE_URL`; optional `SUPATOOL_MAX_CONCURRENT` (default 20).
+## Best Practices for AI Agents (Cursor / Claude / MCP)
 
-## Seed
+To get the best results from your AI coding assistant, follow these steps:
 
-Export selected tables as JSON for AI/reference:
+1. **Start with the Map:** Always ask the AI to read `supabase/schemas/llms.txt` first.
+2. **Targeted Reading:** Once the AI identifies the relevant tables from the catalog, instruct it to open only those specific `.sql` files.
+3. **Understand Relations:** Use the `RELATIONS` section in `llms.txt` to help the AI write accurate JOINs without reading every file.
+4. **RPC Context:** If using functions, refer to `RPC_TABLES` in `llms.txt` to know which tables are affected.
+
+---
+
+## Commands
+
+### Extract
 
 ```bash
-supatool seed --tables tables.yaml --connection "postgresql://..."
+supatool extract --all -o supabase/schemas
+# Options:
+# --schema public,agent   Specify schemas
+# -t "user_*"             Filter tables by pattern
+# --force                 Clear output dir before writing (prevents orphan files)
+
 ```
 
-`tables.yaml`:
+### Seed
 
-```yaml
-tables:
-  - users
-  - public.orders
-```
+Export specific tables for AI reference or testing:
 
-- Output: `supabase/seeds/<timestamp>_supatool/{table}_seed.json`
-- `llms.txt` is written in `supabase/seeds/` listing files and row counts.
+```bash
+supatool seed --tables tables.yaml
+
+```
 
-Do not include sensitive data in seed files.
+*Outputs JSON files and a `llms.txt` index in `supabase/seeds/`.*
 
-## For AI / coding agents (Claude CLI, Cursor, etc.)
+### Deploy
 
-- **Entry point:** Read `supabase/schemas/llms.txt` first. It lists all objects, relations, RPC→tables, and schemas.
-- **Then** open only the files you need (paths under OBJECTS). Use RELATIONS for joins; RPC_TABLES to see which RPCs touch which tables.
-- **Optional:** `schema_index.json` (same data as llms.txt) and `schema_summary.md` (one-file overview) are written when you run `supatool extract`.
-- **Seeds:** `supabase/seeds/llms.txt` lists seed JSON files; it references the schema catalog at `../schemas/llms.txt` when present.
+```bash
+supatool deploy --dry-run
 
-## Other commands
+```
 
-- `supatool help` – List commands
-- `supatool deploy --dry-run` – Preview deploy
-- CRUD: `supatool crud`, `gen:crud` (deprecated)
+---
 
 ## Repository
 
-[https://github.com/idea-garage/supatool](https://github.com/idea-garage/supatool) · [npm](https://www.npmjs.com/package/supatool)
+[GitHub](https://github.com/idea-garage/supatool) · [npm](https://www.npmjs.com/package/supatool)
 
 ---
 
-Acknowledgements: Development would not be this convenient without [Supabase](https://supabase.com/). Thanks to the team and the platform.
+*Developed with ❤️ for the Supabase community. Use at your own risk. Always backup your DB before deployment.*

package/dist/sync/definitionExtractor.js

@@ -189,6 +189,44 @@ async function fetchRlsPolicies(client, spinner, progress, schemas = ['public'])
         return [];
     }
 }
+/**
+ * Fetch RLS enabled flag and policy count for all tables (pg_class.relrowsecurity + pg_policies)
+ */
+async function fetchTableRlsStatus(client, schemas = ['public']) {
+    if (schemas.length === 0)
+        return [];
+    const schemaPlaceholders = schemas.map((_, i) => `$${i + 1}`).join(', ');
+    const result = await client.query(`
+    SELECT
+      n.nspname AS schema_name,
+      c.relname AS table_name,
+      COALESCE(c.relrowsecurity, false) AS rls_enabled
+    FROM pg_class c
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE c.relkind = 'r'
+      AND n.nspname IN (${schemaPlaceholders})
+    ORDER BY n.nspname, c.relname
+  `, schemas);
+    const policyCountMap = new Map();
+    const policyResult = await client.query(`
+    SELECT schemaname, tablename, COUNT(*) AS cnt
+    FROM pg_policies
+    WHERE schemaname IN (${schemaPlaceholders})
+    GROUP BY schemaname, tablename
+  `, schemas);
+    for (const row of policyResult.rows) {
+        policyCountMap.set(`${row.schemaname}.${row.tablename}`, parseInt(row.cnt, 10));
+    }
+    return result.rows.map((r) => {
+        const key = `${r.schema_name}.${r.table_name}`;
+        return {
+            schema: r.schema_name,
+            table: r.table_name,
+            rlsEnabled: !!r.rls_enabled,
+            policyCount: policyCountMap.get(key) ?? 0
+        };
+    });
+}
 /**
  * Fetch FK relations list (for llms.txt RELATIONS)
  */
@@ -973,7 +1011,7 @@ async function generateCreateTableDDL(client, tableName, schemaName = 'public')
 /**
  * Save definitions to files (merge RLS/triggers into table/view; schema folders when multi-schema)
  */
-async function saveDefinitionsByType(definitions, outputDir, separateDirectories = true, schemas = ['public'], relations = [], rpcTables = [], allSchemas = [], version) {
+async function saveDefinitionsByType(definitions, outputDir, separateDirectories = true, schemas = ['public'], relations = [], rpcTables = [], allSchemas = [], version, tableRlsStatus = []) {
     const fs = await Promise.resolve().then(() => __importStar(require('fs')));
     const path = await Promise.resolve().then(() => __importStar(require('path')));
     const outputDate = new Date().toLocaleDateString('en-CA', { year: 'numeric', month: '2-digit', day: '2-digit' });
@@ -1064,12 +1102,12 @@ async function saveDefinitionsByType(definitions, outputDir, separateDirectories
         const ddlWithNewline = def.ddl.endsWith('\n') ? def.ddl : def.ddl + '\n';
         await fsPromises.writeFile(filePath, headerComment + ddlWithNewline);
     }
-    await generateIndexFile(toWrite, outputDir, separateDirectories, multiSchema, relations, rpcTables, allSchemas, schemas, version);
+    await generateIndexFile(toWrite, outputDir, separateDirectories, multiSchema, relations, rpcTables, allSchemas, schemas, version, tableRlsStatus);
 }
 /**
  * Generate index file for DB objects (RLS/triggers already merged into table/view)
  */
-async function generateIndexFile(definitions, outputDir, separateDirectories = true, multiSchema = false, relations = [], rpcTables = [], allSchemas = [], extractedSchemas = [], version) {
+async function generateIndexFile(definitions, outputDir, separateDirectories = true, multiSchema = false, relations = [], rpcTables = [], allSchemas = [], extractedSchemas = [], version, tableRlsStatus = []) {
     const fs = await Promise.resolve().then(() => __importStar(require('fs')));
     const path = await Promise.resolve().then(() => __importStar(require('path')));
     const outputDate = new Date().toLocaleDateString('en-CA', { year: 'numeric', month: '2-digit', day: '2-digit' });
@@ -1101,6 +1139,21 @@ async function generateIndexFile(definitions, outputDir, separateDirectories = t
         cron: definitions.filter(def => def.type === 'cron'),
         type: definitions.filter(def => def.type === 'type')
     };
+    // schema.table -> RLS status (for Tables docs and warnings)
+    const rlsMap = new Map();
+    for (const s of tableRlsStatus) {
+        rlsMap.set(`${s.schema}.${s.table}`, s);
+    }
+    const formatRlsNote = (schema, name) => {
+        const s = rlsMap.get(`${schema}.${name}`);
+        if (!s)
+            return '';
+        if (!s.rlsEnabled)
+            return ' **⚠️ RLS disabled**';
+        if (s.policyCount === 0)
+            return ' (RLS: enabled, policies: 0)';
+        return ` (RLS: enabled, policies: ${s.policyCount})`;
+    };
     // Build relative path per file (schema/type/file when multiSchema)
     const getRelPath = (def) => {
         const typeDir = separateDirectories ? (typeDirNames[def.type] ?? def.type) : '.';
@@ -1123,6 +1176,9 @@ async function generateIndexFile(definitions, outputDir, separateDirectories = t
         readmeContent += 'When multiple schemas are extracted, each schema has its own subfolder (e.g. `public/tables/`, `agent/views/`).\n\n';
     }
     readmeContent += 'Full catalog and relations: [llms.txt](llms.txt)\n';
+    if (tableRlsStatus.some(s => !s.rlsEnabled)) {
+        readmeContent += '\n⚠️ Tables with RLS disabled: [rls_warnings.md](rls_warnings.md)\n';
+    }
     // === llms.txt ===
     let llmsContent = headerLine;
     llmsContent += 'Database Schema - Complete Objects Catalog\n';
@@ -1138,7 +1194,8 @@ async function generateIndexFile(definitions, outputDir, separateDirectories = t
         const filePath = getRelPath(def);
         const commentSuffix = def.comment ? ` # ${def.comment}` : '';
         const displayName = def.schema ? `${def.schema}.${def.name}` : def.name;
-        llmsContent += `${def.type}:${displayName}:${filePath}${commentSuffix}\n`;
+        const rlsSuffix = def.type === 'table' && def.schema ? formatRlsNote(def.schema, def.name) : '';
+        llmsContent += `${def.type}:${displayName}:${filePath}${commentSuffix}${rlsSuffix}\n`;
     });
     if (relations.length > 0) {
         llmsContent += '\nRELATIONS\n';
@@ -1172,12 +1229,21 @@ async function generateIndexFile(definitions, outputDir, separateDirectories = t
     fs.writeFileSync(llmsPath, llmsContent);
     // schema_index.json (same data for agents that parse JSON)
     const schemaIndex = {
-        objects: definitions.map(def => ({
-            type: def.type,
-            name: def.schema ? `${def.schema}.${def.name}` : def.name,
-            path: getRelPath(def),
-            ...(def.comment && { comment: def.comment })
-        })),
+        objects: definitions.map(def => {
+            const base = {
+                type: def.type,
+                name: def.schema ? `${def.schema}.${def.name}` : def.name,
+                path: getRelPath(def),
+                ...(def.comment && { comment: def.comment })
+            };
+            if (def.type === 'table' && def.schema) {
+                const s = rlsMap.get(`${def.schema}.${def.name}`);
+                if (s) {
+                    base.rls = s.rlsEnabled ? (s.policyCount === 0 ? 'enabled_no_policies' : `enabled_${s.policyCount}_policies`) : 'disabled';
+                }
+            }
+            return base;
+        }),
         relations: relations.map(r => ({ from: r.from, to: r.to })),
         rpc_tables: rpcTables.map(rt => ({ rpc: rt.rpc, tables: rt.tables })),
         all_schemas: allSchemas.length > 0
@@ -1188,14 +1254,15 @@ async function generateIndexFile(definitions, outputDir, separateDirectories = t
             : undefined
     };
     fs.writeFileSync(path.join(outputDir, 'schema_index.json'), JSON.stringify(schemaIndex, null, 2), 'utf8');
-    // schema_summary.md (one-file overview for AI)
+    // schema_summary.md (one-file overview for AI) — include RLS status per table
     let summaryMd = '# Schema summary\n\n';
     const tableDefs = definitions.filter(d => d.type === 'table' || d.type === 'view');
     if (tableDefs.length > 0) {
         summaryMd += '## Tables / Views\n';
         tableDefs.forEach(d => {
             const name = d.schema ? `${d.schema}.${d.name}` : d.name;
-            summaryMd += d.comment ? `- ${name} (# ${d.comment})\n` : `- ${name}\n`;
+            const rlsNote = d.type === 'table' && d.schema ? formatRlsNote(d.schema, d.name) : '';
+            summaryMd += d.comment ? `- ${name}${rlsNote} (# ${d.comment})\n` : `- ${name}${rlsNote}\n`;
         });
         summaryMd += '\n';
     }
@@ -1220,6 +1287,18 @@ async function generateIndexFile(definitions, outputDir, separateDirectories = t
         summaryMd += `- Not extracted: ${allSchemas.filter(s => !extractedSet.has(s)).join(', ') || '(none)'}\n`;
     }
     fs.writeFileSync(path.join(outputDir, 'schema_summary.md'), summaryMd, 'utf8');
+    // RLS disabled tables warning doc (tables only; RLS enabled with 0 policies is not warned)
+    const rlsNotEnabled = tableRlsStatus.filter(s => !s.rlsEnabled);
+    if (rlsNotEnabled.length > 0) {
+        let warnMd = '# Tables with RLS disabled (warning)\n\n';
+        warnMd += 'The following tables do not have Row Level Security enabled.\n';
+        warnMd += 'Enabling RLS is recommended for production security.\n\n';
+        warnMd += '| Schema | Table |\n|--------|-------|\n';
+        rlsNotEnabled.forEach(s => {
+            warnMd += `| ${s.schema} | ${s.table} |\n`;
+        });
+        fs.writeFileSync(path.join(outputDir, 'rls_warnings.md'), warnMd, 'utf8');
+    }
 }
 /**
  * Classify and output definitions
@@ -1479,13 +1558,34 @@ async function extractDefinitions(options) {
                 console.warn('RELATIONS/RPC_TABLES extraction skipped:', err);
             }
         }
+        // RLS status (for Tables docs, rls_warnings.md, and extract-time warning)
+        let tableRlsStatus = [];
+        try {
+            const tableDefs = allDefinitions.filter(d => d.type === 'table');
+            if (tableDefs.length > 0) {
+                tableRlsStatus = await fetchTableRlsStatus(client, schemas);
+            }
+        }
+        catch (err) {
+            if (process.env.SUPATOOL_DEBUG) {
+                console.warn('RLS status fetch skipped:', err);
+            }
+        }
         // When force: remove output dir then write (so removed tables don't leave files)
         if (force && fs.existsSync(outputDir)) {
             fs.rmSync(outputDir, { recursive: true });
         }
         // Save definitions (table+RLS+triggers merged, schema folders)
         spinner.text = 'Saving definitions to files...';
-        await saveDefinitionsByType(allDefinitions, outputDir, separateDirectories, schemas, relations, rpcTables, allSchemas, version);
+        await saveDefinitionsByType(allDefinitions, outputDir, separateDirectories, schemas, relations, rpcTables, allSchemas, version, tableRlsStatus);
+        // Warn at extract time when any table has RLS disabled
+        const rlsNotEnabled = tableRlsStatus.filter(s => !s.rlsEnabled);
+        if (rlsNotEnabled.length > 0) {
+            console.warn('');
+            console.warn('⚠️  Tables with RLS disabled: ' + rlsNotEnabled.map(s => `${s.schema}.${s.table}`).join(', '));
+            console.warn('   Details: ' + outputDir + '/rls_warnings.md');
+            console.warn('');
+        }
         // Show stats
         const counts = {
             table: allDefinitions.filter(def => def.type === 'table').length,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supatool",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "CLI for Supabase: extract schema (tables, views, RLS, RPC) to files + llms.txt for LLM, deploy local schema, seed export. CRUD code gen deprecated.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",