@constructive-io/cli 0.0.3 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +346 -153
  3. package/commands/{analyze.d.ts → codegen.d.ts} +2 -2
  4. package/commands/codegen.js +131 -0
  5. package/commands/explorer.js +94 -0
  6. package/commands/get-graphql-schema.js +73 -0
  7. package/commands/server.js +187 -0
  8. package/commands.d.ts +0 -1
  9. package/commands.js +42 -61
  10. package/esm/commands/codegen.js +126 -0
  11. package/esm/commands/explorer.js +92 -0
  12. package/esm/commands/get-graphql-schema.js +71 -0
  13. package/esm/commands/server.js +185 -0
  14. package/esm/commands.js +41 -59
  15. package/esm/index.js +16 -36
  16. package/esm/utils/display.js +26 -23
  17. package/esm/utils/index.js +3 -6
  18. package/index.d.ts +0 -22
  19. package/index.js +16 -72
  20. package/package.json +50 -25
  21. package/utils/display.d.ts +1 -1
  22. package/utils/display.js +26 -23
  23. package/utils/index.d.ts +3 -6
  24. package/utils/index.js +7 -20
  25. package/commands/add.d.ts +0 -7
  26. package/commands/add.js +0 -86
  27. package/commands/admin-users/add.d.ts +0 -4
  28. package/commands/admin-users/add.js +0 -89
  29. package/commands/admin-users/bootstrap.d.ts +0 -4
  30. package/commands/admin-users/bootstrap.js +0 -50
  31. package/commands/admin-users/remove.d.ts +0 -4
  32. package/commands/admin-users/remove.js +0 -82
  33. package/commands/admin-users.d.ts +0 -4
  34. package/commands/admin-users.js +0 -68
  35. package/commands/analyze.js +0 -21
  36. package/commands/clear.d.ts +0 -3
  37. package/commands/clear.js +0 -59
  38. package/commands/deploy.d.ts +0 -4
  39. package/commands/deploy.js +0 -146
  40. package/commands/docker.d.ts +0 -3
  41. package/commands/docker.js +0 -194
  42. package/commands/env.d.ts +0 -4
  43. package/commands/env.js +0 -124
  44. package/commands/export.js +0 -129
  45. package/commands/extension.js +0 -48
  46. package/commands/init/index.d.ts +0 -7
  47. package/commands/init/index.js +0 -47
  48. package/commands/init/module.d.ts +0 -4
  49. package/commands/init/module.js +0 -71
  50. package/commands/init/workspace.d.ts +0 -4
  51. package/commands/init/workspace.js +0 -52
  52. package/commands/install.d.ts +0 -4
  53. package/commands/install.js +0 -37
  54. package/commands/kill.js +0 -107
  55. package/commands/migrate/deps.d.ts +0 -4
  56. package/commands/migrate/deps.js +0 -186
  57. package/commands/migrate/init.d.ts +0 -4
  58. package/commands/migrate/init.js +0 -65
  59. package/commands/migrate/list.d.ts +0 -4
  60. package/commands/migrate/list.js +0 -85
  61. package/commands/migrate/status.d.ts +0 -4
  62. package/commands/migrate/status.js +0 -94
  63. package/commands/migrate.d.ts +0 -4
  64. package/commands/migrate.js +0 -69
  65. package/commands/package.d.ts +0 -3
  66. package/commands/package.js +0 -65
  67. package/commands/plan.d.ts +0 -3
  68. package/commands/plan.js +0 -62
  69. package/commands/remove.d.ts +0 -3
  70. package/commands/remove.js +0 -42
  71. package/commands/rename.d.ts +0 -4
  72. package/commands/rename.js +0 -35
  73. package/commands/revert.d.ts +0 -3
  74. package/commands/revert.js +0 -107
  75. package/commands/tag.d.ts +0 -6
  76. package/commands/tag.js +0 -168
  77. package/commands/verify.d.ts +0 -3
  78. package/commands/verify.js +0 -85
  79. package/dist/README.md +0 -412
  80. package/dist/package.json +0 -64
  81. package/esm/commands/add.js +0 -51
  82. package/esm/commands/admin-users/add.js +0 -87
  83. package/esm/commands/admin-users/bootstrap.js +0 -48
  84. package/esm/commands/admin-users/remove.js +0 -80
  85. package/esm/commands/admin-users.js +0 -63
  86. package/esm/commands/analyze.js +0 -16
  87. package/esm/commands/clear.js +0 -54
  88. package/esm/commands/deploy.js +0 -144
  89. package/esm/commands/docker.js +0 -192
  90. package/esm/commands/env.js +0 -122
  91. package/esm/commands/export.js +0 -127
  92. package/esm/commands/extension.js +0 -46
  93. package/esm/commands/init/index.js +0 -42
  94. package/esm/commands/init/module.js +0 -68
  95. package/esm/commands/init/workspace.js +0 -46
  96. package/esm/commands/install.js +0 -35
  97. package/esm/commands/kill.js +0 -105
  98. package/esm/commands/migrate/deps.js +0 -184
  99. package/esm/commands/migrate/init.js +0 -63
  100. package/esm/commands/migrate/list.js +0 -83
  101. package/esm/commands/migrate/status.js +0 -92
  102. package/esm/commands/migrate.js +0 -64
  103. package/esm/commands/package.js +0 -63
  104. package/esm/commands/plan.js +0 -60
  105. package/esm/commands/remove.js +0 -40
  106. package/esm/commands/rename.js +0 -30
  107. package/esm/commands/revert.js +0 -105
  108. package/esm/commands/tag.js +0 -133
  109. package/esm/commands/verify.js +0 -83
  110. package/esm/package.js +0 -26
  111. package/esm/utils/argv.js +0 -92
  112. package/esm/utils/cli-error.js +0 -48
  113. package/esm/utils/database.js +0 -78
  114. package/esm/utils/deployed-changes.js +0 -68
  115. package/esm/utils/module-utils.js +0 -51
  116. package/package.d.ts +0 -1
  117. package/package.js +0 -29
  118. package/utils/argv.d.ts +0 -46
  119. package/utils/argv.js +0 -100
  120. package/utils/cli-error.d.ts +0 -8
  121. package/utils/cli-error.js +0 -52
  122. package/utils/database.d.ts +0 -21
  123. package/utils/database.js +0 -83
  124. package/utils/deployed-changes.d.ts +0 -4
  125. package/utils/deployed-changes.js +0 -72
  126. package/utils/module-utils.d.ts +0 -8
  127. package/utils/module-utils.js +0 -54
  128. /package/commands/{export.d.ts → explorer.d.ts} +0 -0
  129. /package/commands/{extension.d.ts → get-graphql-schema.d.ts} +0 -0
  130. /package/commands/{kill.d.ts → server.d.ts} +0 -0
