@constructive-io/graphql-codegen 4.7.3 → 4.8.1

package/core/codegen/cli/infra-generator.js

@@ -135,7 +135,7 @@ Create Options:
                 ]))),
             ]),
             t.returnStatement(t.callExpression(t.identifier('handleSubcommand'), [
-                t.memberExpression(t.identifier('answer'), t.identifier('subcommand')),
+                t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('subcommand')), t.tsStringKeyword()),
                 t.identifier('newArgv'),
                 t.identifier('prompter'),
                 t.identifier('store'),
@@ -224,7 +224,7 @@ function buildCreateHandler() {
             ])),
         ]),
         t.variableDeclaration('const', [
-            t.variableDeclarator(t.identifier('answers'), t.awaitExpression(t.callExpression(t.memberExpression(t.identifier('prompter'), t.identifier('prompt')), [
+            t.variableDeclarator(t.identifier('answers'), t.tsAsExpression(t.tsAsExpression(t.awaitExpression(t.callExpression(t.memberExpression(t.identifier('prompter'), t.identifier('prompt')), [
                 t.objectExpression([
                     t.objectProperty(t.identifier('name'), t.identifier('name'), false, true),
                     t.spreadElement(t.identifier('restArgv')),
@@ -243,7 +243,10 @@ function buildCreateHandler() {
                         t.objectProperty(t.identifier('required'), t.booleanLiteral(true)),
                     ]),
                 ]),
-            ]))),
+            ])), t.tsUnknownKeyword()), t.tsTypeReference(t.identifier('Record'), t.tsTypeParameterInstantiation([
+                t.tsStringKeyword(),
+                t.tsStringKeyword(),
+            ])))),
         ]),
         t.variableDeclaration('const', [
             t.variableDeclarator(t.identifier('contextName'), t.memberExpression(t.identifier('answers'), t.identifier('name'))),
@@ -380,7 +383,7 @@ function buildUseHandler() {
                     ]),
                 ]))),
             ]),
-            t.expressionStatement(t.assignmentExpression('=', t.identifier('contextName'), t.memberExpression(t.identifier('answer'), t.identifier('name')))),
+            t.expressionStatement(t.assignmentExpression('=', t.identifier('contextName'), t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('name')), t.tsStringKeyword()))),
         ])),
         t.ifStatement(t.callExpression(t.memberExpression(t.identifier('store'), t.identifier('setCurrentContext')), [t.identifier('contextName')]), t.blockStatement([
             t.expressionStatement(t.callExpression(t.memberExpression(t.identifier('console'), t.identifier('log')), [
@@ -496,7 +499,7 @@ function buildDeleteHandler() {
                     ]),
                 ]))),
             ]),
-            t.expressionStatement(t.assignmentExpression('=', t.identifier('contextName'), t.memberExpression(t.identifier('answer'), t.identifier('name')))),
+            t.expressionStatement(t.assignmentExpression('=', t.identifier('contextName'), t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('name')), t.tsStringKeyword()))),
         ])),
         t.ifStatement(t.callExpression(t.memberExpression(t.identifier('store'), t.identifier('deleteContext')), [t.identifier('contextName')]), t.blockStatement([
             t.expressionStatement(t.callExpression(t.memberExpression(t.identifier('console'), t.identifier('log')), [
@@ -588,7 +591,7 @@ Options:
                 ]))),
             ]),
             t.returnStatement(t.callExpression(t.identifier('handleAuthSubcommand'), [
-                t.memberExpression(t.identifier('answer'), t.identifier('subcommand')),
+                t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('subcommand')), t.tsStringKeyword()),
                 t.identifier('newArgv'),
                 t.identifier('prompter'),
                 t.identifier('store'),
@@ -690,7 +693,7 @@ function buildSetTokenHandler() {
                     ]),
                 ]))),
             ]),
-            t.expressionStatement(t.assignmentExpression('=', t.identifier('tokenValue'), t.memberExpression(t.identifier('answer'), t.identifier('token')))),
+            t.expressionStatement(t.assignmentExpression('=', t.identifier('tokenValue'), t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('token')), t.tsStringKeyword()))),
         ])),
         t.expressionStatement(t.callExpression(t.memberExpression(t.identifier('store'), t.identifier('setCredentials')), [
             t.memberExpression(t.identifier('current'), t.identifier('name')),
@@ -809,7 +812,7 @@ function buildLogoutHandler() {
                 ]),
             ]))),
         ]),
