@forwardimpact/libcodegen 0.1.43 → 0.1.45

package/README.md

@@ -0,0 +1,13 @@
+# libcodegen
+
+Protocol Buffer code generation utilities.
+
+## Getting Started
+
+```sh
+npx fit-codegen --all
+```
+
+```js
+import { CodegenTypes, CodegenServices, CodegenDefinitions } from '@forwardimpact/libcodegen';
+```

package/bin/fit-codegen.js

@@ -16,6 +16,7 @@ import {
   CodegenTypes,
   CodegenServices,
   CodegenDefinitions,
+  CodegenMetadata,
 } from "@forwardimpact/libcodegen";
 import { createStorage } from "@forwardimpact/libstorage";
 
@@ -39,6 +40,10 @@ const definition = {
       type: "boolean",
       description: "Generate service definitions only",
     },
+    metadata: {
+      type: "boolean",
+      description: "Generate field metadata only",
+    },
     help: { type: "boolean", short: "h", description: "Show this help" },
     version: { type: "boolean", description: "Show version" },
     json: { type: "boolean", description: "Output help as JSON" },
@@ -102,9 +107,14 @@ function parseFlags() {
     doServices: doAll || values.service,
     doClients: doAll || values.client,
     doDefinitions: doAll || values.definition,
+    doMetadata: doAll || values.metadata,
     hasGenerationFlags() {
       return (
-        this.doTypes || this.doServices || this.doClients || this.doDefinitions
+        this.doTypes ||
+        this.doServices ||
+        this.doClients ||
+        this.doDefinitions ||
+        this.doMetadata
       );
     },
   };
@@ -174,6 +184,7 @@ function createCodegen(
     types: new CodegenTypes(base),
     services: new CodegenServices(base),
     definitions: new CodegenDefinitions(base),
+    metadata: new CodegenMetadata(base),
   };
 }
 