package/README.md CHANGED
@@ -1,310 +1,383 @@
1
- # **constructive — Platform for building Schemas, APIs, and Apps**
1
+ # Constructive CLI
2
2
 
3
- **A unified cloud platform for data, APIs, and application development.**
3
+ > Build secure, role-aware GraphQL backends powered by PostgreSQL with database-first development
4
4
 
5
- `constructive` brings together everything teams need to model data, ship APIs, and deploy modern applications. It provides a modular foundation for defining schemas, automating infrastructure, and delivering fast, secure experiences—without the complexity of traditional backend stacks.
5
+ 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.
6
6
 
7
7
  ## ✨ Features
8
8
 
9
- * 🧱 **Modular Building Blocks** Compose your app from reusable modules for data, logic, storage, and services. Swap, version, and extend components without rewriting your backend.
10
- * 🔄 **Automated Schema & API Generation** Define your data and relationships once; get auto-generated APIs, migrations, types, and client code across languages.
11
- * ☁️ **Zero-Config Cloud Deployments** Push code, get production. Deploy databases, APIs, functions, and frontends with instant environments and built-in rollout safety.
12
- * 🏗️ **Full-Stack Workspaces** `constructive init` creates a complete workspace with data models, API routes, auth, edge functions, and CI/CD already wired together.
13
- * 📊 **Versioned Infrastructure** Every schema, API, and service change is tracked and versioned, enabling reproducible deployments and safe rollbacks.
14
- * 🌐 **Portable by Design** — Built on open standards and SQL-first workflows, your app runs anywhere—from the constructive cloud to your own infra.
15
- * 🚀 **Optimized Developer Experience** — Type-safe SDKs, hot reloading for data and APIs, local-first dev, and zero boilerplate to get from idea → production fast.
9
+ - 🚀 **Database-First Development** - Design your database, get your GraphQL API automatically
10
+ - 🔐 **Built-in Security** - Role-based access control and security policies
11
+ - 📦 **Module System** - Reusable database modules with dependency management
12
+ - 🛠️ **Developer Experience** - Hot-reload development server with GraphiQL explorer
13
+ - 🏗️ **Production Ready** - Deployment plans, versioning, and rollback support
16
14
 