-        t.ifStatement(t.unaryExpression('!', t.memberExpression(t.identifier('confirm'), t.identifier('confirm'))), t.blockStatement([t.returnStatement()])),
+        t.ifStatement(t.unaryExpression('!', t.tsAsExpression(t.memberExpression(t.identifier('confirm'), t.identifier('confirm')), t.tsBooleanKeyword())), t.blockStatement([t.returnStatement()])),
         t.ifStatement(t.callExpression(t.memberExpression(t.identifier('store'), t.identifier('removeCredentials')), [
             t.memberExpression(t.identifier('current'), t.identifier('name')),
         ]), t.blockStatement([
@@ -909,7 +912,7 @@ ${targets.map((tgt) => `  --${tgt.name}-endpoint <url>  ${tgt.name} endpoint (de
                 ]))),
             ]),
             t.returnStatement(t.callExpression(t.identifier('handleSubcommand'), [
-                t.memberExpression(t.identifier('answer'), t.identifier('subcommand')),
+                t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('subcommand')), t.tsStringKeyword()),
                 t.identifier('newArgv'),
                 t.identifier('prompter'),
                 t.identifier('store'),
@@ -1008,7 +1011,7 @@ function buildMultiTargetCreateHandler(targets) {
     const targetsObjProps = targets.map((target) => {
         const fieldName = `${target.name}Endpoint`;
         return t.objectProperty(t.stringLiteral(target.name), t.objectExpression([
-            t.objectProperty(t.identifier('endpoint'), t.memberExpression(t.identifier('answers'), t.identifier(fieldName))),
+            t.objectProperty(t.identifier('endpoint'), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(fieldName)), t.tsStringKeyword())),
         ]));
     });
     const body = [
@@ -1030,7 +1033,7 @@ function buildMultiTargetCreateHandler(targets) {
             ]))),
         ]),
         t.variableDeclaration('const', [
-            t.variableDeclarator(t.identifier('contextName'), t.memberExpression(t.identifier('answers'), t.identifier('name'))),
+            t.variableDeclarator(t.identifier('contextName'), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier('name')), t.tsStringKeyword())),
         ]),
         t.variableDeclaration('const', [
             t.variableDeclarator(t.identifier('targets'), t.objectExpression(targetsObjProps)),
@@ -1038,7 +1041,7 @@ function buildMultiTargetCreateHandler(targets) {
         t.expressionStatement(t.callExpression(t.memberExpression(t.identifier('store'), t.identifier('createContext')), [
             t.identifier('contextName'),
             t.objectExpression([
-                t.objectProperty(t.identifier('endpoint'), t.memberExpression(t.identifier('answers'), t.identifier(`${targets[0].name}Endpoint`))),
+                t.objectProperty(t.identifier('endpoint'), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(`${targets[0].name}Endpoint`)), t.tsStringKeyword())),
                 t.objectProperty(t.identifier('targets'), t.identifier('targets')),
             ]),
         ])),
@@ -1061,7 +1064,7 @@ function buildMultiTargetCreateHandler(targets) {
             t.templateLiteral([
                 t.templateElement({ raw: `  ${target.name}: `, cooked: `  ${target.name}: ` }),
                 t.templateElement({ raw: '', cooked: '' }, true),
-            ], [t.memberExpression(t.identifier('answers'), t.identifier(fieldName))]),
+            ], [t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(fieldName)), t.tsStringKeyword())]),
         ])));
     }
     const func = t.functionDeclaration(t.identifier('handleCreate'), [argvParam, prompterParam, storeParam], t.blockStatement(body), false, true);
@@ -1137,7 +1140,7 @@ Options:
                 ]))),
             ]),
             t.returnStatement(t.callExpression(t.identifier('handleAuthSubcommand'), [
-                t.memberExpression(t.identifier('answer'), t.identifier('subcommand')),
+                t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('subcommand')), t.tsStringKeyword()),
                 t.identifier('newArgv'),
                 t.identifier('prompter'),
                 t.identifier('store'),

package/core/codegen/cli/table-command-generator.js

@@ -38,7 +38,6 @@ const t = __importStar(require("@babel/types"));
 const komoji_1 = require("komoji");
 const babel_ast_1 = require("../babel-ast");
 const utils_1 = require("../utils");
-const utils_2 = require("../utils");
 function createImportDeclaration(moduleSpecifier, namedImports, typeOnly = false) {
     const specifiers = namedImports.map((name) => t.importSpecifier(t.identifier(name), t.identifier(name)));
     const decl = t.importDeclaration(specifiers, t.stringLiteral(moduleSpecifier));
@@ -50,6 +49,60 @@ function createImportDeclaration(moduleSpecifier, namedImports, typeOnly = false
  * This is used at runtime for type coercion (string CLI args → proper types).
  * e.g., { name: 'string', isActive: 'boolean', position: 'int', status: 'enum' }
  */
+/**
+ * Returns a t.TSType node for the appropriate TypeScript type assertion
+ * based on a field's GraphQL type. Used to cast `cleanedData.fieldName`
+ * to the correct type expected by the ORM.
+ */
+/**
+ * Known GraphQL scalar types. Anything not in this set is an enum or custom type.
+ */
+const KNOWN_SCALARS = new Set([
+    'String', 'Boolean', 'Int', 'BigInt', 'Float', 'UUID',
+    'JSON', 'GeoJSON', 'Datetime', 'Date', 'Time', 'Cursor',
+    'BigFloat', 'Interval',
+]);
+/**
+ * Returns true if the GraphQL type is a known scalar.
+ * Non-scalar types (enums, custom input types) need different handling.
+ */
+function isKnownScalar(gqlType) {
+    return KNOWN_SCALARS.has(gqlType.replace(/!/g, ''));
+}
+function getTsTypeForField(field) {
+    const gqlType = field.type.gqlType.replace(/!/g, '');
+    // For non-scalar types (enums, custom types), return null to signal
+    // that no type assertion should be emitted — the value will be passed
+    // without casting, which avoids "string is not assignable to EnumType" errors.
+    if (!isKnownScalar(gqlType)) {
+        return null;
+    }
+    // Determine the base scalar type
+    // Note: ORM input types flatten array fields to their scalar base type
+    // (e.g., _uuid[] in PG -> string in the ORM input), so we do NOT wrap
+    // in tsArrayType here.
+    switch (gqlType) {
+        case 'Boolean':
+            return t.tsBooleanKeyword();
+        case 'Int':
+        case 'BigInt':
+        case 'Float':
+        case 'BigFloat':
+            return t.tsNumberKeyword();
+        case 'JSON':
+        case 'GeoJSON':
+            return t.tsTypeReference(t.identifier('Record'), t.tsTypeParameterInstantiation([
+                t.tsStringKeyword(),
+                t.tsUnknownKeyword(),
+            ]));
+        case 'Interval':
+            // IntervalInput is a complex type, skip assertion
+            return null;
+        case 'UUID':
+        default:
+            return t.tsStringKeyword();
+    }
+}
 function buildFieldSchemaObject(table) {
     const fields = (0, utils_1.getScalarFields)(table);
     return t.objectExpression(fields.map((f) => {
@@ -162,8 +215,11 @@ function buildGetHandler(table, targetName) {
         t.objectProperty(t.identifier('message'), t.stringLiteral(pk.name)),
         t.objectProperty(t.identifier('required'), t.booleanLiteral(true)),
     ]);
+    const pkTsType = pk.gqlType === 'Int' || pk.gqlType === 'BigInt'
+        ? t.tsNumberKeyword()
+        : t.tsStringKeyword();
     const ormArgs = t.objectExpression([
-        t.objectProperty(t.identifier(pk.name), t.memberExpression(t.identifier('answers'), t.identifier(pk.name))),
+        t.objectProperty(t.identifier(pk.name), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(pk.name)), pkTsType)),
         t.objectProperty(t.identifier('select'), selectObj),
     ]);
     const tryBody = [
@@ -189,19 +245,16 @@ function buildGetHandler(table, targetName) {
  * Looks up the CreateXInput -> inner input type (e.g. DatabaseInput) in the
  * TypeRegistry and checks each field's defaultValue from introspection.
  */
-function getFieldsWithDefaults(table, typeRegistry) {
-    const fieldsWithDefaults = new Set();
-    if (!typeRegistry)
-        return fieldsWithDefaults;
-    // Look up the CreateXInput type (e.g. CreateDatabaseInput)
-    const createInputTypeName = (0, utils_2.getCreateInputTypeName)(table);
-    const createInputType = typeRegistry.get(createInputTypeName);
-    if (!createInputType?.inputFields)
-        return fieldsWithDefaults;
-    // The CreateXInput has an inner field (e.g. "database" of type DatabaseInput)
-    // Find the inner input type that contains the actual field definitions
-    for (const inputField of createInputType.inputFields) {
-        // The inner field's type name is the actual input type (e.g. DatabaseInput)
+/**
+ * Resolve the inner input type from a CreateXInput or UpdateXInput type.
+ * The CreateXInput has an inner field (e.g. "database" of type DatabaseInput)
+ * that contains the actual field definitions.
+ */
+function resolveInnerInputType(inputTypeName, typeRegistry) {
+    const inputType = typeRegistry.get(inputTypeName);
+    if (!inputType?.inputFields)
+        return null;
+    for (const inputField of inputType.inputFields) {
         const innerTypeName = inputField.type.name
             || inputField.type.ofType?.name
             || inputField.type.ofType?.ofType?.name;
@@ -210,29 +263,70 @@ function getFieldsWithDefaults(table, typeRegistry) {
         const innerType = typeRegistry.get(innerTypeName);
         if (!innerType?.inputFields)
             continue;
-        // Check each field in the inner input type for defaultValue
-        for (const field of innerType.inputFields) {
-            if (field.defaultValue !== undefined) {
-                fieldsWithDefaults.add(field.name);
-            }
-            // Also check if the field is NOT wrapped in NON_NULL (nullable = has default or is optional)
-            if (field.type.kind !== 'NON_NULL') {
-                fieldsWithDefaults.add(field.name);
-            }
+        const fields = new Set(innerType.inputFields.map((f) => f.name));
+        return { name: innerTypeName, fields };
+    }
+    return null;
+}
+function getFieldsWithDefaults(table, typeRegistry) {
+    const fieldsWithDefaults = new Set();
+    if (!typeRegistry)
+        return fieldsWithDefaults;
+    const createInputTypeName = (0, utils_1.getCreateInputTypeName)(table);
+    const resolved = resolveInnerInputType(createInputTypeName, typeRegistry);
+    if (!resolved)
+        return fieldsWithDefaults;
+    const innerType = typeRegistry.get(resolved.name);
+    if (!innerType?.inputFields)
+        return fieldsWithDefaults;
+    for (const field of innerType.inputFields) {
+        if (field.defaultValue !== undefined) {
+            fieldsWithDefaults.add(field.name);
+        }
+        if (field.type.kind !== 'NON_NULL') {
+            fieldsWithDefaults.add(field.name);
         }
     }
     return fieldsWithDefaults;
 }
-function buildMutationHandler(table, operation, targetName, typeRegistry) {
+/**
+ * Get the set of field names that actually exist in the create/update input type.
+ * Fields not in this set (e.g. computed fields like searchTsvRank, hashUuid)
+ * should be excluded from the data object in create/update handlers.
+ */
+function getWritableFieldNames(table, typeRegistry) {
+    if (!typeRegistry)
+        return null;
+    const createInputTypeName = (0, utils_1.getCreateInputTypeName)(table);
+    const resolved = resolveInnerInputType(createInputTypeName, typeRegistry);
+    return resolved?.fields ?? null;
+}
+function buildMutationHandler(table, operation, targetName, typeRegistry, ormTypes) {
     const { singularName } = (0, utils_1.getTableNames)(table);
     const pkFields = (0, utils_1.getPrimaryKeyInfo)(table);
     const pk = pkFields[0];
-    const editableFields = (0, utils_1.getScalarFields)(table).filter((f) => f.name !== pk.name &&
-        f.name !== 'nodeId' &&
-        f.name !== 'createdAt' &&
-        f.name !== 'updatedAt');
+    // Get the set of writable field names from the type registry
+    // This filters out computed fields (e.g. searchTsvRank, hashUuid) that exist
+    // on the entity type but not on the create/update input type.
+    const writableFields = getWritableFieldNames(table, typeRegistry);
     // Get fields that have defaults from introspection (for create operations)
     const fieldsWithDefaults = getFieldsWithDefaults(table, typeRegistry);
+    // For create: include fields that are in the create input type.
+    // For update/delete: always exclude the PK (it goes in `where`, not `data`).
+    // The ORM input-types generator always excludes these fields from create inputs
+    // (see EXCLUDED_MUTATION_FIELDS in input-types-generator.ts). We must match this
+    // to avoid generating data properties that don't exist on the ORM create type.
+    // For non-'id' PKs (e.g. NodeTypeRegistry.name), we allow them in create data
+    // since they are user-provided natural keys that DO appear in the create input.
+    const ORM_EXCLUDED_FIELDS = ['id', 'createdAt', 'updatedAt', 'nodeId'];
+    const editableFields = (0, utils_1.getScalarFields)(table).filter((f) => 
+    // For update/delete: always exclude PK (it goes in `where`, not `data`)
+    // For create: exclude PK only if it's in the ORM exclusion list (e.g. 'id')
+    (f.name !== pk.name || (operation === 'create' && !ORM_EXCLUDED_FIELDS.includes(pk.name))) &&
+        // Always exclude ORM-excluded fields (except PK which is handled above)
+        (f.name === pk.name || !ORM_EXCLUDED_FIELDS.includes(f.name)) &&
+        // If we have type registry info, only include fields that exist in the input type
+        (writableFields === null || writableFields.has(f.name)));
     const questions = [];
     if (operation === 'update' || operation === 'delete') {
         questions.push(t.objectExpression([
@@ -261,27 +355,36 @@ function buildMutationHandler(table, operation, targetName, typeRegistry) {
         ])
         : buildSelectObject(table);
     let ormArgs;
+    // Build data properties without individual type assertions.
+    // Instead, we build a plain object from cleanedData and cast the entire
+    // data value through `unknown` to bridge the type gap between
+    // Record<string, unknown> and the ORM's specific input type.
+    // This handles scalars, enums (string literal unions like ObjectCategory),
+    // and array fields uniformly without needing to import each type.
+    const buildDataProps = () => editableFields.map((f) => t.objectProperty(t.identifier(f.name), t.memberExpression(t.identifier('cleanedData'), t.identifier(f.name))));
     if (operation === 'create') {
-        const dataProps = editableFields.map((f) => t.objectProperty(t.identifier(f.name), t.memberExpression(t.identifier('cleanedData'), t.identifier(f.name)), false, true));
         ormArgs = t.objectExpression([
-            t.objectProperty(t.identifier('data'), t.objectExpression(dataProps)),
+            t.objectProperty(t.identifier('data'), t.objectExpression(buildDataProps())),
             t.objectProperty(t.identifier('select'), selectObj),
         ]);
     }
     else if (operation === 'update') {
-        const dataProps = editableFields.map((f) => t.objectProperty(t.identifier(f.name), t.memberExpression(t.identifier('cleanedData'), t.identifier(f.name)), false, true));
         ormArgs = t.objectExpression([
             t.objectProperty(t.identifier('where'), t.objectExpression([
-                t.objectProperty(t.identifier(pk.name), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(pk.name)), t.tsStringKeyword())),
+                t.objectProperty(t.identifier(pk.name), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(pk.name)), pk.gqlType === 'Int' || pk.gqlType === 'BigInt'
+                    ? t.tsNumberKeyword()
+                    : t.tsStringKeyword())),
             ])),
-            t.objectProperty(t.identifier('data'), t.objectExpression(dataProps)),
+            t.objectProperty(t.identifier('data'), t.objectExpression(buildDataProps())),
             t.objectProperty(t.identifier('select'), selectObj),
         ]);
     }
     else {
         ormArgs = t.objectExpression([
             t.objectProperty(t.identifier('where'), t.objectExpression([
-                t.objectProperty(t.identifier(pk.name), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(pk.name)), t.tsStringKeyword())),
+                t.objectProperty(t.identifier(pk.name), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(pk.name)), pk.gqlType === 'Int' || pk.gqlType === 'BigInt'
+                    ? t.tsNumberKeyword()
+                    : t.tsStringKeyword())),
             ])),
             t.objectProperty(t.identifier('select'), selectObj),
         ]);
@@ -298,11 +401,25 @@ function buildMutationHandler(table, operation, targetName, typeRegistry) {
         ]),
     ];
     if (operation !== 'delete') {
+        // Build stripUndefined call and cast to the proper ORM input type
+        // so that property accesses on cleanedData are correctly typed.
+        const stripUndefinedCall = t.callExpression(t.identifier('stripUndefined'), [
+            t.identifier('answers'),
+            t.identifier('fieldSchema'),
+        ]);
+        let cleanedDataExpr = stripUndefinedCall;
+        if (ormTypes) {
+            if (operation === 'create') {
+                // cleanedData as CreateXxxInput['fieldName']
+                cleanedDataExpr = t.tsAsExpression(stripUndefinedCall, t.tsIndexedAccessType(t.tsTypeReference(t.identifier(ormTypes.createInputTypeName)), t.tsLiteralType(t.stringLiteral(ormTypes.innerFieldName))));
+            }
+            else if (operation === 'update') {
+                // cleanedData as XxxPatch
+                cleanedDataExpr = t.tsAsExpression(stripUndefinedCall, t.tsTypeReference(t.identifier(ormTypes.patchTypeName)));
+            }
+        }
         tryBody.push(t.variableDeclaration('const', [
-            t.variableDeclarator(t.identifier('cleanedData'), t.callExpression(t.identifier('stripUndefined'), [
-                t.identifier('answers'),
-                t.identifier('fieldSchema'),
-            ])),
+            t.variableDeclarator(t.identifier('cleanedData'), cleanedDataExpr),
         ]));
     }
     tryBody.push(buildGetClientStatement(targetName), t.variableDeclaration('const', [
@@ -330,25 +447,60 @@ function generateTableCommand(table, options) {
     statements.push(createImportDeclaration(executorPath, ['getClient']));
     const utilsPath = options?.targetName ? '../../utils' : '../utils';
     statements.push(createImportDeclaration(utilsPath, ['coerceAnswers', 'stripUndefined']));
+    statements.push(createImportDeclaration(utilsPath, ['FieldSchema'], true));
+    // Import ORM input types for proper type assertions in mutation handlers.
+    // These types ensure that cleanedData is cast to the correct ORM input type
+    // (e.g., CreateAppPermissionInput['appPermission'] for create, AppPermissionPatch for update)
+    // instead of remaining as Record<string, unknown>.
+    const createInputTypeName = (0, utils_1.getCreateInputTypeName)(table);
+    const patchTypeName = (0, utils_1.getPatchTypeName)(table);
+    const innerFieldName = (0, utils_1.lcFirst)(table.name);
+    // Commands are at cli/commands/xxx.ts (no target) or cli/commands/{target}/xxx.ts (with target).
+    // ORM input-types is at orm/input-types.ts — two or three levels up from commands.
+    const inputTypesPath = options?.targetName
+        ? `../../../orm/input-types`
+        : `../../orm/input-types`;
+    statements.push(createImportDeclaration(inputTypesPath, [createInputTypeName, patchTypeName], true));
     // Generate field schema for type coercion
+    // Use explicit FieldSchema type annotation so TS narrows string literals to FieldType
+    const fieldSchemaId = t.identifier('fieldSchema');
+    fieldSchemaId.typeAnnotation = t.tsTypeAnnotation(t.tsTypeReference(t.identifier('FieldSchema')));
     statements.push(t.variableDeclaration('const', [
-        t.variableDeclarator(t.identifier('fieldSchema'), buildFieldSchemaObject(table)),
+        t.variableDeclarator(fieldSchemaId, buildFieldSchemaObject(table)),
     ]));
-    const subcommands = ['list', 'get', 'create', 'update', 'delete'];
+    // Determine which operations the ORM model supports for this table.
+    // Most tables have `one: null` simply because there's no dedicated GraphQL
+    // findOne query, but the ORM still generates `findOne` using the PK.
+    // The only tables WITHOUT `findOne` are pure record types from SQL functions
+    // (e.g. GetAllRecord, OrgGetManagersRecord) which have no update/delete either.
+    // We detect these by checking: if one, update, AND delete are all null, it's a
+    // read-only record type with no `findOne`.
+    const hasUpdate = table.query?.update !== undefined && table.query?.update !== null;
+    const hasDelete = table.query?.delete !== undefined && table.query?.delete !== null;
+    const hasGet = table.query?.one !== null || hasUpdate || hasDelete;
+    const subcommands = ['list'];
+    if (hasGet)
+        subcommands.push('get');
+    subcommands.push('create');
+    if (hasUpdate)
+        subcommands.push('update');
+    if (hasDelete)
+        subcommands.push('delete');
     const usageLines = [
         '',
         `${commandName} <command>`,
         '',
         'Commands:',
         `  list                  List all ${singularName} records`,
-        `  get                   Get a ${singularName} by ID`,
-        `  create                Create a new ${singularName}`,
-        `  update                Update an existing ${singularName}`,
-        `  delete                Delete a ${singularName}`,
-        '',
-        '  --help, -h            Show this help message',
-        '',
     ];
+    if (hasGet)
+        usageLines.push(`  get                   Get a ${singularName} by ID`);
+    usageLines.push(`  create                Create a new ${singularName}`);
+    if (hasUpdate)
+        usageLines.push(`  update                Update an existing ${singularName}`);
+    if (hasDelete)
+        usageLines.push(`  delete                Delete a ${singularName}`);
+    usageLines.push('', '  --help, -h            Show this help message', '');
     statements.push(t.variableDeclaration('const', [
         t.variableDeclarator(t.identifier('usage'), t.stringLiteral(usageLines.join('\n'))),
     ]));
@@ -386,7 +538,7 @@ function generateTableCommand(table, options) {
                 ]))),
             ]),
             t.returnStatement(t.callExpression(t.identifier('handleTableSubcommand'), [
-                t.memberExpression(t.identifier('answer'), t.identifier('subcommand')),
+                t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('subcommand')), t.tsStringKeyword()),
                 t.identifier('newArgv'),
                 t.identifier('prompter'),
             ])),
@@ -408,11 +560,15 @@ function generateTableCommand(table, options) {
         buildSubcommandSwitch(subcommands, 'handle', 'usage'),
     ]), false, true));
     const tn = options?.targetName;
+    const ormTypes = { createInputTypeName, patchTypeName, innerFieldName };
     statements.push(buildListHandler(table, tn));
-    statements.push(buildGetHandler(table, tn));
-    statements.push(buildMutationHandler(table, 'create', tn, options?.typeRegistry));
-    statements.push(buildMutationHandler(table, 'update', tn, options?.typeRegistry));
-    statements.push(buildMutationHandler(table, 'delete', tn, options?.typeRegistry));
+    if (hasGet)
+        statements.push(buildGetHandler(table, tn));
+    statements.push(buildMutationHandler(table, 'create', tn, options?.typeRegistry, ormTypes));
+    if (hasUpdate)
+        statements.push(buildMutationHandler(table, 'update', tn, options?.typeRegistry, ormTypes));
+    if (hasDelete)
+        statements.push(buildMutationHandler(table, 'delete', tn, options?.typeRegistry, ormTypes));
     const header = (0, utils_1.getGeneratedFileHeader)(`CLI commands for ${table.name}`);
     const code = (0, babel_ast_1.generateCode)(statements);
     return {

package/core/codegen/docs-utils.d.ts

@@ -20,6 +20,16 @@ export interface SkillDefinition {
     }[];
     language?: string;
 }
+export interface SkillReferenceDefinition {
+    title: string;
+    description: string;
+    usage: string[];
+    examples: {
+        description: string;
+        code: string[];
+    }[];
+    language?: string;
+}
 export declare function getReadmeHeader(title: string): string[];
 export declare function getReadmeFooter(): string[];
 export declare function resolveDocsConfig(docs: DocsConfig | boolean | undefined): DocsConfig;
@@ -27,4 +37,5 @@ export declare function formatArgType(arg: CleanOperation['args'][number]): stri
 export declare function formatTypeRef(t: CleanOperation['args'][number]['type']): string;
 export declare function getEditableFields(table: CleanTable): CleanField[];
 export declare function gqlTypeToJsonSchemaType(gqlType: string): string;
-export declare function buildSkillFile(skill: SkillDefinition): string;
+export declare function buildSkillFile(skill: SkillDefinition, referenceNames?: string[]): string;
+export declare function buildSkillReference(ref: SkillReferenceDefinition): string;

package/core/codegen/docs-utils.js

@@ -8,6 +8,7 @@ exports.formatTypeRef = formatTypeRef;
 exports.getEditableFields = getEditableFields;
 exports.gqlTypeToJsonSchemaType = gqlTypeToJsonSchemaType;
 exports.buildSkillFile = buildSkillFile;
+exports.buildSkillReference = buildSkillReference;
 const utils_1 = require("./utils");
 const CONSTRUCTIVE_LOGO_URL = 'https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg';
 const CONSTRUCTIVE_REPO = 'https://github.com/constructive-io/constructive';
@@ -89,9 +90,15 @@ function gqlTypeToJsonSchemaType(gqlType) {
             return 'string';
     }
 }
-function buildSkillFile(skill) {
+function buildSkillFile(skill, referenceNames) {
     const lang = skill.language ?? 'bash';
     const lines = [];
+    // YAML frontmatter (Agent Skills format)
+    lines.push('---');
+    lines.push(`name: ${skill.name}`);
+    lines.push(`description: ${skill.description}`);
+    lines.push('---');
+    lines.push('');
     lines.push(`# ${skill.name}`);
     lines.push('');
     lines.push('<!-- @constructive-io/graphql-codegen - DO NOT EDIT -->');
@@ -118,5 +125,46 @@ function buildSkillFile(skill) {
         lines.push('```');
         lines.push('');
     }
+    if (referenceNames && referenceNames.length > 0) {
+        lines.push('## References');
+        lines.push('');
+        lines.push('See the `references/` directory for detailed per-entity API documentation:');
+        lines.push('');
+        for (const name of referenceNames) {
+            lines.push(`- [${name}](references/${name}.md)`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function buildSkillReference(ref) {
+    const lang = ref.language ?? 'bash';
+    const lines = [];
+    lines.push(`# ${ref.title}`);
+    lines.push('');
+    lines.push('<!-- @constructive-io/graphql-codegen - DO NOT EDIT -->');
+    lines.push('');
+    lines.push(ref.description);
+    lines.push('');
+    lines.push('## Usage');
+    lines.push('');
+    lines.push(`\`\`\`${lang}`);
+    for (const u of ref.usage) {
+        lines.push(u);
+    }
+    lines.push('```');
+    lines.push('');
+    lines.push('## Examples');
+    lines.push('');
+    for (const ex of ref.examples) {
+        lines.push(`### ${ex.description}`);
+        lines.push('');
+        lines.push(`\`\`\`${lang}`);
+        for (const cmd of ex.code) {
+            lines.push(cmd);
+        }
+        lines.push('```');
+        lines.push('');
+    }
     return lines.join('\n');
 }

package/core/codegen/hooks-docs-generator.d.ts

@@ -3,4 +3,4 @@ import type { GeneratedDocFile, McpTool } from './docs-utils';
 export declare function generateHooksReadme(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile;
 export declare function generateHooksAgentsDocs(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile;
 export declare function getHooksMcpTools(tables: CleanTable[], customOperations: CleanOperation[]): McpTool[];
-export declare function generateHooksSkills(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile[];
+export declare function generateHooksSkills(tables: CleanTable[], customOperations: CleanOperation[], targetName: string): GeneratedDocFile[];