@forwardimpact/libcodegen 0.1.27

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Dick Olsson
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/base.js

@@ -0,0 +1,310 @@
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Base class for code generation utilities providing shared functionality
+ * Implements dependency injection pattern with explicit validation
+ */
+export class CodegenBase {
+  #projectRoot;
+  #path;
+  #mustache;
+  #protoLoader;
+  #fs;
+
+  /**
+   * Creates a new codegen base instance with dependency injection
+   * @param {string} projectRoot - Project root directory path
+   * @param {object} path - Path module for file operations
+   * @param {object} mustache - Mustache template rendering module
+   * @param {object} protoLoader - Protocol buffer loader module
+   * @param {object} fs - File system module (sync operations only)
+   */
+  constructor(projectRoot, path, mustache, protoLoader, fs) {
+    if (!projectRoot) throw new Error("projectRoot is required");
+    if (!path) throw new Error("path module is required");
+    if (!mustache) throw new Error("mustache module is required");
+    if (!protoLoader) throw new Error("protoLoader module is required");
+    if (!fs) throw new Error("fs module is required");
+
+    this.#projectRoot = projectRoot;
+    this.#path = path;
+    this.#mustache = mustache;
+    this.#protoLoader = protoLoader;
+    this.#fs = fs;
+  }
+
+  /**
+   * Collect all proto files from project proto directory and tools directory
+   * @param {object} opts - Collection options
+   * @param {boolean} opts.includeTools - Whether to include tool proto files
+   * @returns {string[]} Array of absolute proto file paths
+   */
+  collectProtoFiles(opts = {}) {
+    const { includeTools = true } = opts;
+    const protoDir = this.#path.join(this.#projectRoot, "proto");
+
+    const discovered = this.#fs
+      .readdirSync(protoDir)
+      .filter((f) => f.endsWith(".proto"))
+      .sort();
+
+    const ordered = discovered.includes("common.proto")
+      ? [
+          this.#path.join(protoDir, "common.proto"),
+          ...discovered
+            .filter((f) => f !== "common.proto")
+            .map((f) => this.#path.join(protoDir, f)),
+        ]
+      : discovered.map((f) => this.#path.join(protoDir, f));
+
+    if (includeTools) {
+      try {
+        ordered.push(
+          ...this.#fs
+            .readdirSync(this.#path.join(this.#projectRoot, "tools"))
+            .filter((f) => f.endsWith(".proto"))
+            .map((f) => this.#path.join(this.#projectRoot, "tools", f)),
+        );
+      } catch {
+        // tools directory may not exist; ignore
+      }
+    }
+
+    return ordered;
+  }
+
+  /**
+   * Load mustache template for given kind
+   * @param {"service"|"client"|"exports"|"definition"|"definitions-exports"|"services-exports"} kind - Template kind
+   * @returns {string} Template content
+   */
+  loadTemplate(kind) {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = this.#path.dirname(__filename);
+    const templatePath = this.#path.join(
+      __dirname,
+      "templates",
+      `${kind}.js.mustache`,
+    );
+
+    if (!this.#fs.existsSync(templatePath)) {
+      throw new Error(`Missing ${kind}.js.mustache template`);
+    }
+    return this.#fs.readFileSync(templatePath, "utf8");
+  }
+
+  /**
+   * Render mustache template with given data
+   * @param {string} template - Template content
+   * @param {object} data - Template data
+   * @returns {string} Rendered content
+   */
+  renderTemplate(template, data) {
+    return this.#mustache.render(template, data);
+  }
+
+  /**
+   * Run a command with arguments and options
+   * @param {string} cmd - Command to execute
+   * @param {string[]} args - Command-line arguments
+   * @param {object} [opts] - Child process options
+   * @returns {Promise<void>} Resolves when the command completes successfully
+   */
+  run(cmd, args, opts = {}) {
+    return new Promise((resolvePromise, reject) => {
+      const child = execFile(
+        cmd,
+        args,
+        { stdio: "inherit", ...opts },
+        (err) => {
+          if (err) reject(err);
+          else resolvePromise();
+        },
+      );
+      child.on("error", reject);
+    });
+  }
+
+  /**
+   * Convert string to PascalCase
+   * @param {string} str - String to convert
+   * @returns {string} PascalCase string
+   */
+  pascalCase(str) {
+    return str
+      .split(/[-_\s]+/)
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join("");
+  }
+
+  /**
+   * Parse a .proto file to extract a single service definition and method shapes
+   * @param {string} protoPath - Absolute path to .proto file
+   * @returns {{packageName:string, serviceName:string, methods:Array, namespaceName:string}|null} Parsed service info
+   */
+  parseProtoFile(protoPath) {
+    const def = this.#protoLoader.loadSync(protoPath, {
+      includeDirs: [this.#path.dirname(protoPath)],
+      keepCase: true,
+    });
+
+    const serviceKey = Object.keys(def).find((key) => {
+      const val = def[key];
+      if (!val || typeof val !== "object") return false;
+      const methods = Object.values(val);
+      return (
+        methods.length > 0 &&
+        methods.every(
+          (m) =>
+            m &&
+            typeof m === "object" &&
+            "requestType" in m &&
+            "responseType" in m,
+        )
+      );
+    });
+
+    if (!serviceKey) return null; // Indicate no service for this proto (pure message proto)
+
+    const serviceDef = def[serviceKey];
+    const parts = serviceKey.split(".");
+    const serviceName = parts[parts.length - 1];
+    const packageName = parts.slice(0, -1).join(".");
+
+    const methods = Object.entries(serviceDef).map(
+      ([name, method], index, array) => {
+        const req = method.requestType.type;
+        const res = method.responseType.type;
+
+        return {
+          name,
+          requestType: req.name,
+          responseType: res.name,
+          requestTypeNamespace: this.findTypeNamespace(req, def, packageName),
+          responseTypeNamespace: this.findTypeNamespace(res, def, packageName),
+          paramName: "req",
+          isLast: index === array.length - 1,
+          responseStream: !!method.responseStream,
+          requestStream: !!method.requestStream,
+        };
+      },
+    );
+
+    // Collect all unique namespaces needed for imports
+    const namespaces = new Set([
+      packageName,
+      ...methods.flatMap((m) => [
+        m.requestTypeNamespace,
+        m.responseTypeNamespace,
+      ]),
+    ]);
+
+    // Filter out well-known google namespaces as they are not in libtype
+    const filteredNamespaces = Array.from(namespaces).filter(
+      (ns) => !ns.startsWith("google"),
+    );
+
+    return {
+      packageName,
+      serviceName,
+      methods,
+      namespaceName: packageName,
+      importNamespaces: filteredNamespaces.map((ns, index, array) => ({
+        name: ns,
+        isLast: index === array.length - 1,
+      })),
+    };
+  }
+
+  /**
+   * Find the namespace for a given type by comparing structure
+   * @param {object} typeToFind - The type definition to find namespace for
+   * @param {object} allTypes - All available type definitions
+   * @param {string} fallbackPackage - Fallback package name
+   * @returns {string} The namespace string for the type
+   */
+  findTypeNamespace(typeToFind, allTypes, fallbackPackage) {
+    // Find matching type definition by structure comparison
+    for (const [key, typeDef] of Object.entries(allTypes)) {
+      if (typeDef.type && typeDef.type.name === typeToFind.name) {
+        const typeFields = typeDef.type.field || [];
+        const targetFields = typeToFind.field || [];
+
+        // Compare fields to see if structures match
+        const fieldsMatch =
+          typeFields.length === targetFields.length &&
+          typeFields.every(
+            (field, i) =>
+              field.name === targetFields[i].name &&
+              field.type === targetFields[i].type &&
+              field.typeName === targetFields[i].typeName,
+          );
+
+        if (fieldsMatch) {
+          const parts = key.split(".");
+          return parts.length > 1
+            ? parts.slice(0, -1).join(".")
+            : fallbackPackage;
+        }
+      }
+    }
+    return fallbackPackage;
+  }
+
+  /**
+   * Render and write a service/client artifact for a given proto into a service dir
+   * @param {"service"|"client"|"definition"} kind - Artifact kind to generate
+   * @param {string} protoPath - Absolute path to .proto file
+   * @param {string} outputDir - Absolute directory path for output
+   * @param {string} [filename] - Optional custom filename (defaults to kind.js)
+   * @returns {Promise<void>}
+   */
+  async generateArtifact(kind, protoPath, outputDir, filename) {
+    const parsed = this.parseProtoFile(protoPath);
+    if (!parsed) return; // Skip non-service proto
+
+    const {
+      packageName,
+      serviceName,
+      methods,
+      namespaceName,
+      importNamespaces,
+    } = parsed;
+    const rendered = this.#mustache.render(this.loadTemplate(kind), {
+      packageName,
+      serviceName,
+      methods,
+      namespaceName,
+      importNamespaces,
+      className: `${serviceName}${kind === "service" ? "Base" : kind === "client" ? "Client" : "ServiceDefinition"}`,
+    });
+
+    const jsFile = this.#path.join(outputDir, filename || `${kind}.js`);
+    this.#fs.writeFileSync(jsFile, rendered);
+  }
+
+  /**
+   * Get path module instance
+   * @returns {object} Path module
+   */
+  get path() {
+    return this.#path;
+  }
+
+  /**
+   * Get fs module instance
+   * @returns {object} File system module
+   */
+  get fs() {
+    return this.#fs;
+  }
+
+  /**
+   * Get project root path
+   * @returns {string} Project root directory path
+   */
+  get projectRoot() {
+    return this.#projectRoot;
+  }
+}