17
15
  ## 🚀 Quick Start
18
16
 
19
- ### Install & Setup
17
+ ### Installation
20
18
 
21
19
  ```bash
22
- # Install constructive globally
23
20
  npm install -g @constructive-io/cli
24
-
25
- # Start local Postgres (via Docker) and export env vars
26
- constructive docker start
27
- eval "$(constructive env)"
28
21
  ```
29
22
 
30
- > **Tip:** Already running Postgres? Skip the Docker step and just export your PG* vars.
31
-
32
- ---
33
-
34
- ### Create a Workspace and Install a Package
23
+ ### Create Your First Project
35
24
 
36
25
  ```bash
37
- # 1. Create a workspace
38
- constructive init --workspace
39
- cd my-app
26
+ # Initialize a new workspace
27
+ cnc init workspace
28
+ cd my-project
40
29
 
41
- # 2. Create your first module
42
- constructive init
43
- cd packages/your-module
30
+ # Create your first module
31
+ cnc init
44
32
 
45
- # 3. Install a package
46
- constructive install @pgpm/faker
33
+ # Deploy to your database
34
+ cnc deploy --createdb
47
35
 
48
- # 4. Deploy everything
49
- constructive deploy --createdb --database mydb1
50
- psql -d mydb1 -c "SELECT faker.city('MI');"
51
- > Ann Arbor
36
+ # Start the development server
37
+ cnc server
52
38
  ```
53
39
 
54
- ## 🛠️ Commands
40
+ Visit `http://localhost:5555` to explore your GraphQL API!
55
41
 
56
- ### Getting Started
42
+ ## 📖 Core Concepts
57
43
 
58
- - `constructive init` - Initialize a new module
59
- - `constructive init --workspace` - Initialize a new workspace
44
+ ### Workspaces and Modules
60
45
 
61
- ### Development Setup
46
+ - **Workspace**: A collection of related database modules
47
+ - **Module**: A self-contained database package with migrations, functions, and types
48
+ - **Dependencies**: Modules can depend on other modules, creating reusable building blocks
62
49
 
63
- - `constructive docker start` - Start PostgreSQL container (via Docker)
64
- - `constructive docker stop` - Stop PostgreSQL container
65
- - `constructive env` - Print PostgreSQL environment variables for shell export
50
+ ### Database-First Workflow
66
51
 
67
- ### Database Operations
52
+ 1. **Design** your database schema using SQL migrations
53
+ 2. **Deploy** changes with `cnc deploy`
54
+ 3. **Develop** against the auto-generated GraphQL API
55
+ 4. **Version** and **package** your modules for distribution
68
56
 
69
- - `constructive deploy` - Deploy database changes and migrations
70
- - `constructive verify` - Verify database state matches expected migrations
71
- - `constructive revert` - Safely revert database changes
72
-
73
- ### Migration Management
74
-
75
- - `constructive migrate` - Comprehensive migration management
76
- - `constructive migrate init` - Initialize migration tracking
77
- - `constructive migrate status` - Check migration status
78
- - `constructive migrate list` - List all changes
79
- - `constructive migrate deps` - Show change dependencies
57
+ ## 🛠️ Commands
80
58
 
81
- ### Module Management
59
+ ### Getting Started
82
60
 
83
- - `constructive install` - Install database modules as dependencies
84
- - `constructive extension` - Interactively manage module dependencies
85
- - `constructive tag` - Version your changes with tags
61
+ #### `cnc init`
86
62
 
87
- ### Packaging and Distribution
63
+ Initialize a new Constructive workspace or module.
88
64
 
