firebase-dataconnect-bootstrap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# firebase-dataconnect-bootstrap
+
+Firebase Data Connect の基本構成作成と、Firestore の `onDocumentWritten` Cloud Functions 追加を自動化する CLI です。
+
+## できること
+
+- 対象レポジトリへ `.firebaserc` と `firebase.json` を生成/更新
+- `dataconnect/` 配下に初期ファイル群を作成
+- `functions/` が未初期化なら最小構成で初期化
+- Firestore `onDocumentWritten` 関数を追加して export
+- 必要に応じて `functions/` で `npm install` を実行
+
+## 使い方
+
+初回セットアップ:
+
+```bash
+npm install
+npm run build
+```
+
+対話モード:
+
+```bash
+npx firebase-dataconnect-bootstrap
+```
+
+非対話モード:
+
+```bash
+npx firebase-dataconnect-bootstrap \
+  --yes \
+  --target . \
+  --project your-firebase-project-id \
+  --region asia-northeast1 \
+  --service your-service-id \
+  --location asia-northeast1 \
+  --document 'meetingSummaries/{summaryId}' \
+  --function onMeetingSummaryWritten \
+  --install
+```
+
+## オプション
+
+- `--target <path>`: 対象リポジトリ
+- `--project <id>`: Firebase project id
+- `--region <region>`: Functions region
+- `--service <serviceId>`: Data Connect service id
+- `--location <location>`: Data Connect location
+- `--document <path>`: Firestore document path
+- `--function <name>`: 関数の export 名
+- `--install`: `functions` で `npm install` を実行
+- `--no-install`: `npm install` をスキップ
+- `--yes`: 対話なしで実行（`--project` は必須）
+
+## npm 公開
+
+1. `npm login`
+2. パッケージ名が未使用か確認
+3. `npm run build`
+4. `npm publish --access public`
+
+## 注意点
+
+- Data Connect/Firebase CLI の認証やプロジェクト作成そのものは行いません。
+- 既存の `functions` 実装に追記するため、デプロイ前に差分確認を推奨します。

package/bin/firebase-dataconnect-bootstrap.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCli } from "../dist/cli.js";
+
+await runCli();

package/dist/cli.js

