@constructive-io/graphql-codegen 4.25.0 → 4.27.0

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

@@ -1,7 +1,7 @@
 import * as t from '@babel/types';
-import { toKebabCase } from 'komoji';
+import { toKebabCase } from 'inflekt';
 import { generateCode } from '../babel-ast';
-import { getGeneratedFileHeader, getPrimaryKeyInfo, getScalarFields, getSelectableScalarFields, getTableNames, getWritableFieldNames, resolveInnerInputType, ucFirst, lcFirst, toPascalCase, getCreateInputTypeName, getPatchTypeName, } from '../utils';
+import { getGeneratedFileHeader, getPrimaryKeyInfo, getScalarFields, getSelectableScalarFields, getTableNames, getWritableFieldNames, resolveInnerInputType, ucFirst, lcFirst, toPascalCase, getCreateInputTypeName, getPatchTypeName, getFilterTypeName, getOrderByTypeName, getConditionTypeName, } from '../utils';
 import { categorizeSpecialFields } from '../docs-utils';
 function createImportDeclaration(moduleSpecifier, namedImports, typeOnly = false) {
     const specifiers = namedImports.map((name) => t.importSpecifier(t.identifier(name), t.identifier(name)));
@@ -165,7 +165,146 @@ function buildSubcommandSwitch(subcommands, handlerPrefix, usageVarName) {
     ]));
     return t.switchStatement(t.identifier('subcommand'), cases);
 }
