feat(codegen): apiNames auto-expand, schemaDir, --schema-only, graphile-schema package, README headers

[pyramation]

feat(codegen): apiNames auto-expand to multi-target, schemaDir expansion, --schema-only flag, unified CLI handler, graphile-schema package, generated README headers/footers

Summary

Builds on PR #729 (unified multi-target CLI architecture) with PGPM workflow improvements, a consolidation of schema export commands into one unified --schema-only flag, a new schemaDir config option for auto-discovering .graphql files, unification of cnc codegen as a thin wrapper, a cleanup pass removing incorrect deprecations and redundant wrappers, a new lightweight graphile-schema package, Constructive-branded README headers/footers for all generated documentation, and repo-wide housekeeping.

Key Changes

1. Shared ephemeral DB for multi-target PGPM (generate.ts): generateMulti() detects when multiple targets share the same PGPM source (same workspacePath+moduleName or modulePath), deploys once to a single ephemeral DB, and reuses it. Teardown in finally block.

2. Multi-target cnc codegen (codegen.ts): Mirrors the isMulti detection from graphql-codegen CLI — if loaded config lacks top-level endpoint/schemaFile/schemaDir/db, dispatches to generateMulti(). Adds --target <name> flag.

3. apiNames auto-expansion to multi-target (expandApiNamesToMultiTarget()): When a config specifies multiple apiNames (e.g. ['app', 'admin']), it auto-expands into a multi-target config — each API name becomes its own target with its own GraphQL schema and output directory. Single apiNames: ['app'] and explicit schemas: [...] remain single-target. Wired into both CLIs.

4. schemaDir auto-expansion to multi-target (expandSchemaDirToMultiTarget()): New config option schemaDir points to a directory of *.graphql files. Each file becomes its own target, named by filename (e.g. schemas/app.graphql → target app). Enables a workflow where backend devs export SDL files and frontend devs run codegen against a directory of schemas without any DB access. --schema-dir CLI flag added to both CLIs.

5. --schema-only flag on both graphql-codegen and cnc codegen: Exports GraphQL SDL instead of running full codegen. Works with any source (endpoint, file, database, PGPM). With multi-apiNames, writes one .graphql per API. Replaces all previous export commands.

6. Removed redundant commands (⚠️ breaking):

   • cnc get-graphql-schema → use cnc codegen --schema-only
   • cnc export-schema / graphql-codegen export-schema → use cnc codegen --schema-only
   • graphql/server/src/scripts/codegen-schema.ts → use cnc codegen --schema-only
   • graphql/codegen/src/core/export-schema.ts module removed