@@ -0,0 +1,143 @@
+import { collectConfig } from "./prompt.js";
+import { run } from "./main.js";
+import { pathToFileURL } from "node:url";
+const HELP_TEXT = `firebase-dataconnect-bootstrap
+
+Usage:
+  npx firebase-dataconnect-bootstrap [options]
+
+Options:
+  --target <path>            Target repository path (default: current directory)
+  --project <id>             Firebase project id
+  --region <region>          Functions region (default: us-central1)
+  --service <serviceId>      Data Connect service id
+  --location <location>      Data Connect location (default: same as region)
+  --document <path>          Firestore document path (default: meetingSummaries/{summaryId})
+  --function <name>          Function export name (default: onMeetingSummaryWritten)
+  --install                  Run npm install in functions directory
+  --no-install               Skip npm install in functions directory
+  --yes                      Use defaults and skip prompts where possible
+  -h, --help                 Show help
+`;
+function parseArgs(argv) {
+    const args = {
+        targetDir: undefined,
+        projectId: undefined,
+        region: undefined,
+        serviceId: undefined,
+        location: undefined,
+        documentPath: undefined,
+        functionName: undefined,
+        installDependencies: undefined,
+        yes: false,
+        help: false
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "-h" || token === "--help") {
+            args.help = true;
+            continue;
+        }
+        if (token === "--yes") {
+            args.yes = true;
+            continue;
+        }
+        if (token === "--install") {
+            args.installDependencies = true;
+            continue;
+        }
+        if (token === "--no-install") {
+            args.installDependencies = false;
+            continue;
+        }
+        if (token.startsWith("--target=")) {
+            args.targetDir = token.slice("--target=".length);
+            continue;
+        }
+        if (token.startsWith("--project=")) {
+            args.projectId = token.slice("--project=".length);
+            continue;
+        }
+        if (token.startsWith("--region=")) {
+            args.region = token.slice("--region=".length);
+            continue;
+        }
+        if (token.startsWith("--service=")) {
+            args.serviceId = token.slice("--service=".length);
+            continue;
+        }
+        if (token.startsWith("--location=")) {
+            args.location = token.slice("--location=".length);
+            continue;
+        }
+        if (token.startsWith("--document=")) {
+            args.documentPath = token.slice("--document=".length);
+            continue;
+        }
+        if (token.startsWith("--function=")) {
+            args.functionName = token.slice("--function=".length);
+            continue;
+        }
+        const nextValue = argv[i + 1];
+        const useNext = (field) => {
+            if (!nextValue || nextValue.startsWith("-")) {
+                throw new Error(`Missing value for ${token}`);
+            }
+            args[field] = nextValue;
+            i += 1;
+        };
+        switch (token) {
+            case "--target":
+                useNext("targetDir");
+                break;
+            case "--project":
+                useNext("projectId");
+                break;
+            case "--region":
+                useNext("region");
+                break;
+            case "--service":
+                useNext("serviceId");
+                break;
+            case "--location":
+                useNext("location");
+                break;
+            case "--document":
+                useNext("documentPath");
+                break;
+            case "--function":
+                useNext("functionName");
+                break;
+            default:
+                throw new Error(`Unknown option: ${token}`);
+        }
+    }
+    return args;
+}
+export async function runCli(argv = process.argv.slice(2)) {
+    try {
+        const parsed = parseArgs(argv);
+        if (parsed.help) {
+            console.log(HELP_TEXT);
+            return;
+        }
+        const config = await collectConfig(parsed);
+        const result = await run(config);
+        console.log("");
+        console.log("Setup completed.");
+        console.log(`Target: ${result.targetDir}`);
+        for (const line of result.summaryLines) {
+            console.log(`- ${line}`);
+        }
+    }
+    catch (error) {
+        console.error("");
+        console.error("Setup failed.");
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (import.meta.url === invokedPath) {
+    runCli();
+}

package/dist/main.js

@@ -0,0 +1,370 @@
+import { spawn } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+function toPosixPath(filePath) {
+    return filePath.split(path.sep).join("/");
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readTextIfExists(filePath) {
+    if (!(await exists(filePath))) {
+        return null;
+    }
+    return readFile(filePath, "utf8");
+}
+async function readJsonIfExists(filePath) {
+    const text = await readTextIfExists(filePath);
+    if (!text) {
+        return null;
+    }
+    return JSON.parse(text);
+}
+async function writeJson(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+async function writeTextIfMissing(filePath, text) {
+    if (await exists(filePath)) {
+        return false;
+    }
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, text, "utf8");
+    return true;
+}
+function appendIfMissing(content, appendLine) {
+    if (content.includes(appendLine)) {
+        return { changed: false, content };
+    }
+    const suffix = content.endsWith("\n") ? "" : "\n";
+    return {
+        changed: true,
+        content: `${content}${suffix}${appendLine}\n`
+    };
+}
+function detectModuleStyle(entryPath, packageJson) {
+    const ext = path.extname(entryPath);
+    if (ext === ".ts") {
+        return "esm";
+    }
+    if (ext === ".mjs") {
+        return "esm";
+    }
+    if (ext === ".cjs") {
+        return "cjs";
+    }
+    if (packageJson?.type === "module") {
+        return "esm";
+    }
+    return "cjs";
+}
+function buildDataconnectYaml(config) {
+    return `specVersion: "v1alpha"
+serviceId: "${config.serviceId}"
+location: "${config.location}"
+schema: "./schema"
+connectorDirs:
+  - "./example"
+`;
+}
+function buildSchemaGql() {
+    return `# Data Connect schema scaffold
+type MeetingSummary @table(key: "id") {
+  id: String!
+  title: String!
+  summary: String!
+  transcript: String
+  createdAt: Timestamp!
+  recordedSeconds: Float
+}
+`;
+}
+function buildQueriesGql() {
+    return `query SearchMeetingSummaries($searchQuery: String!) {
+  meetingSummaries(where: { title: { like: $searchQuery } }, orderBy: { createdAt: DESC }, first: 20) {
+    id
+    title
+    summary
+    createdAt
+  }
+}
+`;
+}
+function buildMutationsGql() {
+    return `mutation UpsertMeetingSummary(
+  $id: String!
+  $title: String!
+  $summary: String!
+  $transcript: String
+  $createdAt: Timestamp!
+  $recordedSeconds: Float
+) {
+  insertMeetingSummary(
+    data: {
+      id: $id
+      title: $title
+      summary: $summary
+      transcript: $transcript
+      createdAt: $createdAt
+      recordedSeconds: $recordedSeconds
+    }
+    onConflict: {
+      constraint: "meetingSummary_pkey"
+      updateColumns: [title, summary, transcript, createdAt, recordedSeconds]
+    }
+  ) {
+    id
+  }
+}
+`;
+}
+function buildFunctionModule({ style, functionName, documentPath, region }) {
+    if (style === "cjs") {
+        return `const { onDocumentWritten } = require("firebase-functions/v2/firestore");
+const logger = require("firebase-functions/logger");
+
+const ${functionName} = onDocumentWritten(
+  { document: "${documentPath}", region: "${region}" },
+  async (event) => {
+    logger.info("Firestore onDocumentWritten fired", {
+      params: event.params,
+      hasBefore: Boolean(event.data?.before?.exists),
+      hasAfter: Boolean(event.data?.after?.exists)
+    });
+
+    return;
+  }
+);
+
+module.exports = { ${functionName} };
+`;
+    }
+    return `import { onDocumentWritten } from "firebase-functions/v2/firestore";
+import * as logger from "firebase-functions/logger";
+
+export const ${functionName} = onDocumentWritten(
+  { document: "${documentPath}", region: "${region}" },
+  async (event) => {
+    logger.info("Firestore onDocumentWritten fired", {
+      params: event.params,
+      hasBefore: Boolean(event.data?.before?.exists),
+      hasAfter: Boolean(event.data?.after?.exists)
+    });
+
+    return;
+  }
+);
+`;
+}
+async function ensureFirebaseRc(targetDir, projectId) {
+    const filePath = path.join(targetDir, ".firebaserc");
+    const current = (await readJsonIfExists(filePath)) ?? {};
+    const projects = typeof current.projects === "object" && current.projects !== null
+        ? current.projects
+        : {};
+    const next = {
+        ...current,
+        projects: {
+            ...projects,
+            default: projectId
+        }
+    };
+    await writeJson(filePath, next);
+    return ".firebaserc";
+}
+async function ensureFirebaseJson(targetDir) {
+    const filePath = path.join(targetDir, "firebase.json");
+    const current = (await readJsonIfExists(filePath)) ?? {};
+    const next = { ...current };
+    if (!("functions" in next)) {
+        next.functions = { source: "functions" };
+    }
+    if (!("dataconnect" in next)) {
+        next.dataconnect = { source: "dataconnect" };
+    }
+    await writeJson(filePath, next);
+    return "firebase.json";
+}
+async function ensureDataConnectFiles(targetDir, config) {
+    const created = [];
+    const root = path.join(targetDir, "dataconnect");
+    if (await writeTextIfMissing(path.join(root, "dataconnect.yaml"), buildDataconnectYaml(config))) {
+        created.push("dataconnect/dataconnect.yaml");
+    }
+    if (await writeTextIfMissing(path.join(root, "schema", "schema.gql"), buildSchemaGql())) {
+        created.push("dataconnect/schema/schema.gql");
+    }
+    if (await writeTextIfMissing(path.join(root, "example", "queries.gql"), buildQueriesGql())) {
+        created.push("dataconnect/example/queries.gql");
+    }
+    if (await writeTextIfMissing(path.join(root, "example", "mutations.gql"), buildMutationsGql())) {
+        created.push("dataconnect/example/mutations.gql");
+    }
+    return created;
+}
+async function detectFunctionsEntry(targetDir) {
+    const candidates = [
+        "functions/src/index.ts",
+        "functions/src/index.js",
+        "functions/index.ts",
+        "functions/index.js",
+        "functions/index.mjs",
+        "functions/index.cjs"
+    ];
+    for (const relativePath of candidates) {
+        const fullPath = path.join(targetDir, relativePath);
+        if (await exists(fullPath)) {
+            return relativePath;
+        }
+    }
+    return null;
+}
+async function ensureFunctionsPackage(targetDir) {
+    const packagePath = path.join(targetDir, "functions", "package.json");
+    if (await exists(packagePath)) {
+        return null;
+    }
+    const packageJson = {
+        name: "functions",
+        private: true,
+        main: "index.js",
+        engines: {
+            node: "20"
+        },
+        scripts: {
+            lint: "echo \"No lint configured\"",
+            deploy: "firebase deploy --only functions",
+            serve: "firebase emulators:start --only functions",
+            shell: "firebase functions:shell",
+            start: "npm run shell"
+        },
+        dependencies: {
+            "firebase-admin": "^13.0.0",
+            "firebase-functions": "^6.0.0"
+        }
+    };
+    await writeJson(packagePath, packageJson);
+    await writeTextIfMissing(path.join(targetDir, "functions", ".gitignore"), "node_modules\n");
+    return "functions/package.json";
+}
+async function ensureFunctionsEntry(targetDir) {
+    const existing = await detectFunctionsEntry(targetDir);
+    if (existing) {
+        return { entryPath: existing, created: null };
+    }
+    const defaultEntry = "functions/index.js";
+    const fullPath = path.join(targetDir, defaultEntry);
+    await mkdir(path.dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, `const admin = require("firebase-admin");
+admin.initializeApp();
+`, "utf8");
+    return { entryPath: defaultEntry, created: defaultEntry };
+}
+async function ensureFunctionExport(targetDir, config, entryRelativePath) {
+    const functionsPackage = await readJsonIfExists(path.join(targetDir, "functions", "package.json"));
+    const entryFullPath = path.join(targetDir, entryRelativePath);
+    const moduleStyle = detectModuleStyle(entryFullPath, functionsPackage);
+    const extension = path.extname(entryRelativePath) || ".js";
+    const generatedFileName = `firestoreOnDocumentWritten${extension}`;
+    const generatedRelativePath = path.join(path.dirname(entryRelativePath), generatedFileName);
+    const generatedBaseName = path.basename(generatedFileName, extension);
+    const generatedImportPath = moduleStyle === "esm"
+        ? extension === ".ts"
+            ? `./${generatedBaseName}.js`
+            : `./${generatedFileName}`
+        : `./${generatedBaseName}`;
+    const generatedFullPath = path.join(targetDir, generatedRelativePath);
+    const functionModuleText = buildFunctionModule({
+        style: moduleStyle,
+        functionName: config.functionName,
+        documentPath: config.documentPath,
+        region: config.region
+    });
+    await writeFile(generatedFullPath, functionModuleText, "utf8");
+    const entryText = (await readFile(entryFullPath, "utf8")).trimEnd();
+    const exportLine = moduleStyle === "cjs"
+        ? `exports.${config.functionName} = require("${generatedImportPath}").${config.functionName};`
+        : `export { ${config.functionName} } from "${generatedImportPath}";`;
+    const updated = appendIfMissing(entryText, exportLine);
+    if (updated.changed) {
+        await writeFile(entryFullPath, `${updated.content}`, "utf8");
+    }
+    return {
+        generatedRelativePath: toPosixPath(generatedRelativePath),
+        entryRelativePath: toPosixPath(entryRelativePath),
+        entryUpdated: updated.changed
+    };
+}
+async function runNpmInstall(functionsDir) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn("npm", ["install"], {
+            cwd: functionsDir,
+            stdio: "inherit"
+        });
+        child.on("error", rejectPromise);
+        child.on("exit", (code, signal) => {
+            if (code === 0) {
+                resolvePromise();
+                return;
+            }
+            if (code !== null) {
+                rejectPromise(new Error(`npm install failed with exit code ${code}`));
+                return;
+            }
+            rejectPromise(new Error(`npm install terminated by signal ${signal ?? "unknown signal"}`));
+        });
+    });
+}
+export async function run(config) {
+    if (!config.projectId) {
+        throw new Error("Firebase project id is required.");
+    }
+    const targetDir = path.resolve(config.targetDir);
+    const summaryLines = [];
+    summaryLines.push(`Updated ${await ensureFirebaseRc(targetDir, config.projectId)}`);
+    summaryLines.push(`Updated ${await ensureFirebaseJson(targetDir)}`);
+    const dataconnectCreated = await ensureDataConnectFiles(targetDir, config);
+    if (dataconnectCreated.length === 0) {
+        summaryLines.push("Data Connect files already existed");
+    }
+    else {
+        summaryLines.push(`Created ${dataconnectCreated.join(", ")}`);
+    }
+    const functionsPackage = await ensureFunctionsPackage(targetDir);
+    if (functionsPackage) {
+        summaryLines.push(`Created ${functionsPackage}`);
+    }
+    else {
+        summaryLines.push("functions/package.json already existed");
+    }
+    const { entryPath, created: createdEntry } = await ensureFunctionsEntry(targetDir);
+    if (createdEntry) {
+        summaryLines.push(`Created ${createdEntry}`);
+    }
+    else {
+        summaryLines.push(`Using existing ${entryPath}`);
+    }
+    const exportResult = await ensureFunctionExport(targetDir, config, entryPath);
+    summaryLines.push(`Updated ${exportResult.generatedRelativePath}`);
+    summaryLines.push(exportResult.entryUpdated
+        ? `Appended export in ${exportResult.entryRelativePath}`
+        : `Export already present in ${exportResult.entryRelativePath}`);
+    if (config.installDependencies) {
+        const functionsDir = path.join(targetDir, "functions");
+        await runNpmInstall(functionsDir);
+        summaryLines.push("Installed functions dependencies with npm install");
+    }
+    else {
+        summaryLines.push("Skipped npm install in functions directory");
+    }
+    return {
+        targetDir,
+        summaryLines
+    };
+}