@@ -237,6 +248,7 @@ function printSummary(sourcePath, flags) {
     flags.doServices && "services",
     flags.doClients && "clients",
     flags.doDefinitions && "definitions",
+    flags.doMetadata && "metadata",
   ].filter(Boolean);
   process.stdout.write(
     `\nCode generation complete (${generated.join(", ")}).\n`,
@@ -265,6 +277,9 @@ async function executeGeneration(codegens, sourcePath, flags) {
   if (flags.doDefinitions) {
     tasks.push(codegens.definitions.run(sourcePath));
   }
+  if (flags.doMetadata) {
+    tasks.push(codegens.metadata.run(sourcePath));
+  }
 
   await Promise.all(tasks);
 
@@ -294,7 +309,7 @@ async function runCodegen(protoDirs, projectRoot, finder) {
 
   if (!parsedFlags.hasGenerationFlags()) {
     cli.usageError(
-      "no generation flags specified (use --all, --type, --service, --client, or --definition)",
+      "no generation flags specified (use --all, --type, --service, --client, --definition, or --metadata)",
     );
     process.exit(2);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libcodegen",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "description": "Protocol Buffer code generation utilities for Guide",
   "license": "Apache-2.0",
   "author": "D. Olsson <hi@senzilla.io>",

package/src/base.js

@@ -1,5 +1,31 @@
 import { execFile } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import protobuf from "protobufjs";
+
+/** Convert camelCase to snake_case (protobufjs normalizes field names) */
+function camelToSnake(str) {
+  return str.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+
+// Protobufjs scalar type names are already human-readable (string, int32, bool, etc.)
+// so most pass through as-is. This map handles any aliases needed.
+const PBJS_TYPE_MAP = {
+  string: "string",
+  int32: "int32",
+  int64: "int64",
+  uint32: "uint32",
+  uint64: "uint64",
+  sint32: "sint32",
+  sint64: "sint64",
+  fixed32: "fixed32",
+  fixed64: "fixed64",
+  sfixed32: "sfixed32",
+  sfixed64: "sfixed64",
+  float: "float",
+  double: "double",
+  bool: "bool",
+  bytes: "bytes",
+};
 
 /**
  * Base class for code generation utilities providing shared functionality
@@ -242,6 +268,75 @@ export class CodegenBase {
     };
   }
 
+  /**
+   * Parse metadata for a proto file: service methods with request type fields.
+   * Uses protobufjs for field types, optionality, and comments.
+   * @param {string} protoPath - Absolute path to .proto file
+   * @returns {{packageName:string, serviceName:string, methods:object}|null}
+   */
+  parseMetadata(protoPath) {
+    const parsed = this.parseProtoFile(protoPath);
+    if (!parsed) return null;
+
+    const { packageName, serviceName, methods: parsedMethods } = parsed;
+
+    // Load with protobufjs for field types, optionality, and comments
+    const root = new protobuf.Root();
+    root.resolvePath = (origin, target) => {
+      for (const dir of this.includeDirs) {
+        const candidate = this.#path.join(dir, target);
+        if (this.#fs.existsSync(candidate)) return candidate;
+      }
+      return target;
+    };
+    root.loadSync(protoPath, { alternateCommentMode: true });
+    root.resolveAll();
+
+    const methods = {};
+    for (const method of parsedMethods) {
+      const reqTypeName = `${method.requestTypeNamespace}.${method.requestType}`;
+      let pbjsType = null;
+      try {
+        pbjsType = root.lookupType(reqTypeName);
+      } catch {
+        try {
+          pbjsType = root.lookupType(method.requestType);
+        } catch {
+          // no type found
+        }
+      }
+
+      const fields = {};
+      if (pbjsType) {
+        for (const [camelName, field] of Object.entries(pbjsType.fields)) {
+          const name = camelToSnake(camelName);
+          // Map protobufjs type to simple type name
+          const typeName = field.resolvedType
+            ? "message"
+            : PBJS_TYPE_MAP[field.type] || field.type;
+
+          // proto3 optional uses synthetic oneofs named _fieldname
+          const hasOptionalKeyword =
+            pbjsType.oneofs?.[`_${camelName}`] !== undefined;
+
+          fields[name] = {
+            type: typeName,
+            optional: hasOptionalKeyword,
+            repeated: field.repeated || false,
+            description: field.comment || null,
+          };
+        }
+      }
+
+      methods[method.name] = {
+        requestType: `${method.requestTypeNamespace}.${method.requestType}`,
+        fields,
+      };
+    }
+
+    return { packageName, serviceName, methods };
+  }
+
   /**
    * Find the namespace for a given type by comparing structure
    * @param {object} typeToFind - The type definition to find namespace for

package/src/index.js

@@ -3,3 +3,4 @@ export { CodegenBase } from "./base.js";
 export { CodegenTypes } from "./types.js";
 export { CodegenServices } from "./services.js";
 export { CodegenDefinitions } from "./definitions.js";
+export { CodegenMetadata } from "./metadata.js";

package/src/metadata.js

@@ -0,0 +1,50 @@
+/**
+ * Generates field metadata for all service methods from proto files.
+ * Output is a static ESM module consumed by libmcp for schema generation.
+ */
+export class CodegenMetadata {
+  #base;
+
+  /**
+   * @param {object} base - CodegenBase instance providing shared utilities
+   */
+  constructor(base) {
+    if (!base) throw new Error("CodegenBase instance is required");
+    this.#base = base;
+  }
+
+  /**
+   * Generate metadata.js containing field descriptors for all service methods.
+   * @param {string} generatedPath - Path to generated code directory
+   * @returns {Promise<void>}
+   */
+  async run(generatedPath) {
+    if (!generatedPath) throw new Error("generatedPath is required");
+
+    const protoFiles = this.#base
+      .collectProtoFiles({ includeTools: false })
+      .filter((file) => !file.endsWith(this.#base.path.sep + "common.proto"));
+
+    const metadata = {};
+
+    for (const protoFile of protoFiles) {
+      const parsed = this.#base.parseMetadata(protoFile);
+      if (!parsed) continue;
+
+      const serviceKey = `${parsed.packageName}.${parsed.serviceName}`;
+      metadata[serviceKey] = parsed.methods;
+    }
+
+    const typesDir = this.#base.path.join(generatedPath, "types");
+    this.#base.fs.mkdirSync(typesDir, { recursive: true });
+
+    const content =
+      `/** @generated by fit-codegen — do not edit */\n` +
+      `export const metadata = ${JSON.stringify(metadata, null, 2)};\n`;
+
+    this.#base.fs.writeFileSync(
+      this.#base.path.join(typesDir, "metadata.js"),
+      content,
+    );
+  }
+}