package/bin/fit-codegen.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+import { parseArgs } from "node:util";
+
+import protoLoader from "@grpc/proto-loader";
+import mustache from "mustache";
+
+import { Finder } from "@forwardimpact/libutil";
+import { Logger } from "@forwardimpact/libtelemetry";
+import {
+  CodegenBase,
+  CodegenTypes,
+  CodegenServices,
+  CodegenDefinitions,
+} from "@forwardimpact/libcodegen";
+import { createStorage } from "@forwardimpact/libstorage";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Create tar.gz bundle of all directories inside sourcePath
+ * @param {string} sourcePath - Path containing directories to bundle
+ */
+async function createBundle(sourcePath) {
+  const bundlePath = path.join(sourcePath, "bundle.tar.gz");
+
+  // Get all directories in sourcePath
+  const entries = fs.readdirSync(sourcePath, { withFileTypes: true });
+  const directories = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+
+  if (directories.length === 0) {
+    return; // No directories to bundle
+  }
+
+  // Create tar.gz archive using system tar command
+  try {
+    const directoriesArg = directories.join(" ");
+    execSync(`tar -czf "${bundlePath}" -C "${sourcePath}" ${directoriesArg}`, {
+      stdio: "pipe",
+    });
+  } catch (error) {
+    throw new Error(`Failed to create bundle: ${error.message}`);
+  }
+}
+
+/**
+ * Print CLI usage help
+ */
+function printUsage() {
+  process.stdout.write(
+    [
+      "Usage:",
+      `  npx fit-codegen --all                              # Generate all code`,
+      `  npx fit-codegen --type                             # Generate protobuf types only`,
+      `  npx fit-codegen --service                          # Generate service bases only`,
+      `  npx fit-codegen --client                           # Generate clients only`,
+      `  npx fit-codegen --definition                       # Generate service definitions only`,
+    ].join("\n") + "\n",
+  );
+}
+
+/**
+ * Parse command line flags
+ * @returns {object} Parsed flags with convenience methods
+ */
+function parseFlags() {
+  const { values } = parseArgs({
+    options: {
+      all: {
+        type: "boolean",
+        default: false,
+      },
+      type: {
+        type: "boolean",
+        default: false,
+      },
+      service: {
+        type: "boolean",
+        default: false,
+      },
+      client: {
+        type: "boolean",
+        default: false,
+      },
+      definition: {
+        type: "boolean",
+        default: false,
+      },
+    },
+  });
+
+  const doAll = values.all;
+  return {
+    doTypes: doAll || values.type,
+    doServices: doAll || values.service,
+    doClients: doAll || values.client,
+    doDefinitions: doAll || values.definition,
+    hasGenerationFlags() {
+      return (
+        this.doTypes || this.doServices || this.doClients || this.doDefinitions
+      );
+    },
+  };
+}
+
+/**
+ * Create codegen instances
+ * @param {string} projectRoot - Project root directory path
+ * @param {object} path - Path module
+ * @param {object} mustache - Mustache module
+ * @param {object} protoLoader - Proto loader module
+ * @param {object} fs - File system module
+ * @returns {object} Codegen instances
+ */
+function createCodegen(projectRoot, path, mustache, protoLoader, fs) {
+  const base = new CodegenBase(projectRoot, path, mustache, protoLoader, fs);
+  return {
+    types: new CodegenTypes(base),
+    services: new CodegenServices(base),
+    definitions: new CodegenDefinitions(base),
+  };
+}
+
+/**
+ * Execute code generation tasks
+ * @param {object} codegens - Codegen instances
+ * @param {string} sourcePath - Generated source path
+ * @param {object} flags - Parsed flags
+ * @returns {Promise<void>}
+ */
+async function executeGeneration(codegens, sourcePath, flags) {
+  const tasks = [];
+
+  if (flags.doTypes) {
+    tasks.push(codegens.types.run(sourcePath));
+  }
+  if (flags.doServices) {
+    tasks.push(codegens.services.runForKind("service", sourcePath));
+  }
+  if (flags.doClients) {
+    tasks.push(codegens.services.runForKind("client", sourcePath));
+  }
+  if (flags.doDefinitions) {
+    tasks.push(codegens.definitions.run(sourcePath));
+  }
+
+  await Promise.all(tasks);
+
+  // Generate exports if needed
+  const needsServicesExports = flags.doServices || flags.doClients;
+  const needsDefinitionsExports = flags.doDefinitions;
+
+  const exportTasks = [];
+  if (needsServicesExports) {
+    exportTasks.push(codegens.services.runExports(sourcePath));
+  }
+  if (needsDefinitionsExports) {
+    exportTasks.push(codegens.definitions.runExports(sourcePath));
+  }
+
+  await Promise.all(exportTasks);
+}
+
+/**
+ * Simplified main function
+ * @param {string} projectRoot - Project root directory path
+ * @param {object} finder - Finder instance for path management
+ */
+async function runCodegen(projectRoot, finder) {
+  const parsedFlags = parseFlags();
+
+  if (!parsedFlags.hasGenerationFlags()) {
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const generatedStorage = createStorage("generated", "local");
+  const sourcePath = generatedStorage.path();
+
+  await generatedStorage.ensureBucket();
+
+  const codegens = createCodegen(projectRoot, path, mustache, protoLoader, fs);
+  await executeGeneration(codegens, sourcePath, parsedFlags);
+
+  await finder.createPackageSymlinks(sourcePath);
+  await createBundle(sourcePath);
+}
+
+/**
+ * Find the monorepo root directory (the one with workspaces)
+ * @param {string} startPath - Starting directory path
+ * @returns {string} Project root directory path
+ */
+function findMonorepoRoot(startPath) {
+  let current = startPath;
+  for (let depth = 0; depth < 10; depth++) {
+    const packageJsonPath = path.join(current, "package.json");
+    if (fs.existsSync(packageJsonPath)) {
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+      // Check if this package.json has workspaces (indicates monorepo root)
+      if (packageJson.workspaces) {
+        return current;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  throw new Error("Could not find monorepo root");
+}
+
+/**
+ * CLI entry point
+ */
+async function main() {
+  try {
+    const logger = new Logger("codegen");
+    const finder = new Finder(fsAsync, logger, process);
+    const projectRoot = findMonorepoRoot(__dirname);
+
+    await runCodegen(projectRoot, finder);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`Unexpected error: ${err.message}\n`);
+  process.exit(1);
+});

package/definitions.js

@@ -0,0 +1,82 @@
+/**
+ * Handles service definition generation from protobuf files
+ * Specializes in gRPC service definition creation for runtime registration
+ */
+export class CodegenDefinitions {
+  #base;
+
+  /**
+   * Creates a new definitions generator with base functionality
+   * @param {object} base - CodegenBase instance providing shared utilities
+   */
+  constructor(base) {
+    if (!base) throw new Error("CodegenBase instance is required");
+    this.#base = base;
+  }
+
+  /**
+   * Generate service definitions for all proto files
+   * @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: true })
+      .filter((file) => !file.endsWith(this.#base.path.sep + "common.proto"));
+
+    const definitionsDir = this.#base.path.join(generatedPath, "definitions");
+    this.#base.fs.mkdirSync(definitionsDir, { recursive: true });
+
+    for (const protoFile of protoFiles) {
+      const basename = this.#base.path.basename(protoFile, ".proto");
+      await this.#base.generateArtifact(
+        "definition",
+        protoFile,
+        definitionsDir,
+        `${basename}.js`,
+      );
+    }
+
+    // Generate the definitions exports file
+    await this.runExports(generatedPath);
+  }
+
+  /**
+   * Generate definitions exports file with all service definitions
+   * @param {string} generatedPath - Path to generated code directory
+   * @returns {Promise<void>}
+   */
+  async runExports(generatedPath) {
+    if (!generatedPath) throw new Error("generatedPath is required");
+    const definitionsDir = this.#base.path.join(generatedPath, "definitions");
+    const outputFile = this.#base.path.join(definitionsDir, "exports.js");
+
+    this.#base.fs.mkdirSync(this.#base.path.dirname(outputFile), {
+      recursive: true,
+    });
+
+    const definitions = [];
+
+    if (this.#base.fs.existsSync(definitionsDir)) {
+      for (const file of this.#base.fs.readdirSync(definitionsDir)) {
+        if (!file.endsWith(".js") || file === "exports.js") continue;
+
+        const serviceName = this.#base.path.basename(file, ".js");
+        const pascalServiceName = this.#base.pascalCase(serviceName);
+        definitions.push({
+          name: `${pascalServiceName}ServiceDefinition`,
+          serviceName: serviceName,
+        });
+      }
+    }
+
+    const template = this.#base.loadTemplate("definitions-exports");
+    const content = this.#base.renderTemplate(template, {
+      definitions,
+      hasDefinitions: definitions.length > 0,
+    });
+
+    this.#base.fs.writeFileSync(outputFile, content);
+  }
+}

