@constructive-io/cli 5.1.24 → 5.2.0

package/README.md

@@ -1,96 +1,20 @@
 # Constructive CLI
 
-> Build secure, role-aware GraphQL backends powered by PostgreSQL with database-first development
+> API Server and Development Tools for PostgreSQL
 
-Constructive CLI is a comprehensive command-line tool that transforms your PostgreSQL database into a powerful GraphQL API. With automated schema generation, sophisticated migration management, and robust deployment capabilities, you can focus on building great applications instead of boilerplate code.
+Constructive CLI provides GraphQL server capabilities and code generation tools for PostgreSQL databases. For database migrations, packages, and deployment operations, use [pgpm](https://pgpm.io).
 
-## ✨ Features
-
-- 🚀 **Database-First Development** - Design your database, get your GraphQL API automatically
-- 🔐 **Built-in Security** - Role-based access control and security policies
-- 📦 **Module System** - Reusable database modules with dependency management
-- 🛠️ **Developer Experience** - Hot-reload development server with GraphiQL explorer
-- 🏗️ **Production Ready** - Deployment plans, versioning, and rollback support
-
-## 🚀 Quick Start
-
-### Installation
+## Installation
 
 ```bash
 npm install -g @constructive-io/cli
 ```
 
-### Create Your First Project
-
-```bash
-# Initialize a new workspace
-cnc init workspace
-cd my-project
-
-# Create your first module
-cnc init
-
-# Deploy to your database
-cnc deploy --createdb
-
-# Start the development server
-cnc server
-```
-
-Visit `http://localhost:5555` to explore your GraphQL API!
-
-## 📖 Core Concepts
-
-### Workspaces and Modules
-
-- **Workspace**: A collection of related database modules
-- **Module**: A self-contained database package with migrations, functions, and types
-- **Dependencies**: Modules can depend on other modules, creating reusable building blocks
-
-### Database-First Workflow
-
-1. **Design** your database schema using SQL migrations
-2. **Deploy** changes with `cnc deploy`
-3. **Develop** against the auto-generated GraphQL API
-4. **Version** and **package** your modules for distribution
-
-## 🛠️ Commands
-
-### Getting Started
-
-#### `cnc init`
-
-Initialize a new Constructive workspace or module.
-
-```bash
-# Create a new workspace
-cnc init workspace
-
-# Create a new module (run inside workspace)
-cnc init
-
-# Use templates from GitHub repository (defaults to constructive-io/pgpm-boilerplates.git)
-cnc init workspace --repo owner/repo
-cnc init --repo owner/repo --from-branch develop
-
-# Use templates from custom paths
-cnc init workspace --template-path ./custom-templates
-cnc init --template-path ./custom-templates/module
-```
-
-**Options:**
-
-- `--repo <repo>` - Template repo (default: `https://github.com/constructive-io/pgpm-boilerplates.git`)
-- `--template-path <path>` - Template sub-path (defaults to `workspace`/`module`) or local path override
-- `--from-branch <branch>` - Branch/tag when cloning the template repo
-
-Templates are cached for one week under the `pgpm` tool namespace. Run `cnc cache clean` if you need to refresh the boilerplates.
+## Commands
 
-### Development
+### `cnc server`
 
-#### `cnc server`
-
-Start the GraphQL development server with hot-reload.
+Start the GraphQL development server.
 
 ```bash
 # Start with defaults (port 5555)
@@ -103,7 +27,16 @@ cnc server --port 8080 --no-postgis
 cnc server --origin http://localhost:3000
 ```
 
-#### `cnc explorer`
+**Options:**
+
+- `--port <number>` - Server port (default: 5555)
+- `--origin <url>` - CORS origin URL
+- `--simpleInflection` - Use simple inflection (default: true)
+- `--oppositeBaseNames` - Use opposite base names (default: false)
+- `--postgis` - Enable PostGIS extension (default: true)
+- `--metaApi` - Enable Meta API (default: true)
+
+### `cnc explorer`
 
 Launch GraphiQL explorer for your API.
 
@@ -115,419 +48,89 @@ cnc explorer
 cnc explorer --origin http://localhost:3000
 ```
 
-#### `cnc docker`
-
-Manage PostgreSQL Docker containers for local development.
-
-```bash
-# Start PostgreSQL container
-cnc docker start
-
-# Stop PostgreSQL container
-cnc docker stop
-```
-
-#### `cnc env`
-
-Display environment configuration for PostgreSQL connection.
-
-```bash
-# Print environment variables for shell export
-cnc env
-
-# Use with eval to set environment
-eval "$(cnc env)"
-
-# Print Supabase local development environment
-cnc env --supabase
-```
-
-## 🔄 Updates
-
-The CLI performs a lightweight npm version check at most once per week (skipped in CI or when `PGPM_SKIP_UPDATE_CHECK` is set). Use `cnc update` to install the latest release (installs `pgpm` by default; pass `--package @constructive-io/cli` to target the CLI package).
-
-### Database Operations
-
-#### `cnc deploy`
-
-Deploy your database changes and migrations.
-
-```bash
-# Deploy to selected database
-cnc deploy
-
-# Create database if it doesn't exist
-cnc deploy --createdb
-
-# Deploy specific package to a tag
-cnc deploy --package mypackage --to @v1.0.0
-
-# Fast deployment without transactions
-cnc deploy --fast --no-tx
-```
-
-#### `cnc verify`
-
-Verify your database state matches expected migrations.
-
-```bash
-# Verify current state
-cnc verify
-
-# Verify specific package
-cnc verify --package mypackage
-```
-
-#### `cnc revert`
-
-Safely revert database changes.
-
-```bash
-# Revert latest changes
-cnc revert
-
-# Revert to specific tag
-cnc revert --to @v1.0.0
-```
-
-### Migration Management
-
-#### `cnc migrate`
-
-Comprehensive migration management.
-
-```bash
-# Initialize migration tracking
-cnc migrate init
-
-# Check migration status
-cnc migrate status
-
-# List all changes
-cnc migrate list
-
-# Show change dependencies
-cnc migrate deps
-```
-
-### Module Management
-
-#### `cnc install`
-
-Install PGPM modules as dependencies.
-
-```bash
-# Install single package
-cnc install @constructive-io/auth
-
-# Install multiple packages
-cnc install @constructive-io/auth @constructive-io/utils
-```
-
-#### `cnc extension`
-
-Interactively manage module dependencies.
-
-```bash
-cnc extension
-```
-
-#### `cnc upgrade-modules`
-
-Upgrade installed pgpm modules to their latest versions from npm.
-
-```bash
-# Interactive selection of modules to upgrade
-cnc upgrade-modules
-
-# Upgrade all installed modules without prompting
-cnc upgrade-modules --all
-
-# Preview available upgrades without making changes
-cnc upgrade-modules --dry-run
-
-# Upgrade specific modules
-cnc upgrade-modules --modules @pgpm/base32,@pgpm/faker
-
-# Upgrade modules across all packages in the workspace
-cnc upgrade-modules --workspace --all
-```
-
 **Options:**
 
-- `--all` - Upgrade all modules without prompting
-- `--dry-run` - Show what would be upgraded without making changes
-- `--modules <names>` - Comma-separated list of specific modules to upgrade
-- `--workspace` - Upgrade modules across all packages in the workspace
-- `--cwd <directory>` - Working directory (default: current directory)
-
-#### `cnc tag`
-
-Version your changes with tags.
-
-```bash
-# Tag latest change
-cnc tag v1.0.0
-
-# Tag with comment
-cnc tag v1.0.0 --comment "Initial release"
-
-# Tag specific change
-cnc tag v1.1.0 --package mypackage --changeName my-change
-```
-
-### Packaging and Distribution
-
-#### `cnc plan`
-
-Generate deployment plans for your modules.
-
-```bash
-cnc plan
-```
-
-#### `cnc package`
-
-Package your module for distribution.
-
-```bash
-# Package with defaults
-cnc package
-
-# Package without deployment plan
-cnc package --no-plan
-```
-
-### Utilities
-
-#### `cnc add`
-
-Add a new database change to your module.
-
-```bash
-# Add a new change
-cnc add my_change
-
-# Add with specific type
-cnc add my_function --type function
-```
-
-#### `cnc export`
-
-Export migrations from existing databases.
-
-```bash
-cnc export
-```
-
-#### `cnc kill`
-
-Clean up database connections and optionally drop databases.
-
-```bash
-# Kill connections and drop databases
-cnc kill
-
-# Only kill connections
-cnc kill --no-drop
-```
-
-#### `cnc clear`
-
-Clear database state.
-
-```bash
-cnc clear
-```
-
-#### `cnc remove`
-
-Remove database changes.
-
-```bash
-cnc remove my_change
-```
-
-#### `cnc analyze`
-
-Analyze database structure.
-
-```bash
-cnc analyze
-```
-
-#### `cnc rename`
-
-Rename database changes.
-
-```bash
-cnc rename old_name new_name
-```
+- `--port <number>` - Server port (default: 5555)
+- `--origin <url>` - CORS origin URL (default: http://localhost:3000)
+- `--simpleInflection` - Use simple inflection (default: true)
+- `--oppositeBaseNames` - Use opposite base names (default: false)
+- `--postgis` - Enable PostGIS extension (default: true)
 
-#### `cnc admin-users`
+### `cnc codegen`
 
-Manage admin users for your database.
+Generate TypeScript types, operations, and SDK from a GraphQL schema.
 
 ```bash
-# Bootstrap admin users
-cnc admin-users bootstrap
-
-# Add an admin user
-cnc admin-users add
-
-# Remove an admin user
-cnc admin-users remove
-```
-
-### Testing
-
-#### `cnc test-packages`
-
-Run integration tests on all modules in a workspace. Creates a temporary database for each module, deploys, and optionally runs verify/revert/deploy cycles.
-
-```bash
-# Test all modules in workspace (deploy only)
-cnc test-packages
-
-# Run full deploy/verify/revert/deploy cycle
-cnc test-packages --full-cycle
-
-# Continue testing all packages even after failures
-cnc test-packages --continue-on-fail
-
-# Exclude specific modules
-cnc test-packages --exclude my-module,another-module
+# From SDL file
+cnc codegen --schema ./schema.graphql --out ./codegen
 
-# Combine options
-cnc test-packages --full-cycle --continue-on-fail --exclude legacy-module
+# From endpoint with Host override
+cnc codegen --endpoint http://localhost:3000/graphql --headerHost meta8.localhost --out ./codegen
 ```
 
 **Options:**
 
-- `--full-cycle` - Run full deploy/verify/revert/deploy cycle (default: deploy only)
-- `--continue-on-fail` - Continue testing all packages even after failures (default: stop on first failure)
-- `--exclude <modules>` - Comma-separated module names to exclude
-- `--cwd <directory>` - Working directory (default: current directory)
-
-**Notes:**
-
-- Discovers modules from workspace `pgpm.json` configuration
-- Creates isolated test databases (`test_<module_name>`) for each module
-- Automatically cleans up test databases after each test
-- Uses internal APIs for deploy/verify/revert operations
-
-## 💡 Common Workflows
-
-### Starting a New Project
-
-```bash
-# 1. Create workspace
-mkdir my-app && cd my-app
-cnc init workspace
-
-# 2. Create your first module
-cnc init
-
-# 3. Add some SQL migrations to sql/ directory
-# 4. Deploy to database
-cnc deploy --createdb
-
-# 5. Start developing
-cnc server
-```
-
-### Using Custom Templates
-
-You can use custom templates from GitHub repositories or local paths:
-
-```bash
-# Initialize workspace with templates from GitHub
-cnc init workspace --repo owner/repo
-
-# Initialize workspace with templates from local path
-cnc init workspace --template-path ./my-custom-templates
-
-# Initialize module with custom templates
-cnc init --template-path ./my-custom-templates
+- `--schema <path>` - Schema SDL file path
+- `--endpoint <url>` - GraphQL endpoint to fetch schema via introspection
+- `--headerHost <host>` - Optional Host header for endpoint requests
+- `--auth <token>` - Optional Authorization header value
+- `--header "Name: Value"` - Optional HTTP header (repeatable)
+- `--out <dir>` - Output root directory (default: graphql/codegen/dist)
+- `--format <gql|ts>` - Document format (default: gql)
+- `--convention <style>` - Filename convention (dashed|underscore|camelcase|camelUpper)
+- `--emitTypes <bool>` - Emit types (default: true)
+- `--emitOperations <bool>` - Emit operations (default: true)
+- `--emitSdk <bool>` - Emit SDK (default: true)
+- `--config <path>` - Config file (JSON/YAML)
+
+**Config file example (`codegen.json`):**
 
-# Use specific branch from GitHub repository
-cnc init workspace --repo owner/repo --from-branch develop
+```json
+{
+  "input": {
+    "schema": "./schema.graphql",
+    "headers": { "Host": "meta8.localhost" }
+  },
+  "output": {
+    "root": "graphql/codegen/dist"
+  },
+  "documents": {
+    "format": "gql",
+    "convention": "dashed",
+    "excludePatterns": [".*Module$"]
+  },
+  "features": {
+    "emitTypes": true,
+    "emitOperations": true,
+    "emitSdk": true,
+    "emitReactQuery": true
+  }
+}
 ```
 
-**Template Structure:**
-Custom templates should follow the same structure as the default templates:
+### `cnc get-graphql-schema`
 
-- For workspace: `boilerplates/workspace/` directory
-- For module: `boilerplates/module/` directory
-- Or provide direct path to `workspace/` or `module/` directory
-
-### Working with Existing Projects
+Fetch or build GraphQL schema SDL.
 
 ```bash
-# 1. Clone and enter project
-git clone <repo> && cd <project>
-
-# 2. Install dependencies
-cnc install
+# From database schemas
+cnc get-graphql-schema --database mydb --schemas myapp,public --out ./schema.graphql
 
-# 3. Deploy to local database
-cnc deploy --createdb
-
-# 4. Start development server
-cnc server
+# From running server
+cnc get-graphql-schema --endpoint http://localhost:3000/graphql --out ./schema.graphql
 ```
 
-### Production Deployment
-
-```bash
-# 1. Create deployment plan
-cnc plan
-
-# 2. Package module
-cnc package
-
-# 3. Deploy to production
-cnc deploy --package myapp --to @production
-
-# 4. Verify deployment
-cnc verify --package myapp
-```
-
-### Get Graphql Schema
-
-Fetch and output your GraphQL schema in SDL.
-
-  - Option 1 – Programmatic builder (from database schemas):
-  - Write to file:
-    - `cnc get-graphql-schema --database constructive --schemas myapp,public --out ./schema.graphql`
-  - Print to stdout:
-    - `cnc get-graphql-schema --database constructive --schemas myapp,public`
-
-  - Option 2 – Fetch from running server (via endpoint introspection):
-  - Write to file:
-    - `cnc get-graphql-schema --endpoint http://localhost:3000/graphql --headerHost meta8.localhost --out ./schema.graphql`
-  - Print to stdout:
-    - `cnc get-graphql-schema --endpoint http://localhost:3000/graphql --headerHost meta8.localhost`
-
-Options:
-- `--database <name>` (Option 1)
-- `--schemas <list>` (Option 1; comma-separated)
-- `--endpoint <url>` (Option 2)
-- `--headerHost <hostname>` (Option 2; optional custom HTTP Host header for vhost-based local setups)
-- `--auth <token>` (Option 2; optional; sets Authorization header)
-- `--header <name: value>` (Option 2; optional; repeatable; adds request headers, last value wins on duplicates)
-- `--out <path>` (optional; if omitted, prints to stdout)
-
-Notes:
-- If your local dev server routes by hostname (e.g., `meta8.localhost`), but is reachable at `http://localhost:<port>`, use:
-  - `cnc get-graphql-schema --endpoint http://localhost:3000/graphql --headerHost meta8.localhost`
-- You can repeat `--header` to add multiple headers, e.g.: `--header 'X-Mode: fast' --header 'Authorization: Bearer abc123'`
-
-Tip:
-- For Option 1, include only the schemas you need (e.g., `myapp,public`) to avoid type naming conflicts when multiple schemas contain similarly named tables.
+**Options:**
 
+- `--database <name>` - Database name (for programmatic builder)
+- `--schemas <list>` - Comma-separated schemas to include
+- `--endpoint <url>` - GraphQL endpoint to fetch schema via introspection
+- `--headerHost <host>` - Optional Host header for endpoint requests
+- `--auth <token>` - Optional Authorization header value
+- `--header "Name: Value"` - Optional HTTP header (repeatable)
+- `--out <path>` - Output file path (prints to stdout if omitted)
 
-## ⚙️ Configuration
+## Configuration
 
 ### Environment Variables
 
@@ -541,85 +144,41 @@ export PGUSER=postgres
 export PGPASSWORD=password
 ```
 
-## 🆘 Getting Help
+## Database Operations
 
-### Command Help
+For database migrations, packages, and deployment, use **pgpm**:
 
 ```bash
-# Global help
-cnc --help
-
-# Command-specific help
-cnc deploy --help
-cnc server -h
+npm install -g pgpm
 ```
 
-### Common Options
+Common pgpm commands:
 
-Most commands support these global options:
+- `pgpm init workspace` - Initialize a new workspace
+- `pgpm init` - Create a new module
+- `pgpm add <change>` - Add a database change
+- `pgpm deploy` - Deploy database changes
+- `pgpm verify` - Verify database state
+- `pgpm revert` - Revert database changes
 
-- `--help, -h` - Show help information
-- `--version, -v` - Show version information
-- `--cwd <dir>` - Set working directory
-### Codegen
+See the [pgpm documentation](https://pgpm.io) for more details.
 
-Generate types, operations, and SDK from a schema or endpoint.
+## Getting Help
 
 ```bash
-# From SDL file
-cnc codegen --schema ./schema.graphql --out ./codegen
-
-# From endpoint with Host override
-cnc codegen --endpoint http://localhost:3000/graphql --headerHost meta8.localhost --out ./codegen
-```
-
-Options:
-- `--schema <path>` or `--endpoint <url>`
-- `--out <dir>` output root (default: `graphql/codegen/dist`)
-- `--format <gql|ts>` documents format
-- `--convention <dashed|underscore|camelcase|camelUpper>` filenames
-- `--headerHost <host>` optional HTTP Host header for endpoint requests
-- `--auth <token>` Authorization header value (e.g., `Bearer 123`)
-- `--header "Name: Value"` repeatable headers
-- `--emitTypes <bool>` `--emitOperations <bool>` `--emitSdk <bool>` `--emitReactQuery <bool>`
-- `--config ./config.json` Use customized config file 
-
-
-Config file (JSON/YAML):
+# Global help
+cnc --help
 
-```bash
-# Use a JSON config to override defaults
-cnc codegen --config ./my-options.json
+# Command-specific help
+cnc server --help
+cnc codegen -h
 ```
 
-Example `my-options.json`:
+## Global Options
 
-```json
-{
-  "input": {
-    "schema": "./schema.graphql",
-    "headers": { "Host": "meta8.localhost" }
-  },
-  "output": {
-    "root": "graphql/codegen/dist/codegen-config",
-    "reactQueryFile": "react-query.ts"
-  },
-  "documents": {
-    "format": "gql",
-    "convention": "dashed",
-    "excludePatterns": [".*Module$", ".*By.+And.+$"]
-  },
-  "features": {
-    "emitTypes": true,
-    "emitOperations": true,
-    "emitSdk": true,
-    "emitReactQuery": true
-  },
-  "reactQuery": {
-    "fetcher": "graphql-request"
-  }
-}
-```
+- `--help, -h` - Show help information
+- `--version, -v` - Show version information
+- `--cwd <dir>` - Set working directory
 
 ---