89
- - `constructive plan` - Generate deployment plans for your modules
90
- - `constructive package` - Package your module for distribution
65
+ ```bash
66
+ # Create a new workspace
67
+ cnc init workspace
91
68
 
92
- ### Utilities
69
+ # Create a new module (run inside workspace)
70
+ cnc init
93
71
 
94
- - `constructive add` - Add a new database change
95
- - `constructive remove` - Remove a database change
96
- - `constructive export` - Export migrations from existing databases
97
- - `constructive clear` - Clear database state
98
- - `constructive kill` - Clean up database connections
99
- - `constructive analyze` - Analyze database structure
100
- - `constructive rename` - Rename database changes
101
- - `constructive admin-users` - Manage admin users
72
+ # Use templates from GitHub repository (defaults to constructive-io/pgpm-boilerplates.git)
73
+ cnc init workspace --repo owner/repo
74
+ cnc init --repo owner/repo --from-branch develop
102
75
 
103
- ## 💡 Common Workflows
76
+ # Use templates from custom paths
77
+ cnc init workspace --template-path ./custom-templates
78
+ cnc init --template-path ./custom-templates/module
79
+ ```
104
80
 
105
- ### Starting a New Project and Adding a Change
81
+ **Options:**
106
82
 
107
- ```bash
108
- # 1. Create workspace
109
- constructive init --workspace
110
- cd my-app
83
+ - `--repo <repo>` - Template repo (default: `https://github.com/constructive-io/pgpm-boilerplates.git`)
84
+ - `--template-path <path>` - Template sub-path (defaults to `workspace`/`module`) or local path override
85
+ - `--from-branch <branch>` - Branch/tag when cloning the template repo
111
86
 
112
- # 2. Create your first module
113
- constructive init
114
- cd packages/new-module
87
+ Templates are cached for one week under the `pgpm` tool namespace. Run `cnc cache clean` if you need to refresh the boilerplates.
115
88
 
116
- # 3. Add some SQL migrations to sql/ directory
117
- constructive add some_change
89
+ ### Development
118
90
 
119
- # 4. Deploy to database
120
- constructive deploy --createdb
121
- ```
91
+ #### `cnc server`
122
92
 
123
- ### Working with Existing Projects
93
+ Start the GraphQL development server with hot-reload.
124
94
 
125
95
  ```bash
126
- # 1. Navigate to your module
127
- cd packages/your-module
96
+ # Start with defaults (port 5555)
97
+ cnc server
128
98
 
129
- # 2. Install a package
130
- constructive install @pgpm/faker
131
-
132
- # 3. Deploy all installed modules
133
- constructive deploy --createdb --database mydb1
134
- psql -d mydb1 -c "SELECT faker.city('MI');"
135
- > Ann Arbor
99
+ # Custom port and options
100
+ cnc server --port 8080 --no-postgis
136
101
  ```
137
102
 
138
- ### Testing a module in a workspace
103
+ #### `cnc explorer`
139
104
 
140
- ```bash
141
- # 1. Install workspace dependencies
142
- pnpm install
105
+ Launch GraphiQL explorer for your API.
143
106
 
144
- # 2. Enter the packages/<yourmodule>
145
- cd packages/yourmodule
107
+ ```bash
108
+ # Launch explorer
109
+ cnc explorer
146
110
 
147
- # 3. Test the module in watch mode
148
- pnpm test:watch
111
+ # With custom CORS origin
112
+ cnc explorer --origin http://localhost:3000
149
113
  ```
150
114
 
115
+ ## 🔄 Updates
116
+
117
+ 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).
118
+
151
119
  ### Database Operations
152
120
 
153
- #### `constructive deploy`
121
+ #### `cnc deploy`
154
122
 
155
123
  Deploy your database changes and migrations.
156
124
 
157
125
  ```bash
158
126
  # Deploy to selected database
159
- constructive deploy
127
+ cnc deploy
160
128
 
161
129
  # Create database if it doesn't exist
162
- constructive deploy --createdb
130
+ cnc deploy --createdb
163
131
 
164
132
  # Deploy specific package to a tag
165
- constructive deploy --package mypackage --to @v1.0.0
133
+ cnc deploy --package mypackage --to @v1.0.0
166
134
 
167
135
  # Fast deployment without transactions
168
- constructive deploy --fast --no-tx
136
+ cnc deploy --fast --no-tx
169
137
  ```
