feat: add full file generation control and custom path system

[productdevbook]

🎯 Summary

Add comprehensive control over auto-generated files with custom path support. Perfect for library development, monorepos, and custom project structures.

✨ Features

1. Fine-Grained File Control

Control each generated file individually with three options:

• false - Don't generate
• true - Generate at default location
• string - Generate at custom path

2. Configuration Categories

• scaffold: graphql.config.ts, schema.ts, config.ts, context.ts
• clientUtils: index.ts, ofetch.ts (Nuxt only)
• sdk: Main and external service SDKs
• types: Server, client, and external service types
• paths: Global path overrides

3. Service-Specific Paths ⭐ NEW

Each external service can now define custom paths that override global config:

externalServices: [
  {
    name: 'github',
    paths: {
      sdk: 'app/graphql/organization/github-sdk.ts',
      types: 'types/github.d.ts',
      ofetch: 'app/graphql/organization/github-client.ts'
    }
  }
]

4. Path Placeholders

Support for dynamic placeholders in custom paths:

• {serviceName}, {buildDir}, {rootDir}, {framework}
• {typesDir}, {serverGraphql}, {clientGraphql}

5. Path Resolution Priority

1. Service-specific path
2. Category config
3. Global paths
4. Framework defaults

📝 Examples

Library Mode

graphql: {
  scaffold: false,        // No scaffolding
  clientUtils: false,     // No client utils
}

Custom Monorepo Structure

graphql: {
  paths: {
    serverGraphql: 'packages/api/src/graphql',
    clientGraphql: 'packages/web/src/graphql',
    typesDir: 'packages/types/src/generated',
  }
}

Service Organization

externalServices: [
  {
    name: 'github',
    paths: { sdk: 'app/graphql/vcs/github-sdk.ts' }
  },
  {
    name: 'stripe',
    paths: { sdk: 'app/graphql/billing/stripe-sdk.ts' }
  }
]

📦 Changes

New Files

• src/utils/path-resolver.ts - Path resolution and placeholder system (233 lines)
• src/utils/file-generator.ts - File generation utilities (103 lines)

Updated Files

• src/types/index.ts - New config types and interfaces (+125 lines)
• src/index.ts - Scaffold file generation with config control
• src/utils/type-generation.ts - SDK, types, client utils with config control
• README.md - Comprehensive documentation with examples (+240 lines)

Statistics

• 6 files changed
• 981 insertions(+)
• 58 deletions(-)

🧪 Test plan

• Library mode: Verify scaffold files not generated when scaffold: false
• Custom paths: Test custom path generation with placeholders
• Service-specific paths: Verify external services use custom paths
• Path resolution: Test priority system (service > category > global > default)
• Backward compatibility: Ensure existing configs still work
• Nuxt vs Nitro: Test both frameworks with new config
• Playgrounds: Test in playground environments

🔗 Related Issues

Closes #XX (if applicable)

🚀 Breaking Changes

None. This is fully backward compatible. All new config options are optional.

🤖 Generated with Claude Code