@progressive-development/pd-provider-firebase-functions 1.3.1 → 1.4.0

package/bin/prepare-functions-deploy.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * Makes a Firebase Functions package.json cloud-ready.
+ *
+ * The cloud build installs with npm, and npm does not know the `workspace:`
+ * protocol — a single `workspace:*` ends the deploy with EUNSUPPORTEDPROTOCOL
+ * before anything is uploaded. So every workspace dependency is replaced by
+ * something npm can resolve. Two cases, and the difference is whether the
+ * package is visible to the registry:
+ *
+ *   PUBLISHED → `^<local version>`. The cloud fetches it from the registry.
+ *               So that this never silently deploys an old build: publish
+ *               first, then deploy.
+ *   PRIVATE   → `file:vendor/<name>.tgz`. A private package exists in no
+ *               registry; it is packed here and lands in the functions folder,
+ *               which is uploaded anyway. Packed is what `files` names — i.e.
+ *               `dist`, which must be built BEFORE (see the predeploy chain in
+ *               firebase.json).
+ *
+ * No configuration: pnpm links every workspace dependency into the functions
+ * package's node_modules as a symlink, and its real path is the source folder.
+ *
+ * Usage (firebase.json → functions.predeploy, run inside the functions package):
+ *   pnpm --filter <functions-package> exec pd-prepare-functions-deploy [--dry-run] [dir]
+ *
+ * CAUTION: the script rewrites package.json for good. To continue working:
+ *   git checkout -- packages/functions/package.json && pnpm install
+ */
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** Fixed tarball name per package — otherwise vendor/ collects one corpse per version. */
+export function vendorFileName(name) {
+  return `${name.replace(/[@/]/g, "-").replace(/^-/, "")}.tgz`;
+}
+
+/**
+ * Where a workspace dependency really lives: follow pnpm's symlink.
+ * @returns {{ dir: string, version: string, private: boolean, main: string }}
+ */
+export function findWorkspacePackage(functionsDir, name) {
+  const link = join(functionsDir, "node_modules", ...name.split("/"));
+  if (!existsSync(link)) {
+    throw new Error(`${name}: nicht in node_modules — erst pnpm install.`);
+  }
+  const dir = realpathSync(link);
+  const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+  return {
+    dir,
+    version: pkg.version,
+    private: pkg.private === true,
+    main: pkg.main ?? "dist/index.js",
+  };
+}
+
+/**
+ * Pure part: the rewritten dependency map plus what changed.
+ * `lookup(name)` answers like findWorkspacePackage.
+ */
+export function rewriteDependencies(dependencies, lookup) {
+  const out = { ...(dependencies ?? {}) };
+  const changes = [];
+  for (const [name, spec] of Object.entries(out)) {
+    if (!String(spec).startsWith("workspace:")) continue;
+    const source = lookup(name);
+    const to = source.private
+      ? `file:vendor/${vendorFileName(name)}`
+      : `^${source.version}`;
+    out[name] = to;
+    changes.push({ name, from: spec, to, private: source.private, source });
+  }
+  return { dependencies: out, changes };
+}
+
+/** Packs a private package into vendor/ and returns the tarball name. */
+export function packPrivate(functionsDir, name, source) {
+  const entry = join(source.dir, source.main);
+  if (!existsSync(entry)) {
+    // Without dist the tarball would be empty and the failure would surface in the cloud.
+    throw new Error(`${name}: ${entry} fehlt — erst bauen, dann deployen.`);
+  }
+  const vendor = join(functionsDir, "vendor");
+  mkdirSync(vendor, { recursive: true });
+  const produced = execFileSync("npm", ["pack", "--pack-destination", vendor], {
+    cwd: source.dir,
+    encoding: "utf8",
+  })
+    .trim()
+    .split("\n")
+    .pop();
+  const target = vendorFileName(name);
+  renameSync(join(vendor, produced), join(vendor, target));
+  return target;
+}
+
+/**
+ * Runs the whole thing for one functions directory.
+ * @returns the list of changes (empty when nothing was a workspace dependency)
+ */
+export function prepare(functionsDir, { dryRun = false, log = console.log } = {}) {
+  const pkgPath = join(functionsDir, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const { dependencies, changes } = rewriteDependencies(pkg.dependencies, (name) =>
+    findWorkspacePackage(functionsDir, name)
+  );
+
+  for (const change of changes) {
+    const kind = change.private ? `privat, ${change.source.version}` : "veröffentlicht";
+    log(`  ${change.name}: ${change.from} -> ${change.to} (${kind})`);
+    if (change.private && !dryRun) packPrivate(functionsDir, change.name, change.source);
+  }
+
+  if (changes.length === 0) {
+    log("Keine Workspace-Abhängigkeiten offen.");
+  } else if (dryRun) {
+    log(`Dry-Run: ${pkgPath} bleibt unverändert.`);
+  } else {
+    writeFileSync(pkgPath, JSON.stringify({ ...pkg, dependencies }, null, 2) + "\n");
+    log(`${pkgPath} für den Deploy umgeschrieben.`);
+  }
+  return changes;
+}
+
+// CLI — argv[1] may be the symlinked path of a pnpm bin shim while
+// import.meta.url is the real one; compare real paths.
+const invokedAs = process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href;
+if (invokedAs === import.meta.url) {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+  const dir = resolve(args.find((a) => !a.startsWith("--")) ?? process.cwd());
+  prepare(dir, { dryRun });
+}

package/bin/prepare-functions-deploy.spec.mjs

@@ -0,0 +1,108 @@
+/**
+ * prepare-functions-deploy: veröffentlicht → ^version, privat → vendor-Tarball,
+ * Auffinden über pnpm-Symlinks, Dry-Run schreibt nichts.
+ */
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  findWorkspacePackage,
+  prepare,
+  rewriteDependencies,
+  vendorFileName,
+} from "./prepare-functions-deploy.mjs";
+
+describe("vendorFileName", () => {
+  it("macht aus einem Scope-Namen einen Dateinamen", () => {
+    expect(vendorFileName("@scope/pkg")).toBe("scope-pkg.tgz");
+    expect(vendorFileName("plain")).toBe("plain.tgz");
+  });
+});
+
+describe("rewriteDependencies", () => {
+  const lookup = (name) =>
+    name === "private-model"
+      ? { dir: "/x", version: "0.1.0", private: true, main: "dist/index.js" }
+      : { dir: "/y", version: "1.3.1", private: false, main: "dist/index.js" };
+
+  it("ersetzt nur workspace:-Abhängigkeiten", () => {
+    const { dependencies, changes } = rewriteDependencies(
+      { "@pd/functions": "workspace:*", "private-model": "workspace:^", express: "^4.0.0" },
+      lookup
+    );
+    expect(dependencies).toEqual({
+      "@pd/functions": "^1.3.1",
+      "private-model": "file:vendor/private-model.tgz",
+      express: "^4.0.0",
+    });
+    expect(changes.map((c) => c.name)).toEqual(["@pd/functions", "private-model"]);
+  });
+
+  it("ohne dependencies passiert nichts", () => {
+    expect(rewriteDependencies(undefined, lookup)).toEqual({ dependencies: {}, changes: [] });
+  });
+});
+
+/** Ein Mini-Workspace: functions/ mit pnpm-artigen Symlinks auf zwei Pakete. */
+function fakeWorkspace() {
+  const root = mkdtempSync(join(tmpdir(), "pd-prepare-"));
+  const functions = join(root, "functions");
+  const model = join(root, "model");
+  const published = join(root, "published");
+  mkdirSync(join(functions, "node_modules", "@pd"), { recursive: true });
+  mkdirSync(model);
+  mkdirSync(published);
+  writeFileSync(
+    join(model, "package.json"),
+    JSON.stringify({ name: "app-model", version: "0.2.0", private: true, main: "dist/index.js" })
+  );
+  writeFileSync(
+    join(published, "package.json"),
+    JSON.stringify({ name: "@pd/functions", version: "1.3.1" })
+  );
+  symlinkSync(model, join(functions, "node_modules", "app-model"), "dir");
+  symlinkSync(published, join(functions, "node_modules", "@pd", "functions"), "dir");
+  writeFileSync(
+    join(functions, "package.json"),
+    JSON.stringify({
+      name: "functions",
+      dependencies: { "app-model": "workspace:*", "@pd/functions": "workspace:*", "firebase-admin": "^13.0.0" },
+    })
+  );
+  return { functions, model };
+}
+
+describe("findWorkspacePackage", () => {
+  it("folgt dem Symlink und liest die package.json der Quelle", () => {
+    const { functions } = fakeWorkspace();
+    const src = findWorkspacePackage(functions, "@pd/functions");
+    expect(src).toMatchObject({ version: "1.3.1", private: false });
+    expect(findWorkspacePackage(functions, "app-model").private).toBe(true);
+  });
+
+  it("meldet ein fehlendes Paket verständlich", () => {
+    const { functions } = fakeWorkspace();
+    expect(() => findWorkspacePackage(functions, "nope")).toThrow(/pnpm install/);
+  });
+});
+
+describe("prepare", () => {
+  it("dry-run: meldet die Änderungen, schreibt nichts, packt nichts", () => {
+    const { functions } = fakeWorkspace();
+    const before = readFileSync(join(functions, "package.json"), "utf8");
+    const lines = [];
+    const changes = prepare(functions, { dryRun: true, log: (l) => lines.push(l) });
+    expect(changes.map((c) => c.to)).toEqual(["file:vendor/app-model.tgz", "^1.3.1"]);
+    expect(readFileSync(join(functions, "package.json"), "utf8")).toBe(before);
+    expect(lines.at(-1)).toMatch(/Dry-Run/);
+  });
+
+  it("scharf: privates Paket ohne dist bricht ab, bevor geschrieben wird", () => {
+    const { functions } = fakeWorkspace();
+    const before = readFileSync(join(functions, "package.json"), "utf8");
+    expect(() => prepare(functions, { log: () => {} })).toThrow(/erst bauen/);
+    expect(readFileSync(join(functions, "package.json"), "utf8")).toBe(before);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progressive-development/pd-provider-firebase-functions",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Firebase Functions v2 utilities for pd-spa-helper backend",
   "author": "PD Progressive Development",
   "license": "SEE LICENSE IN LICENSE",
@@ -11,8 +11,12 @@
   "exports": {
     ".": "./dist/index.js"
   },
+  "bin": {
+    "pd-prepare-functions-deploy": "./bin/prepare-functions-deploy.mjs"
+  },
   "files": [
     "dist/",
+    "bin/",
     "package.json",
     "README.md",
     "LICENSE"