170
138
 
171
- #### `constructive verify`
139
+ #### `cnc verify`
172
140
 
173
141
  Verify your database state matches expected migrations.
174
142
 
175
143
  ```bash
176
144
  # Verify current state
177
- constructive verify
145
+ cnc verify
178
146
 
179
147
  # Verify specific package
180
- constructive verify --package mypackage
148
+ cnc verify --package mypackage
181
149
  ```
182
150
 
183
- #### `constructive revert`
151
+ #### `cnc revert`
184
152
 
185
153
  Safely revert database changes.
186
154
 
187
155
  ```bash
188
156
  # Revert latest changes
189
- constructive revert
157
+ cnc revert
190
158
 
191
159
  # Revert to specific tag
192
- constructive revert --to @v1.0.0
160
+ cnc revert --to @v1.0.0
193
161
  ```
194
162
 
195
163
  ### Migration Management
196
164
 
197
- #### `constructive migrate`
165
+ #### `cnc migrate`
198
166
 
199
167
  Comprehensive migration management.
200
168
 
201
169
  ```bash
202
170
  # Initialize migration tracking
203
- constructive migrate init
171
+ cnc migrate init
204
172
 
205
173
  # Check migration status
206
- constructive migrate status
174
+ cnc migrate status
207
175
 
208
176
  # List all changes
209
- constructive migrate list
177
+ cnc migrate list
210
178
 
211
179
  # Show change dependencies
212
- constructive migrate deps
180
+ cnc migrate deps
213
181
  ```
214
182
 
215
183
  ### Module Management
216
184
 
217
- #### `constructive install`
185
+ #### `cnc install`
218
186
 
219
- Install database modules as dependencies.
187
+ Install PGPM modules as dependencies.
220
188
 
221
189
  ```bash
222
190
  # Install single package
223
- constructive install @pgpm/base32
191
+ cnc install @constructive-io/auth
224
192
 
225
193
  # Install multiple packages
226
- constructive install @pgpm/base32 @pgpm/faker
194
+ cnc install @constructive-io/auth @constructive-io/utils
227
195
  ```
228
196
 
229
- #### `constructive extension`
197
+ #### `cnc extension`
230
198
 
231
199
  Interactively manage module dependencies.
232
200
 
233
201
  ```bash
234
- constructive extension
202
+ cnc extension
235
203
  ```
236
204
 
237
- #### `constructive tag`
205
+ #### `cnc tag`
238
206
 
239
207
  Version your changes with tags.
240
208
 
241
209
  ```bash
242
210
  # Tag latest change
243
- constructive tag v1.0.0
211
+ cnc tag v1.0.0
244
212
 
245
213
  # Tag with comment
246
- constructive tag v1.0.0 --comment "Initial release"
214
+ cnc tag v1.0.0 --comment "Initial release"
247
215
 
248
216
  # Tag specific change
249
- constructive tag v1.1.0 --package mypackage --changeName my-change
217
+ cnc tag v1.1.0 --package mypackage --changeName my-change
250
218
  ```
251
219
 
252
220
  ### Packaging and Distribution
253
221
 
254
- #### `constructive plan`
222
+ #### `cnc plan`
255
223
 
256
224
  Generate deployment plans for your modules.
257
225
 
258
226
  ```bash
259
- constructive plan
227
+ cnc plan
260
228
  ```
261
229
 
262
- #### `constructive package`
230
+ #### `cnc package`
263
231
 
264
232
  Package your module for distribution.
265
233
 
266
234
  ```bash
267
235
  # Package with defaults
268
- constructive package
236
+ cnc package
269
237
 
270
238
  # Package without deployment plan
271
- constructive package --no-plan
239
+ cnc package --no-plan
272
240
  ```
273
241
 
274
242
  ### Utilities
275
243
 
276
- #### `constructive export`
244
+ #### `cnc export`
277
245
 
278
246
  Export migrations from existing databases.
279
247
 
280
248
  ```bash
281
- constructive export
249
+ cnc export
282
250
  ```
283
251
 
284
- #### `constructive kill`
252
+ #### `cnc kill`
285
253
 
286
254
  Clean up database connections and optionally drop databases.
287
255
 
