feat(codegen): pluggable embedding system with --auto-embed flag [CI]

graphql/codegen/src/__tests__/codegen/__snapshots__/cli-generator.test.ts.snap

@@ -321,7 +321,7 @@ myapp car find-first --where.id.equalTo <value>
 ### List car records with field selection
 
 \`\`\`bash
-myapp car list --fields id,id
+myapp car list --select id,id
 \`\`\`
 
 ### List car records with filtering and ordering
@@ -393,7 +393,7 @@ myapp driver find-first --where.id.equalTo <value>
 ### List driver records with field selection
 
 \`\`\`bash
-myapp driver list --fields id,id
+myapp driver list --select id,id
 \`\`\`
 
 ### List driver records with filtering and ordering
@@ -706,7 +706,7 @@ const fieldSchema: FieldSchema = {
   isElectric: "boolean",
   createdAt: "string"
 };
-const usage = "\\ncar <command>\\n\\nCommands:\\n  list                  List car records\\n  find-first            Find first matching car record\\n  get                   Get a car by ID\\n  create                Create a new car\\n  update                Update an existing car\\n  delete                Delete a car\\n\\nList Options:\\n  --limit <n>           Max number of records to return (forward pagination)\\n  --last <n>            Number of records from the end (backward pagination)\\n  --after <cursor>      Cursor for forward pagination\\n  --before <cursor>     Cursor for backward pagination\\n  --offset <n>          Number of records to skip\\n  --fields <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)\\n\\nFind-First Options:\\n  --fields <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n\\n  --help, -h            Show this help message\\n";
+const usage = "\\ncar <command>\\n\\nCommands:\\n  list                  List car records\\n  find-first            Find first matching car record\\n  get                   Get a car by ID\\n  create                Create a new car\\n  update                Update an existing car\\n  delete                Delete a car\\n\\nList Options:\\n  --limit <n>           Max number of records to return (forward pagination)\\n  --last <n>            Number of records from the end (backward pagination)\\n  --after <cursor>      Cursor for forward pagination\\n  --before <cursor>     Cursor for backward pagination\\n  --offset <n>          Number of records to skip\\n  --select <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)\\n\\nFind-First Options:\\n  --select <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n\\n  --help, -h            Show this help message\\n";
 export default async (argv: Partial<Record<string, unknown>>, prompter: Inquirerer, _options: CLIOptions) => {
   if (argv.help || argv.h) {
     console.log(usage);
@@ -1166,7 +1166,7 @@ const fieldSchema: FieldSchema = {
   name: "string",
   licenseNumber: "string"
 };
-const usage = "\\ndriver <command>\\n\\nCommands:\\n  list                  List driver records\\n  find-first            Find first matching driver record\\n  get                   Get a driver by ID\\n  create                Create a new driver\\n  update                Update an existing driver\\n  delete                Delete a driver\\n\\nList Options:\\n  --limit <n>           Max number of records to return (forward pagination)\\n  --last <n>            Number of records from the end (backward pagination)\\n  --after <cursor>      Cursor for forward pagination\\n  --before <cursor>     Cursor for backward pagination\\n  --offset <n>          Number of records to skip\\n  --fields <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)\\n\\nFind-First Options:\\n  --fields <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n\\n  --help, -h            Show this help message\\n";
+const usage = "\\ndriver <command>\\n\\nCommands:\\n  list                  List driver records\\n  find-first            Find first matching driver record\\n  get                   Get a driver by ID\\n  create                Create a new driver\\n  update                Update an existing driver\\n  delete                Delete a driver\\n\\nList Options:\\n  --limit <n>           Max number of records to return (forward pagination)\\n  --last <n>            Number of records from the end (backward pagination)\\n  --after <cursor>      Cursor for forward pagination\\n  --before <cursor>     Cursor for backward pagination\\n  --offset <n>          Number of records to skip\\n  --select <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)\\n\\nFind-First Options:\\n  --select <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n\\n  --help, -h            Show this help message\\n";
 export default async (argv: Partial<Record<string, unknown>>, prompter: Inquirerer, _options: CLIOptions) => {
   if (argv.help || argv.h) {
     console.log(usage);
@@ -3197,7 +3197,7 @@ const fieldSchema: FieldSchema = {
   email: "string",
   name: "string"
 };
-const usage = "\\nuser <command>\\n\\nCommands:\\n  list                  List user records\\n  find-first            Find first matching user record\\n  get                   Get a user by ID\\n  create                Create a new user\\n  update                Update an existing user\\n  delete                Delete a user\\n\\nList Options:\\n  --limit <n>           Max number of records to return (forward pagination)\\n  --last <n>            Number of records from the end (backward pagination)\\n  --after <cursor>      Cursor for forward pagination\\n  --before <cursor>     Cursor for backward pagination\\n  --offset <n>          Number of records to skip\\n  --fields <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)\\n\\nFind-First Options:\\n  --fields <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n\\n  --help, -h            Show this help message\\n";
+const usage = "\\nuser <command>\\n\\nCommands:\\n  list                  List user records\\n  find-first            Find first matching user record\\n  get                   Get a user by ID\\n  create                Create a new user\\n  update                Update an existing user\\n  delete                Delete a user\\n\\nList Options:\\n  --limit <n>           Max number of records to return (forward pagination)\\n  --last <n>            Number of records from the end (backward pagination)\\n  --after <cursor>      Cursor for forward pagination\\n  --before <cursor>     Cursor for backward pagination\\n  --offset <n>          Number of records to skip\\n  --select <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)\\n\\nFind-First Options:\\n  --select <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n\\n  --help, -h            Show this help message\\n";
 export default async (argv: Partial<Record<string, unknown>>, prompter: Inquirerer, _options: CLIOptions) => {
   if (argv.help || argv.h) {
     console.log(usage);
@@ -3425,7 +3425,7 @@ const fieldSchema: FieldSchema = {
   id: "uuid",
   role: "string"
 };
-const usage = "\\nmember <command>\\n\\nCommands:\\n  list                  List member records\\n  find-first            Find first matching member record\\n  get                   Get a member by ID\\n  create                Create a new member\\n  update                Update an existing member\\n  delete                Delete a member\\n\\nList Options:\\n  --limit <n>           Max number of records to return (forward pagination)\\n  --last <n>            Number of records from the end (backward pagination)\\n  --after <cursor>      Cursor for forward pagination\\n  --before <cursor>     Cursor for backward pagination\\n  --offset <n>          Number of records to skip\\n  --fields <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)\\n\\nFind-First Options:\\n  --fields <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n\\n  --help, -h            Show this help message\\n";
+const usage = "\\nmember <command>\\n\\nCommands:\\n  list                  List member records\\n  find-first            Find first matching member record\\n  get                   Get a member by ID\\n  create                Create a new member\\n  update                Update an existing member\\n  delete                Delete a member\\n\\nList Options:\\n  --limit <n>           Max number of records to return (forward pagination)\\n  --last <n>            Number of records from the end (backward pagination)\\n  --after <cursor>      Cursor for forward pagination\\n  --before <cursor>     Cursor for backward pagination\\n  --offset <n>          Number of records to skip\\n  --select <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)\\n\\nFind-First Options:\\n  --select <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n\\n  --help, -h            Show this help message\\n";
 export default async (argv: Partial<Record<string, unknown>>, prompter: Inquirerer, _options: CLIOptions) => {
   if (argv.help || argv.h) {
     console.log(usage);
@@ -3640,7 +3640,7 @@ const fieldSchema: FieldSchema = {
   isElectric: "boolean",
   createdAt: "string"
 };
-const usage = "\\ncar <command>\\n\\nCommands:\\n  list                  List car records\\n  find-first            Find first matching car record\\n  get                   Get a car by ID\\n  create                Create a new car\\n  update                Update an existing car\\n  delete                Delete a car\\n\\nList Options:\\n  --limit <n>           Max number of records to return (forward pagination)\\n  --last <n>            Number of records from the end (backward pagination)\\n  --after <cursor>      Cursor for forward pagination\\n  --before <cursor>     Cursor for backward pagination\\n  --offset <n>          Number of records to skip\\n  --fields <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)\\n\\nFind-First Options:\\n  --fields <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n\\n  --help, -h            Show this help message\\n";
+const usage = "\\ncar <command>\\n\\nCommands:\\n  list                  List car records\\n  find-first            Find first matching car record\\n  get                   Get a car by ID\\n  create                Create a new car\\n  update                Update an existing car\\n  delete                Delete a car\\n\\nList Options:\\n  --limit <n>           Max number of records to return (forward pagination)\\n  --last <n>            Number of records from the end (backward pagination)\\n  --after <cursor>      Cursor for forward pagination\\n  --before <cursor>     Cursor for backward pagination\\n  --offset <n>          Number of records to skip\\n  --select <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.name.equalTo foo)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n  --orderBy <values>    Comma-separated ordering values (e.g. NAME_ASC,CREATED_AT_DESC)\\n\\nFind-First Options:\\n  --select <fields>     Comma-separated list of fields to return\\n  --where.<field>.<op>  Filter (dot-notation, e.g. --where.status.equalTo active)\\n  --condition.<f>.<op>  Condition filter (dot-notation)\\n\\n  --help, -h            Show this help message\\n";
 export default async (argv: Partial<Record<string, unknown>>, prompter: Inquirerer, _options: CLIOptions) => {
   if (argv.help || argv.h) {
     console.log(usage);

graphql/codegen/src/core/codegen/cli/docs-generator.ts

@@ -10,6 +10,8 @@ import {
   getSearchFields,
   categorizeSpecialFields,
   buildSpecialFieldsMarkdown,
+  buildSearchExamples,
+  buildSearchExamplesMarkdown,
   getReadmeHeader,
   getReadmeFooter,
   gqlTypeToJsonSchemaType,
@@ -160,6 +162,7 @@ export function generateReadme(
       }
       const specialGroups = categorizeSpecialFields(table, registry);
       lines.push(...buildSpecialFieldsMarkdown(specialGroups));
+      lines.push(...buildSearchExamplesMarkdown(specialGroups, toolName, kebab));
       lines.push('');
     }
   }
@@ -424,18 +427,13 @@ export function generateSkills(
           },
           {
             description: `List ${singularName} records with field selection`,
-            code: [`${toolName} ${kebab} list --fields id,${pk.name}`],
+            code: [`${toolName} ${kebab} list --select id,${pk.name}`],
           },
           {
             description: `List ${singularName} records with filtering and ordering`,
             code: [`${toolName} ${kebab} list --where.${pk.name}.equalTo <value> --orderBy ${pk.name.replace(/([A-Z])/g, '_$1').toUpperCase()}_ASC`],
           },
-          ...(skillSpecialGroups.some((g) => g.category === 'search' || g.category === 'embedding')
-            ? [{
-                description: `Search ${singularName} records`,
-                code: [`${toolName} ${kebab} search "query text" --limit 10 --fields id,searchScore`],
-              }]
-            : []),
+          ...buildSearchExamples(skillSpecialGroups, toolName, kebab),
           {
             description: `Create a ${singularName}`,
             code: [
@@ -763,6 +761,7 @@ export function generateMultiTargetReadme(
       }
       const mtSpecialGroups = categorizeSpecialFields(table, registry);
       lines.push(...buildSpecialFieldsMarkdown(mtSpecialGroups));
+      lines.push(...buildSearchExamplesMarkdown(mtSpecialGroups, toolName, `${tgt.name}:${kebab}`));
       lines.push('');
     }
 
@@ -1096,12 +1095,7 @@ export function generateMultiTargetSkills(
               description: `List ${singularName} records with filtering and ordering`,
               code: [`${toolName} ${cmd} list --where.${pk.name}.equalTo <value> --orderBy ${pk.name.replace(/([A-Z])/g, '_$1').toUpperCase()}_ASC`],
             },
-            ...(mtSkillSpecialGroups.some((g) => g.category === 'search' || g.category === 'embedding')
-              ? [{
-                  description: `Search ${singularName} records`,
-                  code: [`${toolName} ${cmd} search "query text" --limit 10 --fields id,searchScore`],
-                }]
-              : []),
+            ...buildSearchExamples(mtSkillSpecialGroups, toolName, cmd),
             {
               description: `Create a ${singularName}`,
               code: [

graphql/codegen/src/core/codegen/cli/index.ts

@@ -14,7 +14,7 @@ import {
   generateMultiTargetContextCommand,
 } from './infra-generator';
 import { generateTableCommand } from './table-command-generator';
-import { generateUtilsFile, generateNodeFetchFile, generateEntryPointFile } from './utils-generator';
+import { generateUtilsFile, generateNodeFetchFile, generateEntryPointFile, generateEmbedderFile } from './utils-generator';
 
 export interface GenerateCliOptions {
   tables: Table[];
@@ -59,6 +59,14 @@ export function generateCli(options: GenerateCliOptions): GenerateCliResult {
   const utilsFile = generateUtilsFile();
   files.push(utilsFile);
 
+  // Generate embedder module if any table has vector embedding fields
+  const hasAnyEmbeddings = tables.some((t) =>
+    t.fields.some((f) => f.type.gqlType === 'Vector' || f.type.gqlType === '[Float]'),
+  );
+  if (hasAnyEmbeddings) {
+    files.push(generateEmbedderFile());
+  }
+
   // Generate node HTTP adapter if configured (for *.localhost subdomain routing)
   if (useNodeHttpAdapter) {
     files.push(generateNodeFetchFile());
@@ -180,6 +188,16 @@ export function generateMultiTargetCli(
   const utilsFile = generateUtilsFile();
   files.push(utilsFile);
 
+  // Generate embedder module if any target has tables with vector embedding fields
+  const hasAnyMtEmbeddings = targets.some((tgt) =>
+    tgt.tables.some((t) =>
+      t.fields.some((f) => f.type.gqlType === 'Vector' || f.type.gqlType === '[Float]'),
+    ),
+  );
+  if (hasAnyMtEmbeddings) {
+    files.push(generateEmbedderFile());
+  }
+
   // Generate node HTTP adapter if configured (for *.localhost subdomain routing)
   if (options.nodeHttpAdapter) {
     files.push(generateNodeFetchFile());
@@ -299,5 +317,5 @@ export {
 export type { MultiTargetDocsInput } from './docs-generator';
 export { resolveDocsConfig } from '../docs-utils';
 export type { GeneratedDocFile } from '../docs-utils';
-export { generateUtilsFile, generateEntryPointFile } from './utils-generator';
+export { generateUtilsFile, generateEntryPointFile, generateEmbedderFile } from './utils-generator';
 export type { GeneratedFile, MultiTargetExecutorInput } from './executor-generator';