feat(codegen): add pagination, filtering, search, find-first; remove MCP; unify casing

[pyramation]

Summary

Addresses feedback that auto-generated CLI handleList methods ignore command-line arguments and perform un-paginated findMany queries, causing terminal flooding (especially with large embedding columns). Also adds advanced filtering/ordering capabilities, a search subcommand for tables with search-capable fields, cursor-based pagination, and a find-first subcommand for full TS SDK parity. Additionally removes all MCP (Model Context Protocol) functionality from the codegen, as it was only generating static JSON tool definition files that weren't providing value. Finally, unifies casing conventions to use komoji as the single origin of truth for case transformations.

Changes to cli-utils.ts (runtime helpers):

• Added parseIntFlag(argv, name) — parses a CLI flag as an integer, handling minimist delivering numbers or strings
• Added parseStringFlag(argv, name) — parses a CLI flag as a string
• Added parseOrderByFlag(argv) — parses --orderBy as a comma-separated list
• Added parseSelectFlag(argv, defaultSelect) — parses --fields into a select object or falls back to default
• Added parseFindManyArgs(argv, defaultSelect, extraWhere?) — one-stop builder for all findMany args (pagination, filtering, ordering, field selection). Accepts optional extraWhere for the search handler to inject search-field clauses
• Added parseFindFirstArgs(argv, defaultSelect) — like parseFindManyArgs but only includes select, where, and condition (no pagination)
• These helpers replace ~50 lines of inline type coercion and conditional spreads per handler with a single function call

Changes to table-command-generator.ts:

• Removed buildParseIntFlag, buildParseStringFlag, and buildOptionalSpread AST helper functions (no longer needed — logic moved to runtime helpers)
• buildListHandler now emits: const findManyArgs = parseFindManyArgs(argv, defaultSelect); instead of ~130 lines of inline AST
• buildFindFirstHandler now emits: const findFirstArgs = parseFindFirstArgs(argv, defaultSelect); instead of ~60 lines of inline AST
• buildSearchHandler now emits: const findManyArgs = parseFindManyArgs(argv, defaultSelect, searchWhere); instead of ~150 lines of inline AST for limit/offset/select/orderBy parsing
• Generated imports changed from buildSelectFromPaths, coerceAnswers, stripUndefined, unflattenDotNotation to coerceAnswers, parseFindFirstArgs, parseFindManyArgs, stripUndefined
• --where and --condition use dot-notation flags (e.g. --where.name.equalTo foo) parsed via unflattenDotNotation (called internally by the runtime helpers)
• --orderBy accepts a comma-separated string (e.g. NAME_ASC,CREATED_AT_DESC)
• --last, --after, --before flags for cursor-based pagination
• Subcommand name → handler name conversion uses toPascalCase from inflekt
• Usage text includes "List Options", "Find-First Options", and conditional "Search Options" sections
• buildSearchHandler auto-builds a where clause from the query string for all detected search field types (tsvector, BM25, trigram, vector embedding)
• Net result of runtime helper refactor: +149 / −653 lines

Changes to docs generators:

• README tables include find-first and search <query> subcommand rows
• Skill reference docs updated with cursor pagination and find-first examples

MCP removal (10 files, ~2665 lines deleted):

• Removed getCliMcpTools(), getMultiTargetCliMcpTools() from cli/docs-generator.ts
• Removed getOrmMcpTools() from orm/docs-generator.ts
• Removed getHooksMcpTools() from hooks-docs-generator.ts
• Removed generateCombinedMcpConfig() from target-docs-generator.ts
• Removed McpTool interface from docs-utils.ts
• Removed mcp option from DocsConfig interface in types/config.ts
• Removed all mcp-related imports, allMcpTools accumulation, and if (docsConfig.mcp) blocks from generate.ts
• Removed MCP re-exports from cli/index.ts barrel
• Removed 5 MCP test cases and 2 snapshots from cli-generator.test.ts
• Updated resolveDocsConfig() to no longer handle mcp option

Casing unification (toConstantCase / toSnakeCase via inflekt ← komoji):