7. Deprecation cleanup & camelizeArgv unification:

   • Undeprecated generators/index.ts — these are active v5 generator functions, not legacy v4
   • Undeprecated MetaObject/QueryBuilder re-exports in core/index.ts — still actively used
   • Removed formatOutput() and its test — truly deprecated, replaced by writeGeneratedFiles with formatFiles option
   • Removed buildSchemaSDLFromDatabase() passthrough wrapper — callers (DatabaseSchemaSource, PgpmModuleSchemaSource) now import buildSchemaSDL directly from graphile-schema (see TODO #8 below)
   • Unified camelizeArgv flow in both CLIs: camelize once at the top of each handler

8. New graphile-schema package (graphile/graphile-schema/): Lightweight npm package containing buildSchemaSDL and fetchEndpointSchemaSDL extracted from @constructive-io/graphql-server. Eliminates heavy server dependencies (express, cors, grafserv, middleware) from codegen. Uses proper pg-env/pg-cache utilities instead of manual connection string construction, and deepmerge for preset object merging. ⚠️ Breaking: @constructive-io/graphql-server no longer exports these functions — consumers must import from graphile-schema directly.

9. Generated README headers/footers (docs-utils.ts): All 6 README generators (generateTargetReadme, generateRootRootReadme, generateHooksReadme, generateOrmReadme, generateReadme, generateMultiTargetReadme) now include Constructive-branded headers (centered logo + badges) and footers (credit + disclaimer). Provides consistent branding across all generated documentation.

10. Unified cnc codegen as thin wrapper (cli/handler.ts): Extracted shared runCodegenHandler() function containing all core codegen logic. Both graphql-codegen and cnc codegen now delegate to this shared handler after handling their own help/version flags. Eliminates ~150 lines of duplicated code. Uses structural Prompter interface to avoid inquirerer version mismatch between packages.

11. Unit tests for expand functions (expand-targets.test.ts): Added 13 unit tests covering expandApiNamesToMultiTarget and expandSchemaDirToMultiTarget — null cases, single vs. multiple targets, output path defaults, config preservation, file filtering, alphabetical sorting. Removed pointless camelizeArgv mock from codegen.test.ts.

12. --schema-only tests (schema-only.test.ts): Added 5 unit tests covering generate() with schemaOnly: true — file writing, custom filename, no generators required, error handling, directory creation.

13. Documentation cleanup: Updated all stale references to deleted commands (get-graphql-schema, codegen-schema, export-schema) across multiple files:

    • graphql/server/package.json — removed codegen, codegen:clean, and codegen:schema scripts
    • graphql/server/README.md — removed "Codegen" section (server is runtime-only now)
    • graphql/server/tsconfig.json & tsconfig.esm.json — removed src/codegen/**/* and src/schema.ts excludes
    • packages/cli/README.md — replaced get-graphql-schema section with --schema-only docs
    • packages/cli/src/utils/display.ts — removed get-graphql-schema from help text
    • packages/cli/AGENTS.md — updated to reflect current command structure

14. graphile-schema tests (fetch-endpoint-schema.test.ts): Added 5 unit tests for fetchEndpointSchemaSDL using real HTTP mock server — live endpoint fetching, HTTP error handling, invalid JSON response, introspection errors, custom headers/auth.

15. Server cleanup: Removed all dead codegen-related code from @constructive-io/graphql-server:

    • Deleted src/schema.ts backward-compat re-export file
    • Removed graphile-schema dependency (no longer needed)
    • Removed rimraf devDependency (only used by deleted scripts)
    • Updated server-test to import buildSchemaSDL from graphile-schema directly

16. Test script cleanup (41 packages): Removed --passWithNoTests flag from all packages that have actual test files. Only packages with zero tests retain the flag. This ensures tests actually run and fail if test files are missing or broken, rather than silently passing.

Note: This PR targets main and includes all changes from PR #729.

Updates since last revision (latest)

• Removed --passWithNoTests from 41 package.json test scripts that have actual test files
• Packages with zero tests retain --passWithNoTests (correct behavior)

Updates since last revision (previous)

• Removed backward-compat src/schema.ts re-export from server package entirely
• Removed graphile-schema dependency from server (no runtime usage)
• Updated server-test to import from graphile-schema directly
• Removed dead codegen scripts (codegen, codegen:clean) from server package.json
• Removed dead tsconfig excludes (src/codegen/**/*, src/schema.ts)
• Removed rimraf devDependency from server
• Removed "Codegen" section from server README
• Updated 4 documentation files to remove stale references to deleted commands
• Added 5 unit tests to graphile-schema package for fetchEndpointSchemaSDL

Review & Testing Checklist for Human

• ⚠️ BREAKING: @constructive-io/graphql-server no longer exports schema functions — The server package no longer exports buildSchemaSDL or fetchEndpointSchemaSDL. Any external code importing these from @constructive-io/graphql-server will break. Migration: import from graphile-schema instead. Verify no external consumers depend on these exports.
• ⚠️ buildSchemaSDL has no unit tests in graphile-schema package — While fetchEndpointSchemaSDL now has 5 tests, buildSchemaSDL has zero unit tests in the package itself. It's only tested via the integration test in server-test/__tests__/schema-snapshot.test.ts which requires a real database. The pg-env/pg-cache utilities and deepmerge preset merging have never been tested in isolation. Verify connection string construction and preset merging work correctly.
• ⚠️ --schema-only tests only cover schemaFile source — The deleted get-graphql-schema tests covered database mode, endpoint mode with auth/headers/headerHost options. The new schema-only.test.ts only tests with schemaFile source. Endpoint and database sources with auth/headers are untested. Manually verify --schema-only works with endpoint and database sources.
• ⚠️ BREAKING CHANGES — Five commands/exports removed: cnc get-graphql-schema, cnc export-schema, graphql-codegen export-schema, formatOutput() from @constructive-io/graphql-codegen, and schema function exports from @constructive-io/graphql-server. Any existing scripts or external consumers using these will break. Migration path: use cnc codegen --schema-only or graphql-codegen --schema-only for commands; use writeGeneratedFiles with formatFiles: true option instead of formatOutput(); import schema functions from graphile-schema instead of @constructive-io/graphql-server.
• No runtime testing was performed — only pnpm build and CI (TypeScript + unit tests) passed. All features (shared ephemeral DB, multi-target cnc, apiNames auto-expansion, schemaDir expansion, --schema-only, unified handler, graphile-schema package, README headers, doc cleanup, server cleanup) need manual end-to-end testing with a real PGPM workspace and .graphql files.

Test Plan

1. graphile-schema package: Test buildSchemaSDL with a real database and verify connection string construction, schema introspection, and preset merging work correctly. Test fetchEndpointSchemaSDL with a live endpoint and auth/headers options.
2. apiNames auto-expansion: Create config with db: { pgpm: { ... }, apiNames: ['app', 'admin'] }. Run cnc codegen and verify two separate output directories created (./generated/graphql/app, ./generated/graphql/admin) with different schemas.
3. schemaDir auto-expansion: Create directory ./schemas/ with app.graphql and admin.graphql. Create config with schemaDir: './schemas'. Run cnc codegen and verify two targets created, each reading from its respective file.
4. Shared ephemeral DB: Create multi-target config with 3 targets sharing same PGPM workspace+module but different apiNames. Run graphql-codegen and verify console shows [multi-target] Shared PGPM source deployed once for 3 targets: .... Confirm only one ephemeral DB created.
5. --schema-only with PGPM: Run cnc codegen --schema-only --config <pgpm-config> and verify .graphql files written to output directory. Compare SDL with previous cnc get-graphql-schema output.
6. --schema-only with endpoint: Run cnc codegen --schema-only --endpoint https://api.example.com/graphql --output ./schema.graphql and verify SDL written. Test with --auth and --header flags.
7. --schema-only with multi-apiNames: Run cnc codegen --schema-only with config containing apiNames: ['app', 'admin'] and verify two .graphql files created (app.graphql, admin.graphql).
8. --schema-dir CLI flag: Run cnc codegen --schema-dir ./schemas --output ./generated and verify targets created for each .graphql file in the directory.
9. Unified handler: Verify both graphql-codegen and cnc codegen produce identical output for the same config (modulo help/version flags).
10. README headers/footers: Run codegen and verify all generated READMEs include Constructive logo header and disclaimer footer.
11. Documentation accuracy: Verify all CLI flag descriptions in updated docs match actual behavior (especially --schema-only examples).
12. Breaking change verification: Attempt to import buildSchemaSDL from @constructive-io/graphql-server and verify it fails with a clear error. Verify importing from graphile-schema works.
13. Test script cleanup: Run pnpm test in a few of the 41 updated packages and verify tests actually run (not silently passing).

Notes

• This PR combines PR feat(codegen): add unified multi-target CLI architecture #729 (unified multi-target CLI) with the new PGPM improvements, schemaDir expansion, command consolidation, unified CLI handler, graphile-schema package extraction, generated README branding, deprecation cleanup, documentation updates, server cleanup, and test script housekeeping. Review scope is larger than just the features listed above.
• The komoji package was added as a dependency (used by CLI generator).
• The cnc codegen command is now a thin wrapper (~48 lines) that delegates to the shared runCodegenHandler() function, eliminating code duplication.
• The graphile-schema package uses deepmerge@^4.3.1 for preset object merging as requested by the user.
• All 42 CI checks pass.
• The fetchEndpointSchemaSDL tests import getIntrospectionQuery but don't use it (minor unused import).
• The server package is now purely runtime — no codegen functionality remains.
• The --passWithNoTests cleanup affects 41 packages. Detection was based on finding .test.ts/.test.js/.spec.ts files; packages with unusual test file naming/locations may have been missed (low risk).

---

Link to Devin run: https://app.devin.ai/sessions/4bfad737a4ce4a848b01d088ad950986
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring