feat: add stdio-based function discovery mode

Adds an alternative discovery mechanism that outputs function manifests via stderr
instead of starting an HTTP server. This improves reliability by avoiding issues
where module loading blocks the HTTP endpoint from becoming available.

When FUNCTIONS_DISCOVERY_MODE=stdio is set:
- Outputs base64-encoded manifest to stderr with __FIREBASE_FUNCTIONS_MANIFEST__: prefix
- Outputs errors to stderr with __FIREBASE_FUNCTIONS_MANIFEST_ERROR__: prefix
- Exits immediately without starting HTTP server
- Maintains backward compatibility (HTTP remains default)

Includes comprehensive tests that verify both HTTP and stdio discovery work
correctly for all test cases (commonjs, esm, various configurations).

Author: taeold

scripts/bin-test/test.ts

@@ -199,11 +199,46 @@ async function startBin(
   };
 }
 
+async function runStdioDiscovery(
+  modulePath: string
+): Promise<{ stdout: string; stderr: string; exitCode: number | null }> {
+  return new Promise((resolve, reject) => {
+    const proc = subprocess.spawn("npx", ["firebase-functions"], {
+      cwd: path.resolve(modulePath),
+      env: {
+        PATH: process.env.PATH,
+        GCLOUD_PROJECT: "test-project",
+        FUNCTIONS_CONTROL_API: "true",
+        FUNCTIONS_DISCOVERY_MODE: "stdio",
+      },
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+
+    proc.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+
+    proc.on("close", (code) => {
+      resolve({ stdout, stderr, exitCode: code });
+    });
+
+    proc.on("error", (err) => {
+      reject(err);
+    });
+  });
+}
+
 describe("functions.yaml", function () {
   // eslint-disable-next-line @typescript-eslint/no-invalid-this
   this.timeout(TIMEOUT_XL);
 
-  function runTests(tc: Testcase) {
+  function runHttpDiscoveryTests(tc: Testcase) {
     let port: number;
     let cleanup: () => Promise<void>;
 
@@ -233,6 +268,31 @@ describe("functions.yaml", function () {
     });
   }
 
+  function runStdioDiscoveryTests(tc: Testcase) {
+    it("discovers functions via stdio", async function () {
+      // eslint-disable-next-line @typescript-eslint/no-invalid-this
+      this.timeout(TIMEOUT_M);
+
+      const result = await runStdioDiscovery(tc.modulePath);
+
+      // Should exit successfully
+      expect(result.exitCode).to.equal(0);
+
+      // Should not start HTTP server
+      expect(result.stdout).to.not.contain("Serving at port");
+
+      // Should output manifest to stderr
+      const manifestMatch = result.stderr.match(/__FIREBASE_FUNCTIONS_MANIFEST__:(.+)/);
+      expect(manifestMatch).to.not.be.null;
+
+      // Decode and verify manifest
+      const base64 = manifestMatch![1];
+      const manifestJson = Buffer.from(base64, "base64").toString("utf8");
+      const manifest = JSON.parse(manifestJson);
+      expect(manifest).to.deep.equal(tc.expected);
+    });
+  }
+
   describe("commonjs", function () {
     // eslint-disable-next-line @typescript-eslint/no-invalid-this
     this.timeout(TIMEOUT_L);
@@ -320,7 +380,13 @@ describe("functions.yaml", function () {
 
     for (const tc of testcases) {
       describe(tc.name, () => {
-        runTests(tc);
+        describe("http discovery", () => {
+          runHttpDiscoveryTests(tc);
+        });
+        
+        describe("stdio discovery", () => {
+          runStdioDiscoveryTests(tc);
+        });
       });
     }
   });
@@ -350,8 +416,48 @@ describe("functions.yaml", function () {
 
     for (const tc of testcases) {
       describe(tc.name, () => {
-        runTests(tc);
+        describe("http discovery", () => {
+          runHttpDiscoveryTests(tc);
+        });
+        
+        describe("stdio discovery", () => {
+          runStdioDiscoveryTests(tc);
+        });
       });
     }
   });
+  
+  describe("stdio discovery error handling", function () {
+    it("outputs error for broken module", async function () {
+      // Create a temporary broken module
+      const fs = require("fs");
+      const brokenModulePath = path.join(__dirname, "temp-broken-module");
+      
+      try {
+        // Create directory and files
+        fs.mkdirSync(brokenModulePath, { recursive: true });
+        fs.writeFileSync(
+          path.join(brokenModulePath, "package.json"),
+          JSON.stringify({ name: "broken-module", main: "index.js" })
+        );
+        fs.writeFileSync(
+          path.join(brokenModulePath, "index.js"),
+          "const functions = require('firebase-functions');\nsyntax error here"
+        );
+
+        const result = await runStdioDiscovery(brokenModulePath);
+
+        // Should exit with error
+        expect(result.exitCode).to.equal(1);
+
+        // Should output error to stderr
+        const errorMatch = result.stderr.match(/__FIREBASE_FUNCTIONS_MANIFEST_ERROR__:(.+)/);
+        expect(errorMatch).to.not.be.null;
+        expect(errorMatch![1]).to.contain("Unexpected identifier");
+      } finally {
+        // Cleanup
+        fs.rmSync(brokenModulePath, { recursive: true, force: true });
+      }
+    });
+  });
 });

src/bin/firebase-functions.ts

@@ -49,34 +49,53 @@ if (args.length > 1) {
   functionsDir = args[0];
 }
 
-let server: http.Server = undefined;
-const app = express();
-
-function handleQuitquitquit(req: express.Request, res: express.Response) {
-  res.send("ok");
-  server.close();
+async function runStdioDiscovery() {
+  try {
+    const stack = await loadStack(functionsDir);
+    const wireFormat = stackToWire(stack);
+    const manifestJson = JSON.stringify(wireFormat);
+    const base64 = Buffer.from(manifestJson).toString("base64");
+    process.stderr.write(`__FIREBASE_FUNCTIONS_MANIFEST__:${base64}\n`);
+    process.exit(0);
+  } catch (e) {
+    console.error("Failed to generate manifest from function source:", e);
+    process.stderr.write(`__FIREBASE_FUNCTIONS_MANIFEST_ERROR__:${e.message}\n`);
+    process.exit(1);
+  }
 }
 
-app.get("/__/quitquitquit", handleQuitquitquit);
-app.post("/__/quitquitquit", handleQuitquitquit);
+if (process.env.FUNCTIONS_CONTROL_API === "true" && process.env.FUNCTIONS_DISCOVERY_MODE === "stdio") {
+  runStdioDiscovery();
+} else {
+  let server: http.Server = undefined;
+  const app = express();
 
-if (process.env.FUNCTIONS_CONTROL_API === "true") {
-  app.get("/__/functions.yaml", async (req, res) => {
-    try {
-      const stack = await loadStack(functionsDir);
-      res.setHeader("content-type", "text/yaml");
-      res.send(JSON.stringify(stackToWire(stack)));
-    } catch (e) {
-      console.error(e);
-      res.status(400).send(`Failed to generate manifest from function source: ${e}`);
-    }
-  });
-}
+  function handleQuitquitquit(req: express.Request, res: express.Response) {
+    res.send("ok");
+    server.close();
+  }
 
-let port = 8080;
-if (process.env.PORT) {
-  port = Number.parseInt(process.env.PORT);
-}
+  app.get("/__/quitquitquit", handleQuitquitquit);
+  app.post("/__/quitquitquit", handleQuitquitquit);
 
-console.log("Serving at port", port);
-server = app.listen(port);
+  if (process.env.FUNCTIONS_CONTROL_API === "true") {
+    app.get("/__/functions.yaml", async (req, res) => {
+      try {
+        const stack = await loadStack(functionsDir);
+        res.setHeader("content-type", "text/yaml");
+        res.send(JSON.stringify(stackToWire(stack)));
+      } catch (e) {
+        console.error(e);
+        res.status(400).send(`Failed to generate manifest from function source: ${e}`);
+      }
+    });
+  }
+
+  let port = 8080;
+  if (process.env.PORT) {
+    port = Number.parseInt(process.env.PORT);
+  }
+
+  console.log("Serving at port", port);
+  server = app.listen(port);
+}