@constructive-io/graphql-codegen 4.7.3 → 4.8.1

package/esm/core/codegen/orm/docs-generator.js

@@ -1,4 +1,5 @@
-import { buildSkillFile, formatArgType, getEditableFields, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, } from '../docs-utils';
+import { toKebabCase } from 'komoji';
+import { buildSkillFile, buildSkillReference, formatArgType, getEditableFields, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, } from '../docs-utils';
 import { getScalarFields, getTableNames, getPrimaryKeyInfo, lcFirst, fieldTypeToTs, } from '../utils';
 export function generateOrmReadme(tables, customOperations) {
     const lines = [];
@@ -340,30 +341,36 @@ export function getOrmMcpTools(tables, customOperations) {
     }
     return tools;
 }
-export function generateOrmSkills(tables, customOperations) {
+export function generateOrmSkills(tables, customOperations, targetName) {
     const files = [];
+    const skillName = `orm-${targetName}`;
+    const referenceNames = [];
+    // Generate reference files for each table
     for (const table of tables) {
         const { singularName } = getTableNames(table);
         const pk = getPrimaryKeyInfo(table)[0];
         const editableFields = getEditableFields(table);
+        const modelName = lcFirst(singularName);
+        const refName = toKebabCase(singularName);
+        referenceNames.push(refName);
         files.push({
-            fileName: `skills/${lcFirst(singularName)}.md`,
-            content: buildSkillFile({
-                name: `orm-${lcFirst(singularName)}`,
+            fileName: `${skillName}/references/${refName}.md`,
+            content: buildSkillReference({
+                title: singularName,
                 description: table.description || `ORM operations for ${table.name} records`,
                 language: 'typescript',
                 usage: [
-                    `db.${lcFirst(singularName)}.findMany({ select: { id: true } }).execute()`,
-                    `db.${lcFirst(singularName)}.findOne({ ${pk.name}: '<value>', select: { id: true } }).execute()`,
-                    `db.${lcFirst(singularName)}.create({ data: { ${editableFields.map((f) => `${f.name}: '<value>'`).join(', ')} }, select: { id: true } }).execute()`,
-                    `db.${lcFirst(singularName)}.update({ where: { ${pk.name}: '<value>' }, data: { ${editableFields[0]?.name || 'field'}: '<new>' }, select: { id: true } }).execute()`,
-                    `db.${lcFirst(singularName)}.delete({ where: { ${pk.name}: '<value>' } }).execute()`,
+                    `db.${modelName}.findMany({ select: { id: true } }).execute()`,
+                    `db.${modelName}.findOne({ ${pk.name}: '<value>', select: { id: true } }).execute()`,
+                    `db.${modelName}.create({ data: { ${editableFields.map((f) => `${f.name}: '<value>'`).join(', ')} }, select: { id: true } }).execute()`,
+                    `db.${modelName}.update({ where: { ${pk.name}: '<value>' }, data: { ${editableFields[0]?.name || 'field'}: '<new>' }, select: { id: true } }).execute()`,
+                    `db.${modelName}.delete({ where: { ${pk.name}: '<value>' } }).execute()`,
                 ],
                 examples: [
                     {
                         description: `List all ${singularName} records`,
                         code: [
-                            `const items = await db.${lcFirst(singularName)}.findMany({`,
+                            `const items = await db.${modelName}.findMany({`,
                             `  select: { ${pk.name}: true, ${editableFields[0]?.name || 'name'}: true }`,
                             '}).execute();',
                         ],
@@ -371,7 +378,7 @@ export function generateOrmSkills(tables, customOperations) {
                     {
                         description: `Create a ${singularName}`,
                         code: [
-                            `const item = await db.${lcFirst(singularName)}.create({`,
+                            `const item = await db.${modelName}.create({`,
                             `  data: { ${editableFields.map((f) => `${f.name}: 'value'`).join(', ')} },`,
                             `  select: { ${pk.name}: true }`,
                             '}).execute();',
@@ -381,30 +388,60 @@ export function generateOrmSkills(tables, customOperations) {
             }),
         });
     }
+    // Generate reference files for custom operations
     for (const op of customOperations) {
         const accessor = op.kind === 'query' ? 'query' : 'mutation';
         const callArgs = op.args.length > 0
             ? `{ ${op.args.map((a) => `${a.name}: '<value>'`).join(', ')} }`
             : '';
+        const refName = toKebabCase(op.name);
+        referenceNames.push(refName);
         files.push({
-            fileName: `skills/${op.name}.md`,
-            content: buildSkillFile({
-                name: `orm-${op.name}`,
+            fileName: `${skillName}/references/${refName}.md`,
+            content: buildSkillReference({
+                title: op.name,
                 description: op.description || `Execute the ${op.name} ${op.kind}`,
                 language: 'typescript',
-                usage: [
-                    `db.${accessor}.${op.name}(${callArgs}).execute()`,
-                ],
+                usage: [`db.${accessor}.${op.name}(${callArgs}).execute()`],
                 examples: [
                     {
                         description: `Run ${op.name}`,
-                        code: [
-                            `const result = await db.${accessor}.${op.name}(${callArgs}).execute();`,
-                        ],
+                        code: [`const result = await db.${accessor}.${op.name}(${callArgs}).execute();`],
                     },
                 ],
             }),
         });
     }
+    // Generate the overview SKILL.md
+    const tableNames = tables.map((t) => lcFirst(getTableNames(t).singularName));
+    files.push({
+        fileName: `${skillName}/SKILL.md`,
+        content: buildSkillFile({
+            name: skillName,
+            description: `ORM client for the ${targetName} API — provides typed CRUD operations for ${tables.length} tables and ${customOperations.length} custom operations`,
+            language: 'typescript',
+            usage: [
+                `// Import the ORM client`,
+                `import { db } from './orm';`,
+                '',
+                `// Available models: ${tableNames.slice(0, 8).join(', ')}${tableNames.length > 8 ? ', ...' : ''}`,
+                `db.<model>.findMany({ select: { id: true } }).execute()`,
+                `db.<model>.findOne({ id: '<value>', select: { id: true } }).execute()`,
+                `db.<model>.create({ data: { ... }, select: { id: true } }).execute()`,
+                `db.<model>.update({ where: { id: '<value>' }, data: { ... }, select: { id: true } }).execute()`,
+                `db.<model>.delete({ where: { id: '<value>' } }).execute()`,
+            ],
+            examples: [
+                {
+                    description: 'Query records',
+                    code: [
+                        `const items = await db.${tableNames[0] || 'model'}.findMany({`,
+                        '  select: { id: true }',
+                        '}).execute();',
+                    ],
+                },
+            ],
+        }, referenceNames),
+    });
     return files;
 }

package/esm/core/generate.d.ts

@@ -33,6 +33,11 @@ export interface GenerateResult {
  */
 export interface GenerateInternalOptions {
     skipCli?: boolean;
+    /**
+     * Internal-only name for the target when generating skills.
+     * Used by generateMulti() so skill names are stable and composable.
+     */
+    targetName?: string;
 }
 export declare function generate(options?: GenerateOptions, internalOptions?: GenerateInternalOptions): Promise<GenerateResult>;
 export declare function expandApiNamesToMultiTarget(config: GraphQLSDKConfigTarget): Record<string, GraphQLSDKConfigTarget> | null;

package/esm/core/generate.js

@@ -24,6 +24,18 @@ import { generateTargetReadme, generateCombinedMcpConfig, generateRootRootReadme
 import { createSchemaSource, validateSourceOptions } from './introspect';
 import { writeGeneratedFiles } from './output';
 import { runCodegenPipeline, validateTablesFound } from './pipeline';
+import { findWorkspaceRoot } from './workspace';
+function resolveSkillsOutputDir(config, outputRoot) {
+    const workspaceRoot = findWorkspaceRoot(path.resolve(outputRoot)) ??
+        findWorkspaceRoot(process.cwd()) ??
+        process.cwd();
+    if (config.skillsPath) {
+        return path.isAbsolute(config.skillsPath)
+            ? config.skillsPath
+            : path.resolve(workspaceRoot, config.skillsPath);
+    }
+    return path.resolve(workspaceRoot, 'skills');
+}
 export async function generate(options = {}, internalOptions) {
     // Apply defaults to get resolved config
     const config = getConfigOptions(options);
@@ -219,6 +231,8 @@ export async function generate(options = {}, internalOptions) {
         ...(customOperations.mutations ?? []),
     ];
     const allMcpTools = [];
+    const targetName = internalOptions?.targetName ?? 'default';
+    const skillsToWrite = [];
     if (runOrm) {
         if (docsConfig.readme) {
             const readme = generateOrmReadme(tables, allCustomOps);
@@ -232,8 +246,8 @@ export async function generate(options = {}, internalOptions) {
             allMcpTools.push(...getOrmMcpTools(tables, allCustomOps));
         }
         if (docsConfig.skills) {
-            for (const skill of generateOrmSkills(tables, allCustomOps)) {
-                filesToWrite.push({ path: path.posix.join('orm', skill.fileName), content: skill.content });
+            for (const skill of generateOrmSkills(tables, allCustomOps, targetName)) {
+                skillsToWrite.push({ path: skill.fileName, content: skill.content });
             }
         }
     }
@@ -250,8 +264,8 @@ export async function generate(options = {}, internalOptions) {
             allMcpTools.push(...getHooksMcpTools(tables, allCustomOps));
         }
         if (docsConfig.skills) {
-            for (const skill of generateHooksSkills(tables, allCustomOps)) {
-                filesToWrite.push({ path: path.posix.join('hooks', skill.fileName), content: skill.content });
+            for (const skill of generateHooksSkills(tables, allCustomOps, targetName)) {
+                skillsToWrite.push({ path: skill.fileName, content: skill.content });
             }
         }
     }
@@ -271,8 +285,8 @@ export async function generate(options = {}, internalOptions) {
             allMcpTools.push(...getCliMcpTools(tables, allCustomOps, toolName));
         }
         if (docsConfig.skills) {
-            for (const skill of generateCliSkills(tables, allCustomOps, toolName)) {
-                filesToWrite.push({ path: path.posix.join('cli', skill.fileName), content: skill.content });
+            for (const skill of generateCliSkills(tables, allCustomOps, toolName, targetName)) {
+                skillsToWrite.push({ path: skill.fileName, content: skill.content });
             }
         }
     }
@@ -310,6 +324,21 @@ export async function generate(options = {}, internalOptions) {
             };
         }
         allFilesWritten.push(...(writeResult.filesWritten ?? []));
+        if (skillsToWrite.length > 0) {
+            const skillsOutputDir = resolveSkillsOutputDir(config, outputRoot);
+            const skillsWriteResult = await writeGeneratedFiles(skillsToWrite, skillsOutputDir, [], {
+                pruneStaleFiles: false,
+            });
+            if (!skillsWriteResult.success) {
+                return {
+                    success: false,
+                    message: `Failed to write generated skill files: ${skillsWriteResult.errors?.join(', ')}`,
+                    output: skillsOutputDir,
+                    errors: skillsWriteResult.errors,
+                };
+            }
+            allFilesWritten.push(...(skillsWriteResult.filesWritten ?? []));
+        }
     }
     const generators = [
         runReactQuery && 'React Query',
@@ -488,7 +517,7 @@ export async function generateMulti(options) {
                 dryRun,
                 schemaOnly,
                 schemaOnlyFilename: schemaOnly ? `${name}.graphql` : undefined,
-            }, useUnifiedCli ? { skipCli: true } : undefined);
+            }, useUnifiedCli ? { skipCli: true, targetName: name } : { targetName: name });
             results.push({ name, result });
             if (!result.success) {
                 hasError = true;
@@ -571,17 +600,24 @@ export async function generateMulti(options) {
             if (docsConfig.mcp) {
                 allMcpTools.push(...getMultiTargetCliMcpTools(docsInput));
             }
-            if (docsConfig.skills) {
-                for (const skill of generateMultiTargetSkills(docsInput)) {
-                    cliFilesToWrite.push({ path: path.posix.join('cli', skill.fileName), content: skill.content });
-                }
-            }
             if (docsConfig.mcp && allMcpTools.length > 0) {
                 const mcpFile = generateCombinedMcpConfig(allMcpTools, toolName);
                 cliFilesToWrite.push({ path: path.posix.join('cli', mcpFile.fileName), content: mcpFile.content });
             }
             const { writeGeneratedFiles: writeFiles } = await import('./output');
             await writeFiles(cliFilesToWrite, '.', [], { pruneStaleFiles: false });
+            if (docsConfig.skills) {
+                const cliSkillsToWrite = generateMultiTargetSkills(docsInput).map((skill) => ({
+                    path: skill.fileName,
+                    content: skill.content,
+                }));
+                const firstTargetResolved = getConfigOptions({
+                    ...(firstTargetConfig ?? {}),
+                    ...(cliOverrides ?? {}),
+                });
+                const skillsOutputDir = resolveSkillsOutputDir(firstTargetResolved, firstTargetResolved.output);
+                await writeFiles(cliSkillsToWrite, skillsOutputDir, [], { pruneStaleFiles: false });
+            }
         }
         // Generate root-root README if multi-target
         if (names.length > 1 && targetInfos.length > 0 && !dryRun) {

package/esm/core/workspace.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Find the workspace root directory.
+ *
+ * Search order:
+ * 1. pnpm-workspace.yaml (pnpm workspaces)
+ * 2. lerna.json (lerna workspaces)
+ * 3. package.json with "workspaces" field (npm/yarn workspaces)
+ * 4. Nearest package.json (fallback for non-workspace projects)
+ *
+ * @param cwd - Starting directory to search from (defaults to process.cwd())
+ * @returns The workspace root path, or null if nothing found
+ */
+export declare function findWorkspaceRoot(cwd?: string): string | null;

package/esm/core/workspace.js

@@ -0,0 +1,89 @@
+/**
+ * Workspace detection utilities
+ *
+ * Finds the root of a workspace by walking up directories looking for
+ * workspace markers (pnpm-workspace.yaml, lerna.json, package.json with workspaces).
+ * Falls back to the nearest package.json directory.
+ *
+ * Inspired by @pgpmjs/env walkUp / resolvePnpmWorkspace patterns.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve, parse as parsePath } from 'node:path';
+/**
+ * Walk up directories from startDir looking for a file.
+ * Returns the directory containing the file, or null if not found.
+ */
+function walkUp(startDir, filename) {
+    let currentDir = resolve(startDir);
+    while (currentDir) {
+        const targetPath = resolve(currentDir, filename);
+        if (existsSync(targetPath)) {
+            return currentDir;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    return null;
+}
+/**
+ * Find the first pnpm workspace root by looking for pnpm-workspace.yaml
+ */
+function findPnpmWorkspace(cwd) {
+    return walkUp(cwd, 'pnpm-workspace.yaml');
+}
+/**
+ * Find the first lerna workspace root by looking for lerna.json
+ */
+function findLernaWorkspace(cwd) {
+    return walkUp(cwd, 'lerna.json');
+}
+/**
+ * Find the first npm/yarn workspace root by looking for package.json with workspaces field
+ */
+function findNpmWorkspace(cwd) {
+    let currentDir = resolve(cwd);
+    const root = parsePath(currentDir).root;
+    while (currentDir !== root) {
+        const packageJsonPath = resolve(currentDir, 'package.json');
+        if (existsSync(packageJsonPath)) {
+            try {
+                const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+                if (packageJson.workspaces) {
+                    return currentDir;
+                }
+            }
+            catch {
+                // Ignore JSON parse errors
+            }
+        }
+        currentDir = dirname(currentDir);
+    }
+    return null;
+}
+/**
+ * Find the nearest package.json directory (fallback)
+ */
+function findPackageRoot(cwd) {
+    return walkUp(cwd, 'package.json');
+}
+/**
+ * Find the workspace root directory.
+ *
+ * Search order:
+ * 1. pnpm-workspace.yaml (pnpm workspaces)
+ * 2. lerna.json (lerna workspaces)
+ * 3. package.json with "workspaces" field (npm/yarn workspaces)
+ * 4. Nearest package.json (fallback for non-workspace projects)
+ *
+ * @param cwd - Starting directory to search from (defaults to process.cwd())
+ * @returns The workspace root path, or null if nothing found
+ */
+export function findWorkspaceRoot(cwd = process.cwd()) {
+    return (findPnpmWorkspace(cwd) ??
+        findLernaWorkspace(cwd) ??
+        findNpmWorkspace(cwd) ??
+        findPackageRoot(cwd));
+}

package/esm/types/config.d.ts

@@ -138,9 +138,9 @@ export interface DocsConfig {
      */
     mcp?: boolean;
     /**
-     * Generate skills/ directory — per-command .md skill files
-     * Each command gets its own skill file with description, usage, and examples
-     * Compatible with Devin and similar agent skill systems
+     * Generate skills/ directory — per-entity SKILL.md files with YAML frontmatter.
+     * Skills are written to the workspace root skills/ directory (not nested in output).
+     * Uses composable naming: orm-{target}-{entity}, hooks-{target}-{entity}, cli-{target}-{entity}.
      * @default false
      */
     skills?: boolean;
@@ -328,9 +328,17 @@ export interface GraphQLSDKConfigTarget {
      * Controls which doc formats are generated alongside code for each generator target.
      * Applied globally to all enabled generators (ORM, React Query, CLI).
      * Set to `true` to enable all formats, or configure individually.
-     * @default { readme: true, agents: true, mcp: false, skills: false }
+     * @default { readme: true, agents: true, mcp: false }
      */
     docs?: DocsConfig | boolean;
+    /**
+     * Custom path for generated skill files.
+     * When set, skills are written to this directory.
+     * When undefined (default), skills are written to {workspaceRoot}/skills/
+     * where workspaceRoot is auto-detected by walking up from the output directory
+     * looking for pnpm-workspace.yaml, lerna.json, or package.json with workspaces.
+     */
+    skillsPath?: string;
     /**
      * Query key generation configuration
      * Controls how query keys are structured for cache management

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-codegen",
-  "version": "4.7.3",
+  "version": "4.8.1",
   "description": "GraphQL SDK generator for Constructive databases with React Query hooks",
   "keywords": [
     "graphql",
@@ -54,28 +54,28 @@
   },
   "dependencies": {
     "@0no-co/graphql.web": "^1.1.2",
-    "@babel/generator": "^7.28.6",
-    "@babel/types": "^7.28.6",
-    "@constructive-io/graphql-query": "^3.3.3",
+    "@babel/generator": "^7.29.1",
+    "@babel/types": "^7.29.0",
+    "@constructive-io/graphql-query": "^3.3.4",
     "@constructive-io/graphql-types": "^3.1.2",
     "@inquirerer/utils": "^3.3.1",
-    "@pgpmjs/core": "^6.4.1",
-    "ajv": "^8.17.1",
+    "@pgpmjs/core": "^6.4.2",
+    "ajv": "^8.18.0",
     "deepmerge": "^4.3.1",
-    "find-and-require-package-json": "^0.9.0",
-    "gql-ast": "^3.1.0",
-    "graphile-schema": "^1.3.3",
-    "graphql": "^16.9.0",
-    "inflekt": "^0.3.1",
+    "find-and-require-package-json": "^0.9.1",
+    "gql-ast": "^3.1.1",
+    "graphile-schema": "^1.3.4",
+    "graphql": "^16.13.0",
+    "inflekt": "^0.3.3",
     "inquirerer": "^4.5.2",
     "jiti": "^2.6.1",
-    "komoji": "^0.8.0",
-    "oxfmt": "^0.26.0",
-    "pg-cache": "^3.1.0",
+    "komoji": "^0.8.1",
+    "oxfmt": "^0.36.0",
+    "pg-cache": "^3.1.1",
     "pg-env": "^1.5.0",
-    "pgsql-client": "^3.3.1",
-    "pgsql-seed": "^2.3.1",
-    "undici": "^7.19.0"
+    "pgsql-client": "^3.3.2",
+    "pgsql-seed": "^2.3.2",
+    "undici": "^7.22.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0",
@@ -90,16 +90,16 @@
     }
   },
   "devDependencies": {
-    "@tanstack/react-query": "^5.90.19",
+    "@tanstack/react-query": "^5.90.21",
     "@types/babel__generator": "^7.27.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^20.19.27",
-    "@types/react": "^19.2.8",
+    "@types/node": "^22.19.11",
+    "@types/react": "^19.2.14",
     "jest": "^30.2.0",
-    "react": "^19.2.3",
+    "react": "^19.2.4",
     "ts-jest": "^29.2.5",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
-  "gitHead": "16e3a687cf1d629d1eff1a9146e71bec14796196"
+  "gitHead": "f4176b73429bffca0aec8dc89abe9835bf40e5c6"
 }

package/types/config.d.ts

@@ -138,9 +138,9 @@ export interface DocsConfig {
      */
     mcp?: boolean;
     /**
-     * Generate skills/ directory — per-command .md skill files
-     * Each command gets its own skill file with description, usage, and examples
-     * Compatible with Devin and similar agent skill systems
+     * Generate skills/ directory — per-entity SKILL.md files with YAML frontmatter.
+     * Skills are written to the workspace root skills/ directory (not nested in output).
+     * Uses composable naming: orm-{target}-{entity}, hooks-{target}-{entity}, cli-{target}-{entity}.
      * @default false
      */
     skills?: boolean;
@@ -328,9 +328,17 @@ export interface GraphQLSDKConfigTarget {
      * Controls which doc formats are generated alongside code for each generator target.
      * Applied globally to all enabled generators (ORM, React Query, CLI).
      * Set to `true` to enable all formats, or configure individually.
-     * @default { readme: true, agents: true, mcp: false, skills: false }
+     * @default { readme: true, agents: true, mcp: false }
      */
     docs?: DocsConfig | boolean;
+    /**
+     * Custom path for generated skill files.
+     * When set, skills are written to this directory.
+     * When undefined (default), skills are written to {workspaceRoot}/skills/
+     * where workspaceRoot is auto-detected by walking up from the output directory
+     * looking for pnpm-workspace.yaml, lerna.json, or package.json with workspaces.
+     */
+    skillsPath?: string;
     /**
      * Query key generation configuration
      * Controls how query keys are structured for cache management