Merge pull request #59 from constructive-io/devin/1773817552-schema-config-refactor

refactor: update schema export docs from flat props to nested `schema` object

Author: pyramation

skills/constructive-graphql-codegen.zip

@@ -139,9 +139,7 @@ import { generate } from '@constructive-io/graphql-codegen';
 // Export from database
 await generate({
   db: { schemas: ['public'] },
-  schemaOnly: true,
-  schemaOnlyOutput: './schemas',
-  schemaOnlyFilename: 'public.graphql',
+  schema: { enabled: true, output: './schemas', filename: 'public.graphql' },
 });
 
 // Export from PGPM module
@@ -150,16 +148,13 @@ await generate({
     pgpm: { modulePath: './packages/my-module' },
     schemas: ['app_public'],
   },
-  schemaOnly: true,
-  schemaOnlyOutput: './schemas',
-  schemaOnlyFilename: 'app_public.graphql',
+  schema: { enabled: true, output: './schemas', filename: 'app_public.graphql' },
 });
 
 // Export from endpoint
 await generate({
   endpoint: 'https://api.example.com/graphql',
-  schemaOnly: true,
-  schemaOnlyOutput: './schemas',
+  schema: { enabled: true, output: './schemas' },
 });
 ```
 
@@ -232,9 +227,11 @@ interface GenerateOptions {
   cli?: CliConfig | boolean; // Default: false
 
   // Schema export (instead of code generation)
-  schemaOnly?: boolean;
-  schemaOnlyOutput?: string;
-  schemaOnlyFilename?: string;   // Default: 'schema.graphql'
+  schema?: {
+    enabled?: boolean;           // Enable schema export mode
+    output?: string;             // Output directory (default: same as output)
+    filename?: string;           // Default: 'schema.graphql'
+  };
 
   // Documentation (generated alongside code)
   docs?: DocsConfig | boolean; // Default: { readme: true, agents: true, mcp: false, skills: false }

skills/constructive-graphql-codegen/SKILL.md

@@ -34,6 +34,14 @@ npx @constructive-io/graphql-codegen generate [options]
 | `--output <dir>` | `-o` | Output directory | `./generated/graphql` |
 | `--target <name>` | `-t` | Target name (for multi-target configs) | - |
 
+### Schema Export Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--schema-enabled` | Export GraphQL SDL schema file | `false` |
+| `--schema-output <dir>` | Output directory for exported schema | Same as `--output` |
+| `--schema-filename <name>` | Filename for exported schema | `schema.graphql` |
+
 ### Other Options
 
 | Option | Alias | Description | Default |

skills/constructive-graphql-codegen/references/cli-reference.md

@@ -2,6 +2,8 @@
 
 Export GraphQL schemas to `.graphql` SDL files without generating any code. This is useful for creating portable, version-controllable schema artifacts that can then be used as input for code generation via `schemaFile` or `schemaDir`.
 
+Schema export uses a nested `schema` config object: `schema: { enabled, output, filename }`.
+
 ## When to Use
 
 - You want deterministic, portable builds that don't depend on a live database or endpoint at code generation time
@@ -17,9 +19,7 @@ import { generate } from '@constructive-io/graphql-codegen';
 // Export from database
 await generate({
   db: { schemas: ['public'] },
-  schemaOnly: true,
-  schemaOnlyOutput: './schemas',
-  schemaOnlyFilename: 'public.graphql',
+  schema: { enabled: true, output: './schemas', filename: 'public.graphql' },
 });
 
 // Export from PGPM module
@@ -28,16 +28,13 @@ await generate({
     pgpm: { modulePath: './packages/my-module' },
     schemas: ['app_public'],
   },
-  schemaOnly: true,
-  schemaOnlyOutput: './schemas',
-  schemaOnlyFilename: 'app_public.graphql',
+  schema: { enabled: true, output: './schemas', filename: 'app_public.graphql' },
 });
 
 // Export from endpoint
 await generate({
   endpoint: 'https://api.example.com/graphql',
-  schemaOnly: true,
-  schemaOnlyOutput: './schemas',
+  schema: { enabled: true, output: './schemas' },
 });
 
 // Export from PGPM workspace + module name
@@ -49,21 +46,19 @@ await generate({
     },
     schemas: ['app_public'],
   },
-  schemaOnly: true,
-  schemaOnlyOutput: './schemas',
-  schemaOnlyFilename: 'app_public.graphql',
+  schema: { enabled: true, output: './schemas', filename: 'app_public.graphql' },
 });
 ```
 
 ## Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `schemaOnly` | `boolean` | `false` | Enable schema export mode (no code generation) |
-| `schemaOnlyOutput` | `string` | Same as `output` | Output directory for the exported schema file |
-| `schemaOnlyFilename` | `string` | `'schema.graphql'` | Filename for the exported schema |
+| `schema.enabled` | `boolean` | `false` | Enable schema export mode |
+| `schema.output` | `string` | Same as `output` | Output directory for the exported schema file |
+| `schema.filename` | `string` | `'schema.graphql'` | Filename for the exported schema |
 
-When `schemaOnly: true`, no generators run (`reactQuery`, `orm`, `cli` are all ignored). The function fetches the schema via introspection, converts it to SDL using `printSchema()`, and writes it to disk.
+When `schema.enabled` is `true` and no generators are enabled (`reactQuery`, `orm`, `cli` are all false), the function fetches the schema via introspection, converts it to SDL using `printSchema()`, and writes it to disk. When generators are also enabled, the schema is exported alongside code generation.
 
 ## Recommended Two-Step Workflow
 
@@ -76,16 +71,12 @@ import { generate } from '@constructive-io/graphql-codegen';
 // Export each schema you need
 await generate({
   db: { schemas: ['public'] },
-  schemaOnly: true,
-  schemaOnlyOutput: './schemas',
-  schemaOnlyFilename: 'public.graphql',
+  schema: { enabled: true, output: './schemas', filename: 'public.graphql' },
 });
 
 await generate({
   db: { schemas: ['admin'] },
-  schemaOnly: true,
-  schemaOnlyOutput: './schemas',
-  schemaOnlyFilename: 'admin.graphql',
+  schema: { enabled: true, output: './schemas', filename: 'admin.graphql' },
 });
 ```
 
@@ -113,7 +104,7 @@ await generate({
 
 ## Multi-Target Schema Export
 
-When using `generateMulti()` with `schemaOnly: true`, each target's schema is exported with the target name as the filename:
+When using `generateMulti()` with `schema: { enabled: true }`, each target's schema is exported with the target name as the filename:
 
 ```typescript
 import { generateMulti } from '@constructive-io/graphql-codegen';
@@ -129,7 +120,7 @@ await generateMulti({
       output: './schemas',
     },
   },
-  schemaOnly: true,
+  schema: { enabled: true },
 });
 // Produces: schemas/public.graphql, schemas/admin.graphql
 ```
@@ -139,9 +130,7 @@ await generateMulti({
 ```typescript
 const result = await generate({
   db: { schemas: ['public'] },
-  schemaOnly: true,
-  schemaOnlyOutput: './schemas',
-  schemaOnlyFilename: 'public.graphql',
+  schema: { enabled: true, output: './schemas', filename: 'public.graphql' },
 });
 
 if (result.success) {