• Replaced all toScreamingSnake (inflekt) → toConstantCase across codegen/utils.ts, naming-helpers.ts, and tests
• Replaced all underscore (inflekt) → toSnakeCase across query-builder.ts, graphql-naming.ts, and export-utils.ts
• All case transform imports now come from inflekt (which internally delegates to komoji as of inflekt@0.6.0)
• Bumped inflekt ^0.5.1 → ^0.6.0 in all 5 consuming packages (graphql/codegen, graphql/query, pgpm/export, graphile/graphile-settings, postgres/pg-codegen)
• Bumped komoji ^0.8.1 → ^0.9.0 in graphql/codegen (still needs toKebabCase directly)
• Removed direct komoji dependency from pgpm/export, pgpm/core, and graphql/query (no longer imported directly)
• Companion PR: constructive-io/dev-utils#74 (merged) — makes komoji the single origin of truth for case transforms; inflekt@0.6.0 re-exports toConstantCase and toSnakeCase from it

Snapshot updates: 5 snapshots updated to reflect the new generated code (runtime helpers). All 312 tests pass (down from 317 — 5 MCP tests removed).

Updates since last revision

• Runtime helper refactor (+149 / −653 lines): Moved all repetitive inline type coercion and conditional spread AST into runtime helpers in cli-utils.ts. The generator now emits parseFindManyArgs(argv, defaultSelect) instead of ~50 lines of inline ternaries and conditional spreads per handler. This eliminates the previous inconsistency where buildSearchHandler used inline AST while buildListHandler and buildFindFirstHandler used the buildParseIntFlag/buildOptionalSpread helpers — all three handlers now use the same unified runtime helpers.
• Removed 3 AST helper functions: buildParseIntFlag, buildParseStringFlag, buildOptionalSpread are no longer needed.
• Generated code is now much cleaner: Each handler's try-body went from ~50+ lines of parsing logic to ~3 lines (defaultSelect declaration + helper call).

Review & Testing Checklist for Human

• Verify parseFindManyArgs where-merge precedence: In cli-utils.ts, the where variable uses parsed.where ?? extraWhere ? { ... } : undefined. Due to JS operator precedence, ?? binds looser than ?:, so if parsed.where is truthy it will be used directly without merging extraWhere. This means search "query" --where.someField.equalTo val would lose the auto-generated search field clauses. Consider whether this needs parentheses: (parsed.where ?? extraWhere) ? { ... } : undefined or a different merge strategy.
• Verify underscore → toSnakeCase behavioral change: The old underscore split every uppercase letter (APIKey → a_p_i_key); toSnakeCase (komoji) groups acronyms (APIKey → api_key). Check if any table/model/field names with consecutive uppercase letters exist across consumers. modelNameToGetMany() and pgpm/export's graphqlRowToPostgresRow() operate on arbitrary model/column names.
• Verify DocsConfig breaking change — any downstream code or config files that reference mcp: true will now fail type-checking. Search for mcp in codegen config files across consuming repos.
• Review buildSearchHandler AST — still has zero snapshot coverage (test fixtures lack search-capable fields). Consider adding a test fixture with tsvector/embedding columns.
• Test with a real generated CLI — run codegen against a schema, then verify:
  • cli list --limit 5 --fields id,name
  • cli list --limit 10 --after <cursor> (cursor pagination)
  • cli find-first --where.name.equalTo test
  • cli list --where.name.equalTo test --orderBy NAME_ASC
  • cli search "some query" --limit 10 --fields id,searchScore (if search-capable table)
  • cli search "query" --where.extra.equalTo val (verify both where clauses are present)
  • Verify no mcp.json is generated when docs: true is set

Notes

• The buildSearchHandler code path has zero snapshot coverage because no test fixture tables have search-capable fields. This is the highest-risk area of the PR.
• The search subcommand is only generated for tables where categorizeSpecialFields() returns groups with category === 'search' or category === 'embedding'.
• The find-first subcommand is generated for all tables unconditionally.
• Minor: skill doc example shows --fields id,id — the template uses --fields id,${pk.name} which produces id,id when PK is id. Cosmetic only.
• Naming conventions: All case transforms now import from inflekt, which delegates to komoji internally. graphql/codegen still imports toKebabCase directly from komoji since inflekt doesn't re-export it.
• The pnpm-lock.yaml diff is large but is almost entirely formatting changes (single-quoted vs block-style YAML) plus the dependency resolution updates for the version bumps.

Link to Devin session: https://app.devin.ai/sessions/c92c3a11450342f8875625a60fa1be28
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

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 6 additional findings.