package/index.js

@@ -0,0 +1,5 @@
+// Export the new modular classes
+export { CodegenBase } from "./base.js";
+export { CodegenTypes } from "./types.js";
+export { CodegenServices } from "./services.js";
+export { CodegenDefinitions } from "./definitions.js";

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@forwardimpact/libcodegen",
+  "version": "0.1.27",
+  "description": "Protocol Buffer code generation utilities for Guide",
+  "license": "Apache-2.0",
+  "author": "D. Olsson <hi@senzilla.io>",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "fit-codegen": "./bin/fit-codegen.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@grpc/proto-loader": "^0.8.0",
+    "mustache": "^4.2.0",
+    "protobufjs": "^7.5.4",
+    "protobufjs-cli": "^1.2.0"
+  },
+  "devDependencies": {
+    "@forwardimpact/libharness": "^0.1.5"
+  }
+}

package/services.js

@@ -0,0 +1,94 @@
+/**
+ * Handles service and client generation from protobuf files
+ * Specializes in gRPC service base classes and client generation
+ */
+export class CodegenServices {
+  #base;
+
+  /**
+   * Creates a new services generator with base functionality
+   * @param {object} base - CodegenBase instance providing shared utilities
+   */
+  constructor(base) {
+    if (!base) throw new Error("CodegenBase instance is required");
+    this.#base = base;
+  }
+
+  /**
+   * Generate service or client artifacts for all proto files
+   * @param {"service"|"client"} kind - Type of artifacts to generate
+   * @param {string} generatedPath - Path to generated code directory
+   * @returns {Promise<void>}
+   */
+  async runForKind(kind, generatedPath) {
+    if (!generatedPath) throw new Error("generatedPath is required");
+    const protoFiles = this.#base
+      .collectProtoFiles({ includeTools: true })
+      .filter((file) => !file.endsWith(this.#base.path.sep + "common.proto"));
+
+    for (const protoFile of protoFiles) {
+      const basename = this.#base.path.basename(protoFile, ".proto");
+      const outDir = this.#base.path.join(generatedPath, "services", basename);
+      this.#base.fs.mkdirSync(outDir, { recursive: true });
+      await this.#base.generateArtifact(kind, protoFile, outDir);
+    }
+  }
+
+  /**
+   * Generate services exports file with all service bases and clients
+   * @param {string} generatedPath - Path to generated code directory
+   * @returns {Promise<void>}
+   */
+  async runExports(generatedPath) {
+    if (!generatedPath) throw new Error("generatedPath is required");
+    const serviceDir = this.#base.path.join(generatedPath, "services");
+    const outputFile = this.#base.path.join(serviceDir, "exports.js");
+
+    this.#base.fs.mkdirSync(this.#base.path.dirname(outputFile), {
+      recursive: true,
+    });
+
+    const services = [];
+    const clients = [];
+
+    if (this.#base.fs.existsSync(serviceDir)) {
+      for (const dir of this.#base.fs.readdirSync(serviceDir)) {
+        const servicePath = this.#base.path.join(serviceDir, dir);
+        if (!this.#base.fs.statSync(servicePath).isDirectory()) continue;
+
+        const serviceName = this.#base.pascalCase(dir);
+        if (
+          this.#base.fs.existsSync(
+            this.#base.path.join(servicePath, "service.js"),
+          )
+        ) {
+          services.push({
+            name: `${serviceName}Base`,
+            path: `./${dir}/service.js`,
+          });
+        }
+        if (
+          this.#base.fs.existsSync(
+            this.#base.path.join(servicePath, "client.js"),
+          )
+        ) {
+          clients.push({
+            name: `${serviceName}Client`,
+            path: `./${dir}/client.js`,
+          });
+        }
+      }
+    }
+
+    const template = this.#base.loadTemplate("services-exports");
+
+    const content = this.#base.renderTemplate(template, {
+      services,
+      clients,
+      hasServices: services.length > 0,
+      hasClients: clients.length > 0,
+    });
+
+    this.#base.fs.writeFileSync(outputFile, content);
+  }
+}