-function buildListHandler(table, targetName, typeRegistry) {
+/**
+ * Build an auto-embed block that resolves the embedder and converts text
+ * values in the where clause to vector embeddings.
+ *
+ * Generates code equivalent to:
+ *   if (argv['auto-embed']) {
+ *     const embedder = resolveEmbedder();
+ *     if (!embedder) {
+ *       console.error('--auto-embed requires an embedder. Set EMBEDDER_PROVIDER=ollama');
+ *       process.exit(1);
+ *     }
+ *     await autoEmbedWhere(findManyArgs.where ?? {}, ['fieldA', 'fieldB'], embedder);
+ *   }
+ *
+ * @param whereExpr - The expression to access the where clause (e.g. findManyArgs.where, searchWhere)
+ * @param vectorFieldNames - Names of vector embedding fields detected at codegen time
+ * @param assignBack - If true, assigns the result back to findManyArgs.where
+ */
+function buildAutoEmbedBlock(whereExpr, vectorFieldNames, assignBack = false) {
+    const fieldNamesArray = t.arrayExpression(vectorFieldNames.map((n) => t.stringLiteral(n)));
+    const embedderDecl = t.variableDeclaration('const', [
+        t.variableDeclarator(t.identifier('embedder'), t.callExpression(t.identifier('resolveEmbedder'), [])),
+    ]);
+    const noEmbedderCheck = t.ifStatement(t.unaryExpression('!', t.identifier('embedder')), t.blockStatement([
+        t.expressionStatement(t.callExpression(t.memberExpression(t.identifier('console'), t.identifier('error')), [
+            t.stringLiteral('--auto-embed requires an embedder. Set EMBEDDER_PROVIDER=ollama (and optionally EMBEDDER_MODEL, EMBEDDER_BASE_URL).'),
+        ])),
+        t.expressionStatement(t.callExpression(t.memberExpression(t.identifier('process'), t.identifier('exit')), [t.numericLiteral(1)])),
+    ]));
+    const autoEmbedCall = t.awaitExpression(t.callExpression(t.identifier('autoEmbedWhere'), [
+        t.logicalExpression('??', whereExpr, t.objectExpression([])),
+        fieldNamesArray,
+        t.identifier('embedder'),
+    ]));
+    const bodyStatements = [embedderDecl, noEmbedderCheck];
+    if (assignBack) {
+        // findManyArgs.where = await autoEmbedWhere(findManyArgs.where ?? {}, [...], embedder);
+        bodyStatements.push(t.expressionStatement(t.assignmentExpression('=', t.memberExpression(t.identifier('findManyArgs'), t.identifier('where')), autoEmbedCall)));
+    }
+    else {
+        // await autoEmbedWhere(searchWhere, [...], embedder);
+        bodyStatements.push(t.expressionStatement(autoEmbedCall));
+    }
+    return t.ifStatement(t.memberExpression(t.identifier('argv'), t.stringLiteral('auto-embed'), true), t.blockStatement(bodyStatements));
+}
+/**
+ * Build an auto-embed block for mutation handlers (create/update).
+ *
+ * Generates code equivalent to:
+ *   if (argv['auto-embed']) {
+ *     const embedder = resolveEmbedder();
+ *     if (!embedder) {
+ *       console.error('--auto-embed requires an embedder. Set EMBEDDER_PROVIDER=ollama');
+ *       process.exit(1);
+ *     }
+ *     await autoEmbedInput(cleanedData, ['embedding'], embedder);
+ *   }
+ *
+ * @param vectorFieldNames - Names of vector embedding fields detected at codegen time
+ */
+function buildAutoEmbedInputBlock(vectorFieldNames) {
+    const fieldNamesArray = t.arrayExpression(vectorFieldNames.map((n) => t.stringLiteral(n)));
+    const embedderDecl = t.variableDeclaration('const', [
+        t.variableDeclarator(t.identifier('embedder'), t.callExpression(t.identifier('resolveEmbedder'), [])),
+    ]);
+    const noEmbedderCheck = t.ifStatement(t.unaryExpression('!', t.identifier('embedder')), t.blockStatement([
+        t.expressionStatement(t.callExpression(t.memberExpression(t.identifier('console'), t.identifier('error')), [
+            t.stringLiteral('--auto-embed requires an embedder. Set EMBEDDER_PROVIDER=ollama (and optionally EMBEDDER_MODEL, EMBEDDER_BASE_URL).'),
+        ])),
+        t.expressionStatement(t.callExpression(t.memberExpression(t.identifier('process'), t.identifier('exit')), [t.numericLiteral(1)])),
+    ]));
+    const autoEmbedCall = t.awaitExpression(t.callExpression(t.identifier('autoEmbedInput'), [
+        t.identifier('cleanedData'),
+        fieldNamesArray,
+        t.identifier('embedder'),
+    ]));
+    return t.ifStatement(t.memberExpression(t.identifier('argv'), t.stringLiteral('auto-embed'), true), t.blockStatement([
+        embedderDecl,
+        noEmbedderCheck,
+        t.expressionStatement(autoEmbedCall),
+    ]));
+}
+/**
+ * Build the FindManyArgs type instantiation for a table:
+ * FindManyArgs<SelectType, FilterType, ConditionType, OrderByType> & { select: SelectType }
+ *
+ * The intersection with { select: SelectType } makes select required,
+ * matching what the ORM's findMany method expects. parseFindManyArgs
+ * always sets select at runtime (from defaultSelect or --select flag).
+ */
+function buildFindManyArgsType(table, conditionEnabled) {
+    const { typeName } = getTableNames(table);
+    const selectTypeName = `${typeName}Select`;
+    const whereTypeName = getFilterTypeName(table);
+    const conditionTypeName = conditionEnabled ? getConditionTypeName(table) : undefined;
+    const orderByTypeName = getOrderByTypeName(table);
+    const findManyType = t.tsTypeReference(t.identifier('FindManyArgs'), t.tsTypeParameterInstantiation([
+        t.tsTypeReference(t.identifier(selectTypeName)),
+        t.tsTypeReference(t.identifier(whereTypeName)),
+        conditionTypeName
+            ? t.tsTypeReference(t.identifier(conditionTypeName))
+            : t.tsNeverKeyword(),
+        t.tsTypeReference(t.identifier(orderByTypeName)),
+    ]));
+    // Intersect with { select: SelectType } to make select required
+    return t.tsIntersectionType([
+        findManyType,
+        t.tsTypeLiteral([
+            Object.assign(t.tsPropertySignature(t.identifier('select'), t.tsTypeAnnotation(t.tsTypeReference(t.identifier(selectTypeName)))), { optional: false }),
+        ]),
+    ]);
+}
+/**
+ * Build the FindFirstArgs type instantiation for a table:
+ * FindFirstArgs<SelectType, FilterType, ConditionType> & { select: SelectType }
+ *
+ * The intersection with { select: SelectType } makes select required,
+ * matching what the ORM's findFirst method expects.
+ */
+function buildFindFirstArgsType(table, conditionEnabled) {
+    const { typeName } = getTableNames(table);
+    const selectTypeName = `${typeName}Select`;
+    const whereTypeName = getFilterTypeName(table);
+    const conditionTypeName = conditionEnabled ? getConditionTypeName(table) : undefined;
+    const findFirstType = t.tsTypeReference(t.identifier('FindFirstArgs'), t.tsTypeParameterInstantiation([
+        t.tsTypeReference(t.identifier(selectTypeName)),
+        t.tsTypeReference(t.identifier(whereTypeName)),
+        conditionTypeName
+            ? t.tsTypeReference(t.identifier(conditionTypeName))
+            : t.tsNeverKeyword(),
+    ]));
+    // Intersect with { select: SelectType } to make select required
+    return t.tsIntersectionType([
+        findFirstType,
+        t.tsTypeLiteral([
+            Object.assign(t.tsPropertySignature(t.identifier('select'), t.tsTypeAnnotation(t.tsTypeReference(t.identifier(selectTypeName)))), { optional: false }),
+        ]),
+    ]);
+}
+function buildListHandler(table, vectorFieldNames, targetName, typeRegistry, conditionEnabled = false) {
     const { singularName } = getTableNames(table);
     const defaultSelectObj = buildSelectObject(table, typeRegistry);
     // --- Build the try body ---
@@ -174,13 +313,23 @@ function buildListHandler(table, targetName, typeRegistry) {
     tryBody.push(t.variableDeclaration('const', [
         t.variableDeclarator(t.identifier('defaultSelect'), defaultSelectObj),
     ]));
-    // const findManyArgs = parseFindManyArgs(argv, defaultSelect);
-    tryBody.push(t.variableDeclaration('const', [
-        t.variableDeclarator(t.identifier('findManyArgs'), t.callExpression(t.identifier('parseFindManyArgs'), [
+    // const findManyArgs = parseFindManyArgs<FindManyArgs<...>>(argv, defaultSelect);
+    {
+        const callExpr = t.callExpression(t.identifier('parseFindManyArgs'), [
             t.identifier('argv'),
             t.identifier('defaultSelect'),
-        ])),
-    ]));
+        ]);
+        callExpr.typeParameters = t.tsTypeParameterInstantiation([
+            buildFindManyArgsType(table, conditionEnabled),
+        ]);
+        tryBody.push(t.variableDeclaration('const', [
+            t.variableDeclarator(t.identifier('findManyArgs'), callExpr),
+        ]));
+    }
+    // Auto-embed vector fields in the where clause when --auto-embed is passed
+    if (vectorFieldNames.length > 0) {
+        tryBody.push(buildAutoEmbedBlock(t.memberExpression(t.identifier('findManyArgs'), t.identifier('where')), vectorFieldNames, true));
+    }
     tryBody.push(buildGetClientStatement(targetName));
     // const result = await client.<singular>.findMany(findManyArgs).execute();
     tryBody.push(t.variableDeclaration('const', [
@@ -197,10 +346,10 @@ function buildListHandler(table, targetName, typeRegistry) {
 }
 /**
  * Build a `handleFindFirst` function — CLI equivalent of the TS SDK's findFirst().
- * Accepts --fields, --where.<field>.<op>, --condition.<field>.<op> flags.
+ * Accepts --select, --where.<field>.<op>, --condition.<field>.<op> flags.
  * Internally calls findMany with first:1 and returns a single record (or null).
  */
-function buildFindFirstHandler(table, targetName, typeRegistry) {
+function buildFindFirstHandler(table, targetName, typeRegistry, conditionEnabled = false) {
     const { singularName } = getTableNames(table);
     const defaultSelectObj = buildSelectObject(table, typeRegistry);
     const tryBody = [];
@@ -208,13 +357,19 @@ function buildFindFirstHandler(table, targetName, typeRegistry) {
     tryBody.push(t.variableDeclaration('const', [
         t.variableDeclarator(t.identifier('defaultSelect'), defaultSelectObj),
     ]));
-    // const findFirstArgs = parseFindFirstArgs(argv, defaultSelect);
-    tryBody.push(t.variableDeclaration('const', [
-        t.variableDeclarator(t.identifier('findFirstArgs'), t.callExpression(t.identifier('parseFindFirstArgs'), [
+    // const findFirstArgs = parseFindFirstArgs<FindFirstArgs<...>>(argv, defaultSelect);
+    {
+        const callExpr = t.callExpression(t.identifier('parseFindFirstArgs'), [
             t.identifier('argv'),
             t.identifier('defaultSelect'),
-        ])),
-    ]));
+        ]);
+        callExpr.typeParameters = t.tsTypeParameterInstantiation([
+            buildFindFirstArgsType(table, conditionEnabled),
+        ]);
+        tryBody.push(t.variableDeclaration('const', [
+            t.variableDeclarator(t.identifier('findFirstArgs'), callExpr),
+        ]));
+    }
     tryBody.push(buildGetClientStatement(targetName));
     // const result = await client.<singular>.findFirst(findFirstArgs).execute();
     tryBody.push(t.variableDeclaration('const', [
@@ -233,9 +388,9 @@ function buildFindFirstHandler(table, targetName, typeRegistry) {
  * Build a `handleSearch` function for tables with search-capable fields.
  * Extracts the first positional arg as the query string and auto-builds a
  * `where` clause that targets all detected search fields (tsvector, BM25,
- * trigram, vector embedding).  Supports --limit, --offset, --fields, --orderBy.
+ * trigram, vector embedding).  Supports --limit, --offset, --select, --orderBy.
  */
-function buildSearchHandler(table, specialGroups, targetName, typeRegistry) {
+function buildSearchHandler(table, specialGroups, vectorFieldNames, targetName, typeRegistry, conditionEnabled = false) {
     const { singularName } = getTableNames(table);
     const defaultSelectObj = buildSelectObject(table, typeRegistry);
     const tryBody = [];
@@ -251,11 +406,11 @@ function buildSearchHandler(table, specialGroups, targetName, typeRegistry) {
         t.expressionStatement(t.callExpression(t.memberExpression(t.identifier('process'), t.identifier('exit')), [t.numericLiteral(1)])),
     ])));
     // Build the where clause properties from detected search fields
-    // e.g. { tsvContent: { query }, bm25Body: { query }, trgmTitle: { value: query, threshold: 0.3 }, vectorEmbedding: { value: query } }
+    // e.g. { tsvContent: { query }, bm25Body: { query }, trgmTitle: { value: query, threshold: 0.3 }, vectorEmbedding: { vector: query } }
     const whereProps = [];
     for (const group of specialGroups) {
         for (const field of group.fields) {
-            if (field.type.pgType?.toLowerCase() === 'tsvector') {
+            if (field.type.gqlType === 'FullText' && !field.type.isArray) {
                 // tsvector field: { query }
                 whereProps.push(t.objectProperty(t.identifier(field.name), t.objectExpression([
                     t.objectProperty(t.identifier('query'), t.identifier('query'), false, true),
@@ -281,9 +436,10 @@ function buildSearchHandler(table, specialGroups, targetName, typeRegistry) {
                 ])));
             }
             else if (group.category === 'embedding') {
-                // Vector embedding field: { value: query }
+                // Vector embedding field: { vector: query }
+                // When --auto-embed is used, autoEmbedWhere will convert the text to a vector
                 whereProps.push(t.objectProperty(t.identifier(field.name), t.objectExpression([
-                    t.objectProperty(t.identifier('value'), t.identifier('query')),
+                    t.objectProperty(t.identifier('vector'), t.identifier('query')),
                 ])));
             }
         }
@@ -292,18 +448,28 @@ function buildSearchHandler(table, specialGroups, targetName, typeRegistry) {
     tryBody.push(t.variableDeclaration('const', [
         t.variableDeclarator(t.identifier('searchWhere'), t.objectExpression(whereProps)),
     ]));
+    // Auto-embed vector fields in the where clause when --auto-embed is passed
+    if (vectorFieldNames.length > 0) {
+        tryBody.push(buildAutoEmbedBlock(t.identifier('searchWhere'), vectorFieldNames, false));
+    }
     // const defaultSelect = { ... };
     tryBody.push(t.variableDeclaration('const', [
         t.variableDeclarator(t.identifier('defaultSelect'), defaultSelectObj),
     ]));
-    // const findManyArgs = parseFindManyArgs(argv, defaultSelect, searchWhere);
-    tryBody.push(t.variableDeclaration('const', [
-        t.variableDeclarator(t.identifier('findManyArgs'), t.callExpression(t.identifier('parseFindManyArgs'), [
+    // const findManyArgs = parseFindManyArgs<FindManyArgs<...>>(argv, defaultSelect, searchWhere);
+    {
+        const callExpr = t.callExpression(t.identifier('parseFindManyArgs'), [
             t.identifier('argv'),
             t.identifier('defaultSelect'),
             t.identifier('searchWhere'),
-        ])),
-    ]));
+        ]);
+        callExpr.typeParameters = t.tsTypeParameterInstantiation([
+            buildFindManyArgsType(table, conditionEnabled),
+        ]);
+        tryBody.push(t.variableDeclaration('const', [
+            t.variableDeclarator(t.identifier('findManyArgs'), callExpr),
+        ]));
+    }
     tryBody.push(buildGetClientStatement(targetName));
     // const result = await client.<singular>.findMany(findManyArgs).execute();
     tryBody.push(t.variableDeclaration('const', [
@@ -375,7 +541,7 @@ export function getFieldsWithDefaults(table, typeRegistry) {
     }
     return fieldsWithDefaults;
 }
-function buildMutationHandler(table, operation, targetName, typeRegistry, ormTypes) {
+function buildMutationHandler(table, operation, vectorFieldNames, targetName, typeRegistry, ormTypes) {
     const { singularName } = getTableNames(table);
     const pkFields = getPrimaryKeyInfo(table);
     const pk = pkFields[0];
@@ -503,6 +669,11 @@ function buildMutationHandler(table, operation, targetName, typeRegistry, ormTyp
         tryBody.push(t.variableDeclaration('const', [
             t.variableDeclarator(t.identifier('cleanedData'), cleanedDataExpr),
         ]));
+        // Inject --auto-embed block for create/update when table has vector fields.
+        // Converts text strings in vector fields to embeddings before the ORM call.
+        if (vectorFieldNames.length > 0) {
+            tryBody.push(buildAutoEmbedInputBlock(vectorFieldNames));
+        }
     }
     tryBody.push(buildGetClientStatement(targetName), t.variableDeclaration('const', [
         t.variableDeclarator(t.identifier('result'), t.awaitExpression(buildOrmCall(singularName, operation, ormArgs))),
@@ -517,7 +688,7 @@ function buildMutationHandler(table, operation, targetName, typeRegistry, ormTyp
     ]), false, true);
 }
 export function generateTableCommand(table, options) {
-    const { singularName } = getTableNames(table);
+    const { singularName, typeName } = getTableNames(table);
     const commandName = toKebabCase(singularName);
     const statements = [];
     const executorPath = options?.executorImportPath ?? '../executor';
@@ -542,7 +713,25 @@ export function generateTableCommand(table, options) {
     const inputTypesPath = options?.targetName
         ? `../../../orm/input-types`
         : `../../orm/input-types`;
-    statements.push(createImportDeclaration(inputTypesPath, [createInputTypeName, patchTypeName], true));
+    // Import table-specific ORM types for generic type parameters on parseFindManyArgs/parseFindFirstArgs
+    const selectTypeName = `${typeName}Select`;
+    const whereTypeName = getFilterTypeName(table);
+    const orderByTypeName = getOrderByTypeName(table);
+    const conditionEnabled = options?.condition === true;
+    const conditionTypeName = conditionEnabled ? getConditionTypeName(table) : undefined;
+    statements.push(createImportDeclaration(inputTypesPath, [
+        createInputTypeName,
+        patchTypeName,
+        selectTypeName,
+        whereTypeName,
+        ...(conditionTypeName ? [conditionTypeName] : []),
+        orderByTypeName,
+    ], true));
+    // Import FindManyArgs/FindFirstArgs from select-types for proper generic typing
+    const selectTypesPath = options?.targetName
+        ? `../../../orm/select-types`
+        : `../../orm/select-types`;
+    statements.push(createImportDeclaration(selectTypesPath, ['FindManyArgs', 'FindFirstArgs'], true));
     // Generate field schema for type coercion
     // Use explicit FieldSchema type annotation so TS narrows string literals to FieldType
     const fieldSchemaId = t.identifier('fieldSchema');
@@ -563,6 +752,21 @@ export function generateTableCommand(table, options) {
     // Detect whether this table has search-capable fields (tsvector, BM25, trgm, vector embedding)
     const specialGroups = categorizeSpecialFields(table, options?.typeRegistry);
     const hasSearchFields = specialGroups.some((g) => g.category === 'search' || g.category === 'embedding');
+    // Collect vector embedding field names for --auto-embed support
+    const vectorFieldNames = [];
+    for (const group of specialGroups) {
+        if (group.category === 'embedding') {
+            for (const field of group.fields) {
+                vectorFieldNames.push(field.name);
+            }
+        }
+    }
+    const hasEmbeddings = vectorFieldNames.length > 0;
+    // Import embedder functions when table has vector embedding fields
+    if (hasEmbeddings) {
+        const embedderPath = options?.targetName ? '../../embedder' : '../embedder';
+        statements.push(createImportDeclaration(embedderPath, ['resolveEmbedder', 'autoEmbedWhere', 'autoEmbedInput']));
+    }
     const subcommands = ['list', 'find-first'];
     if (hasSearchFields)
         subcommands.push('search');
@@ -588,11 +792,21 @@ export function generateTableCommand(table, options) {
     usageLines.push(`  create                Create a new ${singularName}`);
     if (hasUpdate)
         usageLines.push(`  update                Update an existing ${singularName}`);
+    if (hasEmbeddings) {
+        usageLines.push('', 'Create/Update Options:', '  --auto-embed          Convert text values in vector fields to embeddings before saving');
+    }
     if (hasDelete)
         usageLines.push(`  delete                Delete a ${singularName}`);
-    usageLines.push('', 'List Options:', '  --limit <n>           Max number of records to return (forward pagination)', '  --last <n>            Number of records from the end (backward pagination)', '  --after <cursor>      Cursor for forward pagination', '  --before <cursor>     Cursor for backward pagination', '  --offset <n>          Number of records to skip', '  --fields <fields>     Comma-separated list of fields to return', '  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)', '  --condition.<f>.<op>  Condition filter (dot-notation)', '  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)', '', 'Find-First Options:', '  --fields <fields>     Comma-separated list of fields to return', '  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)', '  --condition.<f>.<op>  Condition filter (dot-notation)', '');
+    usageLines.push('', 'List Options:', '  --limit <n>           Max number of records to return (forward pagination)', '  --last <n>            Number of records from the end (backward pagination)', '  --after <cursor>      Cursor for forward pagination', '  --before <cursor>     Cursor for backward pagination', '  --offset <n>          Number of records to skip', '  --select <fields>     Comma-separated list of fields to return', '  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)', '  --condition.<f>.<op>  Condition filter (dot-notation)', '  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)', '', 'Find-First Options:', '  --select <fields>     Comma-separated list of fields to return', '  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)', '  --condition.<f>.<op>  Condition filter (dot-notation)', '');
     if (hasSearchFields) {
-        usageLines.push('Search Options:', '  <query>               Search query string (required)', '  --limit <n>           Max number of records to return', '  --offset <n>          Number of records to skip', '  --fields <fields>     Comma-separated list of fields to return', '  --orderBy <values>    Comma-separated list of ordering values', '');
+        usageLines.push('Search Options:', '  <query>               Search query string (required)', '  --limit <n>           Max number of records to return', '  --offset <n>          Number of records to skip', '  --select <fields>     Comma-separated list of fields to return', '  --orderBy <values>    Comma-separated list of ordering values');
+        if (hasEmbeddings) {
+            usageLines.push('  --auto-embed          Convert text queries to vectors via configured embedder');
+        }
+        usageLines.push('');
+    }
+    if (hasEmbeddings) {
+        usageLines.push('Embedding Options (for --auto-embed):', '  Set EMBEDDER_PROVIDER=ollama to enable text-to-vector embedding.', '  Optional: EMBEDDER_MODEL (default: nomic-embed-text)', '  Optional: EMBEDDER_BASE_URL (default: http://localhost:11434)', '');
     }
     usageLines.push('  --help, -h            Show this help message', '');
     statements.push(t.variableDeclaration('const', [
@@ -655,17 +869,17 @@ export function generateTableCommand(table, options) {
     ]), false, true));
     const tn = options?.targetName;
     const ormTypes = { createInputTypeName, patchTypeName, innerFieldName };
-    statements.push(buildListHandler(table, tn, options?.typeRegistry));
-    statements.push(buildFindFirstHandler(table, tn, options?.typeRegistry));
+    statements.push(buildListHandler(table, vectorFieldNames, tn, options?.typeRegistry, conditionEnabled));
+    statements.push(buildFindFirstHandler(table, tn, options?.typeRegistry, conditionEnabled));
     if (hasSearchFields)
-        statements.push(buildSearchHandler(table, specialGroups, tn, options?.typeRegistry));
+        statements.push(buildSearchHandler(table, specialGroups, vectorFieldNames, tn, options?.typeRegistry, conditionEnabled));
     if (hasGet)
         statements.push(buildGetHandler(table, tn, options?.typeRegistry));
-    statements.push(buildMutationHandler(table, 'create', tn, options?.typeRegistry, ormTypes));
+    statements.push(buildMutationHandler(table, 'create', vectorFieldNames, tn, options?.typeRegistry, ormTypes));
     if (hasUpdate)
-        statements.push(buildMutationHandler(table, 'update', tn, options?.typeRegistry, ormTypes));
+        statements.push(buildMutationHandler(table, 'update', vectorFieldNames, tn, options?.typeRegistry, ormTypes));
     if (hasDelete)
-        statements.push(buildMutationHandler(table, 'delete', tn, options?.typeRegistry, ormTypes));
+        statements.push(buildMutationHandler(table, 'delete', vectorFieldNames, tn, options?.typeRegistry, ormTypes));
     const header = getGeneratedFileHeader(`CLI commands for ${table.name}`);
     const code = generateCode(statements);
     return {

package/esm/core/codegen/cli/utils-generator.d.ts

@@ -25,3 +25,11 @@ export declare function generateNodeFetchFile(): GeneratedFile;
  * provide their own entry point with custom configuration.
  */
 export declare function generateEntryPointFile(): GeneratedFile;
+/**
+ * Generate an embedder.ts file with pluggable text-to-vector embedding.
+ *
+ * Provides a runtime embedder registry using @agentic-kit/ollama so that
+ * CLI search and list commands can convert text queries into vector arrays
+ * for pgvector similarity search when --auto-embed is passed.
+ */
+export declare function generateEmbedderFile(): GeneratedFile;

package/esm/core/codegen/cli/utils-generator.js

@@ -67,3 +67,16 @@ export function generateEntryPointFile() {
         content: readTemplateFile('cli-entry.ts', 'CLI entry point'),
     };
 }
+/**
+ * Generate an embedder.ts file with pluggable text-to-vector embedding.
+ *
+ * Provides a runtime embedder registry using @agentic-kit/ollama so that
+ * CLI search and list commands can convert text queries into vector arrays
+ * for pgvector similarity search when --auto-embed is passed.
+ */
+export function generateEmbedderFile() {
+    return {
+        fileName: 'embedder.ts',
+        content: readTemplateFile('embedder.ts', 'CLI embedder — pluggable text-to-vector embedding for search commands'),
+    };
+}

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

@@ -65,6 +65,23 @@ export declare function buildSpecialFieldsMarkdown(groups: SpecialFieldGroup[]):
  * Returns empty array when there are no special fields.
  */
 export declare function buildSpecialFieldsPlain(groups: SpecialFieldGroup[]): string[];
+export interface SearchExample {
+    description: string;
+    code: string[];
+}
+/**
+ * Build concrete, field-specific CLI examples for tables with search fields.
+ * Uses the same field-name derivation logic as buildSearchHandler in
+ * table-command-generator.ts so the examples match the actual generated code.
+ *
+ * Returns an empty array when the table has no search/embedding fields.
+ */
+export declare function buildSearchExamples(specialGroups: SpecialFieldGroup[], toolName: string, cmd: string): SearchExample[];
+/**
+ * Build markdown lines for search-specific examples in README-style docs.
+ * Returns empty array when there are no search examples.
+ */
+export declare function buildSearchExamplesMarkdown(specialGroups: SpecialFieldGroup[], toolName: string, cmd: string): string[];
 /**
  * Represents a flattened argument for docs/skills generation.
  * INPUT_OBJECT args are expanded to dot-notation fields.

package/esm/core/codegen/docs-utils.js

@@ -96,16 +96,23 @@ function isPostGISField(f) {
     return false;
 }
 function isEmbeddingField(f) {
-    const pgType = f.type.pgType?.toLowerCase();
-    if (pgType === 'vector')
+    // VectorCodecPlugin maps pgvector `vector` columns to the `Vector` GQL scalar.
+    // This is the primary detection path — no _meta or pgType enrichment needed.
+    if (f.type.gqlType === 'Vector')
         return true;
+    // Legacy fallback: name-based heuristic for schemas without VectorCodecPlugin
     if (/embedding$/i.test(f.name) && f.type.isArray && f.type.gqlType === 'Float')
         return true;
     return false;
 }
 function isTsvectorField(f) {
     const pgType = f.type.pgType?.toLowerCase();
-    return pgType === 'tsvector';
+    if (pgType === 'tsvector')
+        return true;
+    // Fallback: PostGraphile maps tsvector columns to the FullText GQL scalar
+    if (f.type.gqlType === 'FullText' && !f.type.isArray)
+        return true;
+    return false;
 }
 function isSearchComputedField(f) {
     if (f.name === 'searchScore')
@@ -227,6 +234,131 @@ export function buildSpecialFieldsPlain(groups) {
     }
     return lines;
 }
+/**
+ * Build concrete, field-specific CLI examples for tables with search fields.
+ * Uses the same field-name derivation logic as buildSearchHandler in
+ * table-command-generator.ts so the examples match the actual generated code.
+ *
+ * Returns an empty array when the table has no search/embedding fields.
+ */
+export function buildSearchExamples(specialGroups, toolName, cmd) {
+    const examples = [];
+    const scoreFields = [];
+    for (const group of specialGroups) {
+        for (const field of group.fields) {
+            // tsvector (FullText scalar) — where input uses the column name directly
+            if (field.type.gqlType === 'FullText' && !field.type.isArray) {
+                examples.push({
+                    description: `Full-text search via tsvector (\`${field.name}\`)`,
+                    code: [
+                        `${toolName} ${cmd} list --where.${field.name} "search query" --select title,tsvRank`,
+                    ],
+                });
+                scoreFields.push('tsvRank');
+            }
+            // BM25 computed score — bodyBm25Score → bm25Body
+            if (/Bm25Score$/.test(field.name)) {
+                const baseName = field.name.replace(/Bm25Score$/, '');
+                const inputName = `bm25${baseName.charAt(0).toUpperCase()}${baseName.slice(1)}`;
+                examples.push({
+                    description: `BM25 keyword search via \`${inputName}\``,
+                    code: [
+                        `${toolName} ${cmd} list --where.${inputName}.query "search query" --select title,${field.name}`,
+                    ],
+                });
+                scoreFields.push(field.name);
+            }
+            // Trigram similarity — titleTrgmSimilarity → trgmTitle
+            if (/TrgmSimilarity$/.test(field.name)) {
+                const baseName = field.name.replace(/TrgmSimilarity$/, '');
+                const inputName = `trgm${baseName.charAt(0).toUpperCase()}${baseName.slice(1)}`;
+                examples.push({
+                    description: `Fuzzy search via trigram similarity (\`${inputName}\`)`,
+                    code: [
+                        `${toolName} ${cmd} list --where.${inputName}.value "approximate query" --where.${inputName}.threshold 0.3 --select title,${field.name}`,
+                    ],
+                });
+                scoreFields.push(field.name);
+            }
+            // pgvector embedding — uses column name, with --auto-embed for text-to-vector
+            if (group.category === 'embedding') {
+                examples.push({
+                    description: `Vector similarity search via \`${field.name}\` (manual vector)`,
+                    code: [
+                        `# Pass a pre-computed vector array via dot-notation`,
+                        `${toolName} ${cmd} list --where.${field.name}.vector '[0.1,0.2,0.3]' --where.${field.name}.distance 1.0 --select title,${field.name}VectorDistance`,
+                    ],
+                });
+                examples.push({
+                    description: `Vector semantic search via \`${field.name}\` with --auto-embed`,
+                    code: [
+                        `# --auto-embed converts text to vectors using the configured embedder (e.g. Ollama nomic-embed-text)`,
+                        `EMBEDDER_PROVIDER=ollama ${toolName} ${cmd} search "semantic query" --auto-embed --select title,${field.name}VectorDistance`,
+                        `EMBEDDER_PROVIDER=ollama ${toolName} ${cmd} list --where.${field.name}.vector "semantic query" --auto-embed --select title,${field.name}VectorDistance`,
+                    ],
+                });
+                examples.push({
+                    description: `Create/update with auto-embedded \`${field.name}\` via --auto-embed`,
+                    code: [
+                        `# --auto-embed on create/update converts text strings in vector fields to embeddings before saving`,
+                        `EMBEDDER_PROVIDER=ollama ${toolName} ${cmd} create --${field.name} "text to embed" --auto-embed`,
+                        `EMBEDDER_PROVIDER=ollama ${toolName} ${cmd} update --${field.name} "new text to embed" --auto-embed`,
+                    ],
+                });
+            }
+            // searchScore — composite blend field, useful for ordering
+            if (field.name === 'searchScore') {
+                scoreFields.push('searchScore');
+            }
+        }
+    }
+    // Composite fullTextSearch example (dispatches to all text adapters)
+    const hasTextSearch = specialGroups.some((g) => g.category === 'search' && g.fields.some((f) => f.type.gqlType === 'FullText' || /TrgmSimilarity$/.test(f.name) || /Bm25Score$/.test(f.name)));
+    if (hasTextSearch) {
+        const fieldsArg = scoreFields.length > 0
+            ? `title,${[...new Set(scoreFields)].join(',')}`
+            : 'title';
+        examples.push({
+            description: 'Composite search (fullTextSearch dispatches to all text adapters)',
+            code: [
+                `${toolName} ${cmd} list --where.fullTextSearch "search query" --select ${fieldsArg}`,
+            ],
+        });
+    }
+    // Combined search + pagination + ordering example
+    if (examples.length > 0) {
+        examples.push({
+            description: 'Search with pagination and field projection',
+            code: [
+                `${toolName} ${cmd} list --where.fullTextSearch "query" --limit 10 --select id,title,searchScore`,
+                `${toolName} ${cmd} search "query" --limit 10 --select id,title,searchScore`,
+            ],
+        });
+    }
+    return examples;
+}
+/**
+ * Build markdown lines for search-specific examples in README-style docs.
+ * Returns empty array when there are no search examples.
+ */
+export function buildSearchExamplesMarkdown(specialGroups, toolName, cmd) {
+    const examples = buildSearchExamples(specialGroups, toolName, cmd);
+    if (examples.length === 0)
+        return [];
+    const lines = [];
+    lines.push('**Search Examples:**');
+    lines.push('');
+    for (const ex of examples) {
+        lines.push(`*${ex.description}:*`);
+        lines.push('```bash');
+        for (const c of ex.code) {
+            lines.push(c);
+        }
+        lines.push('```');
+        lines.push('');
+    }
+    return lines;
+}
 function unwrapNonNull(typeRef) {
     if (typeRef.kind === 'NON_NULL' && typeRef.ofType) {
         return { inner: typeRef.ofType, required: true };

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

@@ -1,4 +1,4 @@
-import { toKebabCase } from 'komoji';
+import { toKebabCase } from 'inflekt';
 import { buildSkillFile, buildSkillReference, formatArgType, fieldPlaceholder, pkPlaceholder, argPlaceholder, getReadmeHeader, getReadmeFooter, } from './docs-utils';
 import { getTableNames, getScalarFields, getPrimaryKeyInfo, getListQueryHookName, getSingleQueryHookName, getCreateMutationHookName, getUpdateMutationHookName, getDeleteMutationHookName, hasValidPrimaryKey, ucFirst, } from './utils';
 function getCustomHookName(op) {

package/esm/core/codegen/index.js

@@ -92,7 +92,7 @@ export function generate(options) {
         hasInvalidation = true;
     }
     // Condition types (PostGraphile simple equality filters)
-    const conditionEnabled = config.codegen?.condition !== false;
+    const conditionEnabled = config.codegen?.condition === true;
     // 4. Generate table-based query hooks (queries/*.ts)
     const queryHooks = generateAllQueryHooks(tables, {
         reactQueryEnabled,