GQLServer: support programmatic schema imports (eliminate glob patterns)

[skilgoreT]

Summary

When extracting shared GQL schemas into standalone packages (e.g. @saga-ed/coach-gql-schema in Coach PR #34), consumers currently reference .gql files via filesystem glob patterns into node_modules:

GQL_SERVER_SCHEMAPATTERNS=node_modules/@saga-ed/coach-gql-schema/schemas/**/*.gql

This works but couples consumers to the internal directory structure of the schema package and to node_modules layout. Two changes in the SOA infrastructure would allow a cleaner contract.

Proposed Changes

1. Subpath exports for schema files

Schema packages should expose .gql files via the exports map using a subpath pattern:

// in the schema package's package.json
"exports": {
  ".":            { "import": "./dist/index.js",     "types": "./dist/index.d.ts" },
  "./schemas/*":  "./schemas/*"
}

This formalizes the contract — consumers reference @saga-ed/coach-gql-schema/schemas/cns.gql rather than reaching into node_modules internals.

2. GQLServer accepts typeDefs string/DocumentNode directly

Schema packages already produce a merged schema.graphql via codegen. If the package exports this as a typeDefs string:

// in the schema package's src/index.ts
import { readFileSync } from 'node:fs';
export const typeDefs = readFileSync(
  new URL('../generated/schema.graphql', import.meta.url),
  'utf-8'
);

Then consumers can do:

import { typeDefs } from '@saga-ed/coach-gql-schema';
// pass typeDefs directly to GQLServer — no glob needed

This eliminates GQL_SERVER_SCHEMAPATTERNS entirely for that consumer. GQLServer would need to accept a schema string (or DocumentNode) in addition to its current glob-based input.

Prototype Plan

Prototype both changes in the SOA gql-api example app before applying to Coach:

1. Add "./schemas/*" to the example schema package's exports map
2. Export the merged schema as a typeDefs string from the package entry point
3. Update GQLServer to accept typeDefs as an alternative to glob patterns
4. Validate the example app works with both approaches

Context

• Coach PR: saga-ed/coach#34 (shared GQL schema extraction)
• Review notes: claude/projects/gql-schema-refactor/research/pr-34-review.md

🤖 Generated with Claude Code