package/templates/client.js.mustache

@@ -0,0 +1,70 @@
+/* eslint no-unused-vars: "off" */
+
+import { Client } from "@forwardimpact/librpc/client.js";
+import { createAuth, createGrpc } from "@forwardimpact/librpc/base.js";
+import { createObserver } from "@forwardimpact/libtelemetry";
+import { {{#importNamespaces}}{{name}}{{^isLast}}, {{/isLast}}{{/importNamespaces}} } from "@forwardimpact/libtype";
+
+/**
+ * Typed client for the {{serviceName}} gRPC service.
+ * Extends the `Client` class for shared gRPC client functionality.
+ */
+export class {{className}} extends Client {
+  /**
+   * Creates a new {{serviceName}} client instance
+   * @param {object} config - Service configuration
+   * @param {import("@forwardimpact/libtelemetry").Logger} [logger] - Optional logger instance
+   * @param {import("@forwardimpact/libtelemetry").Tracer} [tracer] - Optional tracer for distributed tracing
+   * @param {Function} [authFn] - Optional authentication function
+   */
+  constructor(config, logger = null, tracer = null, authFn = createAuth) {
+    super(config, logger, tracer, createObserver, createGrpc, authFn);
+  }
+
+{{#methods}}
+  {{#responseStream}}
+  /**
+   * Call the `{{name}}` RPC with request/response type conversion.
+   * @param { {{requestTypeNamespace}}.{{requestType}} } {{paramName}} - Typed request message.
+   * @returns { import("@grpc/grpc-js").ClientReadableStream<{{responseTypeNamespace}}.{{responseType}}> } Response stream emitting typed messages.
+   */
+  {{name}}({{paramName}}) {
+    // Type validation
+    if (!({{paramName}} instanceof {{requestTypeNamespace}}.{{requestType}})) {
+      throw new TypeError(
+        `{{name}}: Expected parameter to be instanceof {{requestTypeNamespace}}.{{requestType}}`,
+      );
+    }
+    
+    // Convert to plain object
+    const request = {{requestTypeNamespace}}.{{requestType}}.toObject({{paramName}});
+    
+    // Make gRPC call
+    return this.callStream("{{name}}", request, (res) => {{responseTypeNamespace}}.{{responseType}}.fromObject(res));
+  }
+  {{/responseStream}}
+  {{^responseStream}}
+  /**
+   * Call the `{{name}}` RPC with request/response type conversion.
+   * @param { {{requestTypeNamespace}}.{{requestType}} } {{paramName}} - Typed request message.
+   * @returns { Promise<{{responseTypeNamespace}}.{{responseType}}> } Typed response message.
+   */
+  async {{name}}({{paramName}}) {
+    // Type validation
+    if (!({{paramName}} instanceof {{requestTypeNamespace}}.{{requestType}})) {
+      throw new TypeError(
+        `{{name}}: Expected parameter to be instanceof {{requestTypeNamespace}}.{{requestType}}`,
+      );
+    }
+    
+    // Convert to plain object
+    const request = {{requestTypeNamespace}}.{{requestType}}.toObject({{paramName}});
+    
+    // Make gRPC call (tracing handled by base Client class)
+    return this.callUnary("{{name}}", request, (res) => {{responseTypeNamespace}}.{{responseType}}.fromObject(res));
+  }
+  {{/responseStream}}
+{{^isLast}}
+
+{{/isLast}}{{/methods}}
+}

package/templates/definition.js.mustache

@@ -0,0 +1,31 @@
+import { {{#importNamespaces}}{{name}}{{^isLast}}, {{/isLast}}{{/importNamespaces}} } from "@forwardimpact/libtype";
+
+/**
+ * Pre-compiled gRPC service definition for {{serviceName}}
+ * Generated at build time
+ */
+export const {{serviceName}}ServiceDefinition = {
+{{#methods}}
+  {{name}}: {
+    path: '/{{packageName}}.{{serviceName}}/{{name}}',
+    requestStream: {{requestStream}},
+    responseStream: {{responseStream}},
+    requestSerialize: (value) => {
+      return Buffer.from({{requestTypeNamespace}}.{{requestType}}.encode(value).finish());
+    },
+    requestDeserialize: (value) => {
+      return {{requestTypeNamespace}}.{{requestType}}.toObject(
+        {{requestTypeNamespace}}.{{requestType}}.decode(value)
+      );
+    },
+    responseSerialize: (value) => {
+      return Buffer.from({{responseTypeNamespace}}.{{responseType}}.encode(value).finish());
+    },
+    responseDeserialize: (value) => {
+      return {{responseTypeNamespace}}.{{responseType}}.toObject(
+        {{responseTypeNamespace}}.{{responseType}}.decode(value)
+      );
+    },
+  },
+{{/methods}}
+};

package/templates/definitions-exports.js.mustache

@@ -0,0 +1,31 @@
+// THIS FILE IS AUTO-GENERATED - DO NOT EDIT
+// Generated by scripts/codegen.js
+
+{{#hasDefinitions}}
+// Service Definitions
+{{#definitions}}
+export { {{name}} } from "./{{{serviceName}}}.js";
+{{/definitions}}
+{{/hasDefinitions}}
+
+{{#hasDefinitions}}
+// Import service definitions to make them available for aggregation
+{{#definitions}}
+import { {{name}} } from "./{{{serviceName}}}.js";
+{{/definitions}}
+{{/hasDefinitions}}
+
+// Aggregate exports for convenience
+{{#hasDefinitions}}
+export const definitions = {
+{{#definitions}}
+  {{serviceName}}: {{name}},
+{{/definitions}}
+};
+{{/hasDefinitions}}
+{{^hasDefinitions}}
+export const definitions = {};
+{{/hasDefinitions}}
+
+// Re-export as default for dynamic importing
+export default definitions;

package/templates/service.js.mustache

@@ -0,0 +1,82 @@
+/* eslint no-unused-vars: "off" */
+
+import { {{#importNamespaces}}{{name}}{{^isLast}}, {{/isLast}}{{/importNamespaces}} } from "@forwardimpact/libtype";
+
+/**
+ * Base class for {{serviceName}} service implementation
+ */
+export class {{className}} {
+  config;
+
+  /**
+   * Creates a new {{serviceName}} service instance
+   * @param {object} config - Service configuration
+   */
+  constructor(config) {
+    if (!config) throw new Error("config is required");
+    this.config = config;
+  }
+
+{{#methods}}
+  {{#responseStream}}
+  /**
+   * Must be implemented by subclass (server streaming)
+   * @param { {{requestTypeNamespace}}.{{requestType}} } {{paramName}} - Request parameters
+   * @param { (response: {{responseTypeNamespace}}.{{responseType}}) => void } write - Callback to write response messages
+   * @returns { Promise<void> } Resolves when streaming is complete
+   */
+  async {{name}}({{paramName}}, write) {
+    throw new Error("{{name}} not implemented");
+  }
+  {{/responseStream}}
+  {{^responseStream}}
+  /**
+   * Must be implemented by subclass
+   * @param { {{requestTypeNamespace}}.{{requestType}} } {{paramName}} - Request parameters
+   * @returns { Promise<{{responseTypeNamespace}}.{{responseType}}> } Response object
+   */
+  async {{name}}({{paramName}}) {
+    throw new Error("{{name}} not implemented");
+  }
+  {{/responseStream}}
+
+{{/methods}}
+  /**
+   * Creates gRPC handlers for this service instance
+   * @returns { object } Map of method names to handler functions
+   */
+  getHandlers() {
+    return {
+{{#methods}}
+      {{#responseStream}}
+      {{name}}: async (call) => {
+        // Validate and convert request
+        const error = {{requestTypeNamespace}}.{{requestType}}.verify(call.request);
+        if (error) throw new Error(`{{name}}: ${error}`);
+        const req = {{requestTypeNamespace}}.{{requestType}}.fromObject(call.request);
+
+        // Stream wrapper that writes typed responses
+        const write = (response) => {
+          call.write({{responseTypeNamespace}}.{{responseType}}.toObject(response));
+        };
+
+        // Call implementation and end stream
+        await this.{{name}}(req, write);
+        call.end();
+      },
+      {{/responseStream}}
+      {{^responseStream}}
+      {{name}}: async (call) => {
+        // Validate and convert request
+        const error = {{requestTypeNamespace}}.{{requestType}}.verify(call.request);
+        if (error) throw new Error(`{{name}}: ${error}`);
+        const req = {{requestTypeNamespace}}.{{requestType}}.fromObject(call.request);
+        
+        // Call implementation
+        return await this.{{name}}(req);
+      },
+      {{/responseStream}}
+{{/methods}}
+    };
+  }
+}

package/templates/services-exports.js.mustache

@@ -0,0 +1,65 @@
+// THIS FILE IS AUTO-GENERATED - DO NOT EDIT
+// Generated by scripts/codegen.js
+
+{{#hasServices}}
+// Service Base Classes
+{{#services}}
+export { {{name}} } from "{{{path}}}";
+{{/services}}
+{{/hasServices}}
+
+{{#hasClients}}
+// Client Classes
+{{#clients}}
+export { {{name}} } from "{{{path}}}";
+{{/clients}}
+{{/hasClients}}
+
+{{#hasServices}}
+// Import service base classes to make them available for aggregation
+{{#services}}
+import { {{name}} } from "{{{path}}}";
+{{/services}}
+{{/hasServices}}
+
+{{#hasClients}}
+// Import client classes to make them available for aggregation
+{{#clients}}
+import { {{name}} } from "{{{path}}}";
+{{/clients}}
+{{/hasClients}}
+
+// Aggregate exports for convenience
+{{#hasServices}}
+export const services = {
+{{#services}}
+  {{name}},
+{{/services}}
+};
+{{/hasServices}}
+{{^hasServices}}
+export const services = {};
+{{/hasServices}}
+
+{{#hasClients}}
+export const clients = {
+{{#clients}}
+  {{name}},
+{{/clients}}
+};
+{{/hasClients}}
+{{^hasClients}}
+export const clients = {};
+{{/hasClients}}
+
+// Re-export everything as default for dynamic importing
+export default {
+  services,
+  clients,
+{{#services}}
+  {{name}},
+{{/services}}
+{{#clients}}
+  {{name}},
+{{/clients}}
+};

package/types.js

@@ -0,0 +1,92 @@
+/**
+ * Handles JavaScript type generation from protobuf files
+ * Specializes in Protocol Buffer to JavaScript type conversion
+ */
+export class CodegenTypes {
+  #base;
+
+  /**
+   * Creates a new types generator with base functionality
+   * @param {object} base - CodegenBase instance providing shared utilities
+   */
+  constructor(base) {
+    if (!base) throw new Error("CodegenBase instance is required");
+    this.#base = base;
+  }
+
+  /**
+   * Generate JavaScript types from protobuf files
+   * @param {string} generatedPath - Path to generated code directory
+   * @returns {Promise<void>}
+   */
+  async run(generatedPath) {
+    if (!generatedPath) throw new Error("generatedPath is required");
+    const typesDir = this.#base.path.resolve(generatedPath, "types");
+    const protoOutDir = this.#base.path.resolve(generatedPath, "proto");
+    const jsOutFile = this.#base.path.resolve(typesDir, "types.js");
+
+    // Create directories and clean up existing files
+    [typesDir, protoOutDir].forEach((dir) => {
+      this.#base.fs.mkdirSync(dir, { recursive: true });
+    });
+
+    if (this.#base.fs.existsSync(jsOutFile)) {
+      this.#base.fs.unlinkSync(jsOutFile);
+    }
+
+    const protoFiles = this.#base.collectProtoFiles({ includeTools: true });
+
+    // Copy all proto source files into generated/proto for runtime loading
+    protoFiles.forEach((protoFile) => {
+      this.#base.fs.copyFileSync(
+        protoFile,
+        this.#base.path.resolve(
+          protoOutDir,
+          this.#base.path.basename(protoFile),
+        ),
+      );
+    });
+
+    await this.generateJavaScriptTypes(protoFiles, jsOutFile);
+
+    // ESM resolution fix: ensure explicit extension for Node ESM and default import
+    const content = this.#base.fs.readFileSync(jsOutFile, "utf8");
+    const fixed = content
+      .replace(/from\s+"protobufjs\/minimal";/, 'from "protobufjs/minimal.js";')
+      .replace(
+        /import\s+\*\s+as\s+\$protobuf\s+from\s+"protobufjs\/minimal\.js";/,
+        'import $protobuf from "protobufjs/minimal.js";',
+      );
+
+    if (fixed !== content) {
+      this.#base.fs.writeFileSync(jsOutFile, fixed, "utf8");
+    }
+  }
+
+  /**
+   * Generate JavaScript types using protobufjs compiler
+   * @param {string[]} protoFiles - Array of proto file paths to compile
+   * @param {string} outFile - Output JavaScript file path
+   * @returns {Promise<void>}
+   */
+  async generateJavaScriptTypes(protoFiles, outFile) {
+    const args = [
+      "-t",
+      "static-module",
+      "-w",
+      "es6",
+      "--no-delimited",
+      "--no-create",
+      "--no-service",
+      "--force-message",
+      "--keep-case",
+      "-o",
+      outFile,
+      ...protoFiles,
+    ];
+
+    await this.#base.run("npx", ["pbjs", ...args], {
+      cwd: this.#base.projectRoot,
+    });
+  }
+}