288
256
  ```bash
289
257
  # Kill connections and drop databases
290
- constructive kill
258
+ cnc kill
291
259
 
292
260
  # Only kill connections
293
- constructive kill --no-drop
261
+ cnc kill --no-drop
294
262
  ```
295
263
 
296
- ## ⚙️ Configuration
264
+ ## 💡 Common Workflows
297
265
 
298
- ### Environment Variables
266
+ ### Starting a New Project
267
+
268
+ ```bash
269
+ # 1. Create workspace
270
+ mkdir my-app && cd my-app
271
+ cnc init workspace
272
+
273
+ # 2. Create your first module
274
+ cnc init
275
+
276
+ # 3. Add some SQL migrations to sql/ directory
277
+ # 4. Deploy to database
278
+ cnc deploy --createdb
279
+
280
+ # 5. Start developing
281
+ cnc server
282
+ ```
299
283
 
300
- `constructive` uses standard PostgreSQL environment variables (`PGHOST`, `PGPORT`, `PGDATABASE`, `PGUSER`, `PGPASSWORD`).
284
+ ### Using Custom Templates
285
+
286
+ You can use custom templates from GitHub repositories or local paths:
301
287
 
302
- **Quick setup** (recommended):
303
288
  ```bash
304
- eval "$(constructive env)"
289
+ # Initialize workspace with templates from GitHub
290
+ cnc init workspace --repo owner/repo
291
+
292
+ # Initialize workspace with templates from local path
293
+ cnc init workspace --template-path ./my-custom-templates
294
+
295
+ # Initialize module with custom templates
296
+ cnc init --template-path ./my-custom-templates
297
+
298
+ # Use specific branch from GitHub repository
299
+ cnc init workspace --repo owner/repo --from-branch develop
305
300
  ```
306
301
 
307
- **Manual setup** (if you prefer):
302
+ **Template Structure:**
303
+ Custom templates should follow the same structure as the default templates:
304
+
305
+ - For workspace: `boilerplates/workspace/` directory
306
+ - For module: `boilerplates/module/` directory
307
+ - Or provide direct path to `workspace/` or `module/` directory
308
+
309
+ ### Working with Existing Projects
310
+
311
+ ```bash
312
+ # 1. Clone and enter project
313
+ git clone <repo> && cd <project>
314
+
315
+ # 2. Install dependencies
316
+ cnc install
317
+
318
+ # 3. Deploy to local database
319
+ cnc deploy --createdb
320
+
321
+ # 4. Start development server
322
+ cnc server
323
+ ```
324
+
325
+ ### Production Deployment
326
+
327
+ ```bash
328
+ # 1. Create deployment plan
329
+ cnc plan
330
+
331
+ # 2. Package module
332
+ cnc package
333
+
334
+ # 3. Deploy to production
335
+ cnc deploy --package myapp --to @production
336
+
337
+ # 4. Verify deployment
338
+ cnc verify --package myapp
339
+ ```
340
+
341
+ ### Get Graphql Schema
342
+
343
+ Fetch and output your GraphQL schema in SDL.
344
+
345
+ - Option 1 – Programmatic builder (from database schemas):
346
+ - Write to file:
347
+ - `cnc get-graphql-schema --database constructive --schemas myapp,public --out ./schema.graphql`
348
+ - Print to stdout:
349
+ - `cnc get-graphql-schema --database constructive --schemas myapp,public`
350
+
351
+ - Option 2 – Fetch from running server (via endpoint introspection):
352
+ - Write to file:
353
+ - `cnc get-graphql-schema --endpoint http://localhost:3000/graphql --headerHost meta8.localhost --out ./schema.graphql`
354
+ - Print to stdout:
355
+ - `cnc get-graphql-schema --endpoint http://localhost:3000/graphql --headerHost meta8.localhost`
356
+
357
+ Options:
358
+ - `--database <name>` (Option 1)
359
+ - `--schemas <list>` (Option 1; comma-separated)
360
+ - `--endpoint <url>` (Option 2)
361
+ - `--headerHost <hostname>` (Option 2; optional custom HTTP Host header for vhost-based local setups)
362
+ - `--auth <token>` (Option 2; optional; sets Authorization header)
363
+ - `--header <name: value>` (Option 2; optional; repeatable; adds request headers, last value wins on duplicates)
364
+ - `--out <path>` (optional; if omitted, prints to stdout)
365
+
366
+ Notes:
367
+ - If your local dev server routes by hostname (e.g., `meta8.localhost`), but is reachable at `http://localhost:<port>`, use:
368
+ - `cnc get-graphql-schema --endpoint http://localhost:3000/graphql --headerHost meta8.localhost`
369
+ - You can repeat `--header` to add multiple headers, e.g.: `--header 'X-Mode: fast' --header 'Authorization: Bearer abc123'`
370
+
371
+ Tip:
372
+ - 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.
373
+
374
+
375
+ ## ⚙️ Configuration
376
+
377
+ ### Environment Variables
378
+
379
+ Constructive respects standard PostgreSQL environment variables:
380
+
308
381
  ```bash
309
382
  export PGHOST=localhost
310
383
  export PGPORT=5432
@@ -313,22 +386,17 @@ export PGUSER=postgres
313
386
  export PGPASSWORD=password
314
387
  ```
315
388
 
316
- **Supabase local development:**
317
- ```bash
318
- eval "$(constructive env --supabase)"
319
- ```
320
-
321
- ## Getting Help
389
+ ## 🆘 Getting Help
322
390
 
323
391
  ### Command Help
324
392
 
325
393
  ```bash
326
394
  # Global help
327
- constructive --help
395
+ cnc --help
328
396
 
329
397
  # Command-specific help
330
- constructive deploy --help
331
- constructive tag -h
398
+ cnc deploy --help
399
+ cnc server -h
332
400
  ```
333
401
 
334
402
  ### Common Options
@@ -338,10 +406,135 @@ Most commands support these global options:
338
406
  - `--help, -h` - Show help information
339
407
  - `--version, -v` - Show version information
340
408
  - `--cwd <dir>` - Set working directory
409
+ ### Codegen
410
+
411
+ Generate types, operations, and SDK from a schema or endpoint.
412
+
413
+ ```bash
414
+ # From SDL file
415
+ cnc codegen --schema ./schema.graphql --out ./codegen
416
+
417
+ # From endpoint with Host override
418
+ cnc codegen --endpoint http://localhost:3000/graphql --headerHost meta8.localhost --out ./codegen
419
+ ```
420
+
421
+ Options:
422
+ - `--schema <path>` or `--endpoint <url>`
423
+ - `--out <dir>` output root (default: `graphql/codegen/dist`)
424
+ - `--format <gql|ts>` documents format
425
+ - `--convention <dashed|underscore|camelcase|camelUpper>` filenames
426
+ - `--headerHost <host>` optional HTTP Host header for endpoint requests
427
+ - `--auth <token>` Authorization header value (e.g., `Bearer 123`)
428
+ - `--header "Name: Value"` repeatable headers
429
+ - `--emitTypes <bool>` `--emitOperations <bool>` `--emitSdk <bool>` `--emitReactQuery <bool>`
430
+ - `--config ./config.json` Use customized config file
431
+
432
+
433
+ Config file (JSON/YAML):
434
+
435
+ ```bash
436
+ # Use a JSON config to override defaults
437
+ cnc codegen --config ./my-options.json
438
+ ```
439
+
440
+ Example `my-options.json`:
441
+
442
+ ```json
443
+ {
444
+ "input": {
445
+ "schema": "./schema.graphql",
446
+ "headers": { "Host": "meta8.localhost" }
447
+ },
448
+ "output": {
449
+ "root": "graphql/codegen/dist/codegen-config",
450
+ "reactQueryFile": "react-query.ts"
451
+ },
452
+ "documents": {
453
+ "format": "gql",
454
+ "convention": "dashed",
455
+ "excludePatterns": [".*Module$", ".*By.+And.+$"]
456
+ },
457
+ "features": {
458
+ "emitTypes": true,
459
+ "emitOperations": true,
460
+ "emitSdk": true,
461
+ "emitReactQuery": true
462
+ },
463
+ "reactQuery": {
464
+ "fetcher": "graphql-request"
465
+ }
466
+ }
467
+ ```
468
+
469
+ ---
470
+
471
+ ## Education and Tutorials
472
+
473
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
474
+ Get started with modular databases in minutes. Install prerequisites and deploy your first module.
475
+
476
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
477
+ Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
478
+
479
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
480
+ Master the workflow for adding, organizing, and managing database changes with pgpm.
481
+
482
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
483
+ Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
484
+
485
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
486
+ Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
487
+
488
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
489
+ Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
490
+
491
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
492
+ Common issues and solutions for pgpm, PostgreSQL, and testing.
493
+
494
+ ## Related Constructive Tooling
495
+
496
+ ### 🧪 Testing
497
+
498
+ * [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
499
+ * [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
500
+ * [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
501
+ * [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
502
+
503
+ ### 🧠 Parsing & AST
504
+
505
+ * [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
506
+ * [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
507
+ * [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
508
+ * [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
509
+ * [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
510
+ * [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
511
+ * [pg-ast](https://www.npmjs.com/package/pg-ast): **🔍 Low-level AST tools** and transformations for Postgres query structures.
512
+
513
+ ### 🚀 API & Dev Tools
514
+
515
+ * [@constructive-io/graphql-server](https://github.com/constructive-io/constructive/tree/main/graphql/server): **⚡ Express-based API server** powered by PostGraphile to expose a secure, scalable GraphQL API over your Postgres database.
516
+ * [@constructive-io/graphql-explorer](https://github.com/constructive-io/constructive/tree/main/graphql/explorer): **🔎 Visual API explorer** with GraphiQL for browsing across all databases and schemas—useful for debugging, documentation, and API prototyping.
517
+
518
+ ### 🔁 Streaming & Uploads
519
+
520
+ * [etag-hash](https://github.com/constructive-io/constructive/tree/main/streaming/etag-hash): **🏷️ S3-compatible ETags** created by streaming and hashing file uploads in chunks.
521
+ * [etag-stream](https://github.com/constructive-io/constructive/tree/main/streaming/etag-stream): **🔄 ETag computation** via Node stream transformer during upload or transfer.
522
+ * [uuid-hash](https://github.com/constructive-io/constructive/tree/main/streaming/uuid-hash): **🆔 Deterministic UUIDs** generated from hashed content, great for deduplication and asset referencing.
523
+ * [uuid-stream](https://github.com/constructive-io/constructive/tree/main/streaming/uuid-stream): **🌊 Streaming UUID generation** based on piped file content—ideal for upload pipelines.
524
+ * [@constructive-io/s3-streamer](https://github.com/constructive-io/constructive/tree/main/streaming/s3-streamer): **📤 Direct S3 streaming** for large files with support for metadata injection and content validation.
525
+ * [@constructive-io/upload-names](https://github.com/constructive-io/constructive/tree/main/streaming/upload-names): **📂 Collision-resistant filenames** utility for structured and unique file names for uploads.
526
+
527
+ ### 🧰 CLI & Codegen
528
+
529
+ * [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
530
+ * [@constructive-io/cli](https://github.com/constructive-io/constructive/tree/main/packages/cli): **🖥️ Command-line toolkit** for managing Constructive projects—supports database scaffolding, migrations, seeding, code generation, and automation.
531
+ * [@constructive-io/graphql-codegen](https://github.com/constructive-io/constructive/tree/main/graphql/codegen): **✨ GraphQL code generation** (types, operations, SDK) from schema/endpoint introspection.
532
+ * [@constructive-io/query-builder](https://github.com/constructive-io/constructive/tree/main/packages/query-builder): **🏗️ SQL constructor** providing a robust TypeScript-based query builder for dynamic generation of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and stored procedure calls—supports advanced SQL features like `JOIN`, `GROUP BY`, and schema-qualified queries.
533
+ * [@constructive-io/graphql-query](https://github.com/constructive-io/constructive/tree/main/graphql/query): **🧩 Fluent GraphQL builder** for PostGraphile schemas. ⚡ Schema-aware via introspection, 🧩 composable and ergonomic for building deeply nested queries.
341
534
 
342
535
  ## Credits
343
536
 
344
- 🛠 Built by Constructive — if you like our tools, please checkout and contribute to [our github ⚛️](https://github.com/constructive-io)
537
+ **🛠 Built by the [Constructive](https://constructive.io) team creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
345
538
 
346
539
  ## Disclaimer
347
540