feat(codegen): add CLI command generator with agent-ready docs from GraphQL schema

graphql/codegen/package.json

@@ -68,6 +68,7 @@
     "inflekt": "^0.3.1",
     "inquirerer": "^4.4.0",
     "jiti": "^2.6.1",
+    "komoji": "^0.8.0",
     "oxfmt": "^0.26.0",
     "pg-cache": "workspace:^",
     "pg-env": "workspace:^",

graphql/codegen/src/core/codegen/barrel.ts

@@ -195,14 +195,15 @@ export interface RootBarrelOptions {
   hasTypes?: boolean;
   hasHooks?: boolean;
   hasOrm?: boolean;
+  hasCli?: boolean;
 }
 
 /**
  * Generate the root index.ts barrel file for the output directory.
  * Re-exports from subdirectories based on which generators are enabled.
  */
 export function generateRootBarrel(options: RootBarrelOptions = {}): string {
-  const { hasTypes = false, hasHooks = false, hasOrm = false } = options;
+  const { hasTypes = false, hasHooks = false, hasOrm = false, hasCli = false } = options;
   const statements: t.Statement[] = [];
 
   if (hasTypes) {
@@ -214,8 +215,11 @@ export function generateRootBarrel(options: RootBarrelOptions = {}): string {
   if (hasOrm) {
     statements.push(exportAllFrom('./orm'));
   }
+  if (hasCli) {
+    statements.push(exportAllFrom('./cli'));
+  }
 
-  // Add file header as leading comment on first statement
+  // Add file headeras leading comment on first statement
   if (statements.length > 0) {
     addJSDocComment(statements[0], [
       'Generated SDK - auto-generated, do not edit',

graphql/codegen/src/core/codegen/cli/arg-mapper.ts

@@ -0,0 +1,139 @@
+import * as t from '@babel/types';
+
+import type { CleanArgument, CleanTypeRef } from '../../../types/schema';
+
+function unwrapNonNull(typeRef: CleanTypeRef): { inner: CleanTypeRef; required: boolean } {
+  if (typeRef.kind === 'NON_NULL' && typeRef.ofType) {
+    return { inner: typeRef.ofType, required: true };
+  }
+  return { inner: typeRef, required: false };
+}
+
+function resolveBaseType(typeRef: CleanTypeRef): CleanTypeRef {
+  if ((typeRef.kind === 'NON_NULL' || typeRef.kind === 'LIST') && typeRef.ofType) {
+    return resolveBaseType(typeRef.ofType);
+  }
+  return typeRef;
+}
+
+export function buildQuestionObject(arg: CleanArgument): t.ObjectExpression {
+  const { inner, required } = unwrapNonNull(arg.type);
+  const base = resolveBaseType(arg.type);
+  const props: t.ObjectProperty[] = [];
+
+  if (base.kind === 'ENUM' && base.enumValues && base.enumValues.length > 0) {
+    props.push(
+      t.objectProperty(t.identifier('type'), t.stringLiteral('autocomplete')),
+    );
+    props.push(
+      t.objectProperty(t.identifier('name'), t.stringLiteral(arg.name)),
+    );
+    props.push(
+      t.objectProperty(
+        t.identifier('message'),
+        t.stringLiteral(arg.description || arg.name),
+      ),
+    );
+    props.push(
+      t.objectProperty(
+        t.identifier('options'),
+        t.arrayExpression(base.enumValues.map((v) => t.stringLiteral(v))),
+      ),
+    );
+  } else if (base.kind === 'SCALAR' && base.name === 'Boolean') {
+    props.push(
+      t.objectProperty(t.identifier('type'), t.stringLiteral('confirm')),
+    );
+    props.push(
+      t.objectProperty(t.identifier('name'), t.stringLiteral(arg.name)),
+    );
+    props.push(
+      t.objectProperty(
+        t.identifier('message'),
+        t.stringLiteral(arg.description || arg.name),
+      ),
+    );
+    props.push(
+      t.objectProperty(t.identifier('default'), t.booleanLiteral(false)),
+    );
+  } else if (
+    base.kind === 'SCALAR' &&
+    (base.name === 'Int' || base.name === 'Float')
+  ) {
+    props.push(
+      t.objectProperty(t.identifier('type'), t.stringLiteral('text')),
+    );
+    props.push(
+      t.objectProperty(t.identifier('name'), t.stringLiteral(arg.name)),
+    );
+    props.push(
+      t.objectProperty(
+        t.identifier('message'),
+        t.stringLiteral(arg.description || `${arg.name} (number)`),
+      ),
+    );
+  } else if (inner.kind === 'INPUT_OBJECT' && inner.inputFields) {
+    return buildInputObjectQuestion(arg.name, inner, required);
+  } else {
+    props.push(
+      t.objectProperty(t.identifier('type'), t.stringLiteral('text')),
+    );
+    props.push(
+      t.objectProperty(t.identifier('name'), t.stringLiteral(arg.name)),
+    );
+    props.push(
+      t.objectProperty(
+        t.identifier('message'),
+        t.stringLiteral(arg.description || arg.name),
+      ),
+    );
+  }
+
+  if (required) {
+    props.push(
+      t.objectProperty(t.identifier('required'), t.booleanLiteral(true)),
+    );
+  }
+
+  return t.objectExpression(props);
+}
+
+function buildInputObjectQuestion(
+  _name: string,
+  typeRef: CleanTypeRef,
+  _required: boolean,
+): t.ObjectExpression {
+  if (typeRef.inputFields && typeRef.inputFields.length > 0) {
+    const firstField = typeRef.inputFields[0];
+    return buildQuestionObject(firstField);
+  }
+  return t.objectExpression([
+    t.objectProperty(t.identifier('type'), t.stringLiteral('text')),
+    t.objectProperty(t.identifier('name'), t.stringLiteral(_name)),
+    t.objectProperty(
+      t.identifier('message'),
+      t.stringLiteral(_name),
+    ),
+  ]);
+}
+
+export function buildQuestionsArray(args: CleanArgument[]): t.ArrayExpression {
+  const questions: t.Expression[] = [];
+  for (const arg of args) {
+    const base = resolveBaseType(arg.type);
+    const { inner } = unwrapNonNull(arg.type);
+
+    if (inner.kind === 'INPUT_OBJECT' && inner.inputFields) {
+      for (const field of inner.inputFields) {
+        questions.push(buildQuestionObject(field));
+      }
+    } else if (base.kind === 'INPUT_OBJECT' && base.inputFields) {
+      for (const field of base.inputFields) {
+        questions.push(buildQuestionObject(field));
+      }
+    } else {
+      questions.push(buildQuestionObject(arg));
+    }
+  }
+  return t.arrayExpression(questions);
+}