test(server-test): CLI e2e tests + field-specific search examples in generated docs

[pyramation]

Summary

Adds 11 end-to-end tests (2 suites) that exercise the full CLI pipeline: codegen → transpile → execute as child process against a running PostgreSQL database with a real GraphQL server.

Also adds field-specific search examples to all generated CLI docs so that agents and users can see concrete dot-notation flags for each search type (tsvector, trgm, BM25, pgvector, composite fullTextSearch).

CLI E2E Tests

Approach (Approach A):

1. getConnections() spins up a real Postgres DB + GraphQL HTTP server
2. generateCli() and generateOrm() produce TypeScript source files
3. ts.transpileModule strips types without resolving imports (avoids needing all type packages in a temp dir)
4. Appstash context is configured via APPSTASH_BASE_DIR pointing at a temp directory with the test server endpoint
5. A child process (spawn, not execFileSync) runs the compiled CLI against the live server
6. stdout is parsed and assertions verify the results

Why spawn instead of execFileSync: The GraphQL server runs in the same Node.js process. Synchronous child execution blocks the event loop, preventing the server from responding — causing a deadlock/timeout.

Suite 1 — Animals (simple-seed, 5 tests):

1. Paginated list with --where (dot-notation) + --fields projection
2. Cursor-based forward pagination (--limit + --after)
3. find-first with --where.name.equalTo
4. Combined --where + --orderBy + --fields
5. Empty result set handling

Suite 2 — Search CLI (search-seed, 6 tests):

1. tsvector search via --where.tsvTsv (dot-notation passthrough to server's actual filter field)
2. trgm fuzzy matching via --where.trgmTitle.value + --where.trgmTitle.threshold
3. Composite fullTextSearch filter via --where.fullTextSearch
4. Search + pagination (--where.tsvTsv + --limit)
5. pgvector error handling — verifies CLI returns {ok: false, errors: [...]} when vector arrays are passed via dot-notation (string coercion, not JSON arrays — a known CLI limitation for complex types)
6. Schema introspection — verifies the Article type exposes expected search fields (tsvRank, titleTrgmSimilarity, bodyTrgmSimilarity, searchScore, and conditionally pgvector fields)

Package.json changes: Added @0no-co/graphql.web, gql-ast, appstash (^0.7.0), inquirerer, and nested-obj as devDependencies in server-test — these are ORM/CLI runtime deps needed by the child process.

Generated Search Examples in CLI Docs

New buildSearchExamples() and buildSearchExamplesMarkdown() helpers in docs-utils.ts. When a table has search-capable fields, generated README and skill references now include concrete examples:

• tsvector: --where.<field> "search query" --fields title,tsvRank
• trgm: --where.trgm<Base>.value "query" --where.trgm<Base>.threshold 0.3
• BM25: --where.bm25<Base>.query "search query"
• pgvector: --where.<field>.vector '[...]' --where.<field>.distance 1.0 (with CLI limitation note)
• Composite: --where.fullTextSearch "query" (dispatches to all text adapters)
• Combined: search + pagination + field projection example

Field-name derivation mirrors buildSearchHandler in table-command-generator.ts so examples always match the generated code. Integrated into all four generators: single-target README, single-target skills, multi-target README, and multi-target skills. Replaces the previous single generic search "query text" example.

Updates since last revision

• Extracted shared runCli helper: Moved runCli() from inline per-suite to a shared module-level function taking (distDir, tmpHome, ...args) — eliminates ~60 lines of duplication between Suite 1 and Suite 2.
• Template literal for runner script: Replaced [...].join('\n') array-of-strings approach with a readable RUNNER_SCRIPT template literal constant.
• Fixed duplicate JSDoc: Removed duplicate JSDoc comment on setupAppstashContext.
• Fixed stale header: Removed Suite 3 reference from file header comment (blueprint tests were removed in a prior revision).

Review & Testing Checklist for Human

• buildSearchExamples field-name derivation duplicates buildSearchHandler logic: The BM25 (bodyBm25Score → bm25Body) and trgm (titleTrgmSimilarity → trgmTitle) name-mapping regexes in docs-utils.ts are copy-pasted from table-command-generator.ts. If one changes, the other will silently produce wrong examples. Consider whether this should be a shared utility.
• Hardcoded title,tsvRank in generated examples: buildSearchExamples uses title as the example display field, which may not exist on all tables. Verify this is acceptable for example-quality docs or whether it should derive a field name from the table.
• CLI exits 0 on GraphQL errors (Test 5): The generated CLI returns {ok: false, errors: [...]} with exit code 0 when the server rejects a query. This is the current behavior being tested, not a bug introduced by this PR — but it may be worth considering whether the CLI should exit non-zero on server errors in a follow-up.
• buildArticlesTable() is hand-crafted (lines 609–751): Manually mirrors the search-seed schema. If the search plugin's naming conventions change or the schema.sql fixture evolves, this Table object will silently produce wrong generated code. Cross-check field names against search-seed/schema.sql and the live introspection output.
• Hardcoded UUID in Suite 1 Test 3: Asserts node.id === 'a0000001-0000-0000-0000-000000000001' — tied to simple-seed/test-data.sql. Confirm this ID exists and won't change.

Recommended test plan: Run cd graphql/server-test && npx jest cli-e2e --verbose in CI (requires PostgreSQL) to confirm all 11 tests pass. Also verify the existing test suite still passes (pnpm test). For the doc generation changes, run cd graphql/codegen && pnpm test and inspect a generated skill reference for a search-enabled table to confirm the new examples render correctly.

Notes

• The pnpm-lock.yaml diff is large but is purely formatting changes (single-line vs multi-line resolution objects) from a lockfile refresh — no dependency version changes beyond appstash@0.7.0.
• The graphile-cache ERROR log during teardown (PostGraphile instance has been released) is pre-existing in other server-test suites and is harmless.
• The companion PR for APPSTASH_BASE_DIR env var support in appstash itself was merged and published as appstash@0.7.0 via dev-utils PR #75.

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 5 additional findings.