package/dist/prompt.js

@@ -0,0 +1,78 @@
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+function normalizeFunctionName(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9_$]/g, "_");
+    if (!cleaned) {
+        return "onMeetingSummaryWritten";
+    }
+    if (/^[A-Za-z_$]/.test(cleaned)) {
+        return cleaned;
+    }
+    return `fn_${cleaned}`;
+}
+function normalizeConfig(partial) {
+    const targetDir = resolve(partial.targetDir ?? process.cwd());
+    const region = partial.region?.trim() || "us-central1";
+    const projectId = partial.projectId?.trim() || "";
+    const serviceId = partial.serviceId?.trim() || `${projectId || "my-project"}-service`;
+    const location = partial.location?.trim() || region;
+    const documentPath = partial.documentPath?.trim() || "meetingSummaries/{summaryId}";
+    const functionName = normalizeFunctionName(partial.functionName?.trim() || "onMeetingSummaryWritten");
+    const installDependencies = typeof partial.installDependencies === "boolean" ? partial.installDependencies : true;
+    return {
+        targetDir,
+        projectId,
+        region,
+        serviceId,
+        location,
+        documentPath,
+        functionName,
+        installDependencies
+    };
+}
+export async function collectConfig(parsed) {
+    const defaults = normalizeConfig(parsed);
+    if (parsed.yes) {
+        if (!defaults.projectId) {
+            throw new Error("`--project` is required when using --yes.");
+        }
+        return defaults;
+    }
+    const rl = createInterface({ input, output });
+    try {
+        const ask = async (label, fallback, required = false) => {
+            const answer = await rl.question(`${label} [${fallback}]: `);
+            const value = answer.trim() || fallback;
+            if (!value && required) {
+                throw new Error(`${label} is required.`);
+            }
+            return value;
+        };
+        console.log("Firebase Data Connect / Cloud Functions bootstrap");
+        console.log("");
+        const targetDir = resolve(await ask("Target repository path", defaults.targetDir, true));
+        const projectId = await ask("Firebase project id", defaults.projectId || "my-project", true);
+        const region = await ask("Functions region", defaults.region, true);
+        const serviceId = await ask("Data Connect service id", `${projectId}-service`, true);
+        const location = await ask("Data Connect location", defaults.location || region, true);
+        const documentPath = await ask("Firestore document path", defaults.documentPath, true);
+        const rawFunctionName = await ask("Function export name", defaults.functionName, true);
+        const functionName = normalizeFunctionName(rawFunctionName);
+        const installRaw = await ask("Run npm install in functions directory? (y/n)", defaults.installDependencies ? "y" : "n", true);
+        const installDependencies = installRaw.toLowerCase().startsWith("y");
+        return {
+            targetDir,
+            projectId,
+            region,
+            serviceId,
+            location,
+            documentPath,
+            functionName,
+            installDependencies
+        };
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "firebase-dataconnect-bootstrap",
+  "version": "0.1.0",
+  "description": "Bootstrap Firebase Data Connect and Firestore onDocumentWritten function setup in any repository.",
+  "type": "module",
+  "bin": {
+    "firebase-dataconnect-bootstrap": "bin/firebase-dataconnect-bootstrap.js"
+  },
+  "main": "dist/main.js",
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "start": "npm run build && node dist/cli.js",
+    "lint": "npm run typecheck",
+    "test": "npm run typecheck",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "firebase",
+    "dataconnect",
+    "firestore",
+    "cloud-functions",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}