firebase-dataconnect-bootstrap 1.1.0 → 1.2.1

package/README.md

@@ -1,31 +1,49 @@
 # firebase-dataconnect-bootstrap
 
-Firebase Data Connect の基本構成作成と、Firestore の `onDocumentWritten` Cloud Functions 追加を自動化する CLI です。
+Firebase Data Connect と Cloud Functions のセットアップを自動化する CLI です。  
+初期作成だけでなく、再実行で設定変更（途中更新）もできます。
 
 ## できること
 
-- 対象レポジトリへ `.firebaserc` と `firebase.json` を生成/更新
-- `dataconnect/` 配下に初期ファイル群を作成
-- `functions/` が未初期化なら最小構成で初期化
-- Firestore `onDocumentWritten` 関数を追加して export
-- 必要に応じて `functions/` で `npm install` を実行
+- `.firebaserc` と `firebase.json` の生成/更新
+- `dataconnect/` 初期ファイル生成
+- `functions/` 未初期化時の最小構成作成
+- Firestore `onDocumentWritten` の生成/更新
+- ベクトル検索用 `onRequest` 関数の生成/更新
+- 埋め込み実装差し替え用 `vectorSearchEmbedding` テンプレート生成
+- 前回設定を `.firebase-dataconnect-bootstrap.json` に保存し、次回実行時に再利用
 
 ## 使い方
 
-初回セットアップ:
-
 ```bash
-npm install
-npm run build
+npx firebase-dataconnect-bootstrap
 ```
 
-対話モード:
+対話モードは日本語で質問が表示されます。  
+同じリポジトリで再実行すると、保存済み設定を初期値として設定変更できます。  
+既存設定がある場合は、対話中に「新しいコレクション設定を追加するか」を選べます。
+
+## 追加コレクションを非対話で追加する例
 
 ```bash
-npx firebase-dataconnect-bootstrap
+npx firebase-dataconnect-bootstrap \
+  --yes \
+  --add-collection \
+  --target . \
+  --project your-firebase-project-id \
+  --document 'articles/{articleId}' \
+  --function onArticlesWritten \
+  --vector-search \
+  --vector-collection 'articles' \
+  --source-text-field 'body' \
+  --vector-field 'embedding' \
+  --search-fields 'title,body,updatedAt' \
+  --search-function 'searchArticlesByVector' \
+  --top-k 8 \
+  --no-install
 ```
 
-非対話モード:
+## 非対話モード例
 
 ```bash
 npx firebase-dataconnect-bootstrap \
@@ -37,30 +55,51 @@ npx firebase-dataconnect-bootstrap \
   --location asia-northeast1 \
   --document 'meetingSummaries/{summaryId}' \
   --function onMeetingSummaryWritten \
+  --vector-search \
+  --vector-collection 'meetingSummaries' \
+  --source-text-field 'summary' \
+  --vector-field 'embedding' \
+  --search-fields 'title,summary,createdAt' \
+  --search-function 'searchByVector' \
+  --top-k 5 \
   --install
 ```
 
-## オプション
+## 主なオプション
+
+- `--config <name>`: 設定保存ファイル名（既定: `.firebase-dataconnect-bootstrap.json`）
+- `--add-collection`: 再実行時に既存設定へ新しいコレクション設定を追加
+- `--vector-search` / `--no-vector-search`: ベクトル検索 scaffold の有効/無効
+- `--vector-collection <path>`: 検索対象コレクション
+- `--source-text-field <name>`: 埋め込み更新対象のテキストフィールド
+- `--vector-field <name>`: ベクトル保存フィールド
+- `--search-fields <csv>`: 検索結果として返すフィールド
+- `--search-function <name>`: 生成する `onRequest` 関数名
+- `--top-k <number>`: 検索時のデフォルト上位件数
 
-- `--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 公開
+- `onDocumentWritten_<functionName>.*`
+  - `sourceTextField` の内容を `embedText` に渡し、`vectorField` へ保存
+- `vectorSearchOnRequest_<searchFunctionName>.*`
+  - HTTP リクエストの `vector`（または `query`）でコサイン類似度検索
+- `vectorSearchEmbedding_<functionName>.*`
+  - `embedText` を実装する差し替えポイント（デフォルトは `null` を返す）
 
-1. `npm login`
-2. パッケージ名が未使用か確認
-3. `npm run build`
-4. `npm publish --access public`
+## npm モジュールとして検索クライアントを使う
 
-## 注意点
+```ts
+import { createVectorSearchClient } from "firebase-dataconnect-bootstrap/search-client";
+
+const client = createVectorSearchClient({
+  endpoint: "https://<region>-<project>.cloudfunctions.net/searchByVector"
+});
+
+const result = await client.search({
+  query: "議事録の要点",
+  topK: 5
+});
+```
 
-- Data Connect/Firebase CLI の認証やプロジェクト作成そのものは行いません。
-- 既存の `functions` 実装に追記するため、デプロイ前に差分確認を推奨します。
+`query` を使う場合は、Functions 側 `vectorSearchEmbedding.*` の `embedText` 実装が必要です。  
+`vector` を直接渡す場合は `embedText` が未実装でも検索できます。

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -14,8 +14,18 @@ Options:
   --location <location>      Data Connect location (default: same as region)
   --document <path>          Firestore document path (default: meetingSummaries/{summaryId})
   --function <name>          Function export name (default: onMeetingSummaryWritten)
+  --config <name>            Saved config filename (default: .firebase-dataconnect-bootstrap.json)
+  --add-collection           Add a new collection setting on re-run
   --install                  Run npm install in functions directory
   --no-install               Skip npm install in functions directory
+  --vector-search            Enable vector search scaffolding
+  --no-vector-search         Disable vector search scaffolding
+  --vector-collection <path> Collection path used for vector search
+  --source-text-field <name> Source text field for embedding updates
+  --vector-field <name>      Vector field name
+  --search-fields <csv>      Response fields for search results (comma-separated)
+  --search-function <name>   onRequest function export name for vector search
+  --top-k <number>           Default topK value for vector search
   --yes                      Use defaults and skip prompts where possible
   -h, --help                 Show help
 `;
@@ -29,6 +39,9 @@ function parseArgs(argv) {
         documentPath: undefined,
         functionName: undefined,
         installDependencies: undefined,
+        configFileName: undefined,
+        vectorSearch: {},
+        addCollection: undefined,
         yes: false,
         help: false
     };
@@ -50,6 +63,18 @@ function parseArgs(argv) {
             args.installDependencies = false;
             continue;
         }
+        if (token === "--vector-search") {
+            args.vectorSearch = { ...(args.vectorSearch ?? {}), enabled: true };
+            continue;
+        }
+        if (token === "--no-vector-search") {
+            args.vectorSearch = { ...(args.vectorSearch ?? {}), enabled: false };
+            continue;
+        }
+        if (token === "--add-collection") {
+            args.addCollection = true;
+            continue;
+        }
         if (token.startsWith("--target=")) {
             args.targetDir = token.slice("--target=".length);
             continue;
@@ -78,12 +103,66 @@ function parseArgs(argv) {
             args.functionName = token.slice("--function=".length);
             continue;
         }
+        if (token.startsWith("--config=")) {
+            args.configFileName = token.slice("--config=".length);
+            continue;
+        }
+        if (token.startsWith("--vector-collection=")) {
+            args.vectorSearch = {
+                ...(args.vectorSearch ?? {}),
+                collectionPath: token.slice("--vector-collection=".length)
+            };
+            continue;
+        }
+        if (token.startsWith("--source-text-field=")) {
+            args.vectorSearch = {
+                ...(args.vectorSearch ?? {}),
+                sourceTextField: token.slice("--source-text-field=".length)
+            };
+            continue;
+        }
+        if (token.startsWith("--vector-field=")) {
+            args.vectorSearch = {
+                ...(args.vectorSearch ?? {}),
+                vectorField: token.slice("--vector-field=".length)
+            };
+            continue;
+        }
+        if (token.startsWith("--search-fields=")) {
+            args.vectorSearch = {
+                ...(args.vectorSearch ?? {}),
+                returnFields: token
+                    .slice("--search-fields=".length)
+                    .split(",")
+                    .map((field) => field.trim())
+                    .filter(Boolean)
+            };
+            continue;
+        }
+        if (token.startsWith("--search-function=")) {
+            args.vectorSearch = {
+                ...(args.vectorSearch ?? {}),
+                functionName: token.slice("--search-function=".length)
+            };
+            continue;
+        }
+        if (token.startsWith("--top-k=")) {
+            const parsedTopK = Number.parseInt(token.slice("--top-k=".length), 10);
+            if (Number.isNaN(parsedTopK) || parsedTopK <= 0) {
+                throw new Error("--top-k must be a positive integer");
+            }
+            args.vectorSearch = { ...(args.vectorSearch ?? {}), defaultTopK: parsedTopK };
+            continue;
+        }
         const nextValue = argv[i + 1];
-        const useNext = (field) => {
+        const requireNextValue = () => {
             if (!nextValue || nextValue.startsWith("-")) {
                 throw new Error(`Missing value for ${token}`);
             }
-            args[field] = nextValue;
+            return nextValue;
+        };
+        const useNext = (field) => {
+            args[field] = requireNextValue();
             i += 1;
         };
         switch (token) {
@@ -108,6 +187,56 @@ function parseArgs(argv) {
             case "--function":
                 useNext("functionName");
                 break;
+            case "--config":
+                useNext("configFileName");
+                break;
+            case "--vector-collection":
+                args.vectorSearch = {
+                    ...(args.vectorSearch ?? {}),
+                    collectionPath: requireNextValue()
+                };
+                i += 1;
+                break;
+            case "--source-text-field":
+                args.vectorSearch = {
+                    ...(args.vectorSearch ?? {}),
+                    sourceTextField: requireNextValue()
+                };
+                i += 1;
+                break;
+            case "--vector-field":
+                args.vectorSearch = {
+                    ...(args.vectorSearch ?? {}),
+                    vectorField: requireNextValue()
+                };
+                i += 1;
+                break;
+            case "--search-fields":
+                args.vectorSearch = {
+                    ...(args.vectorSearch ?? {}),
+                    returnFields: requireNextValue()
+                        .split(",")
+                        .map((field) => field.trim())
+                        .filter(Boolean)
+                };
+                i += 1;
+                break;
+            case "--search-function":
+                args.vectorSearch = {
+                    ...(args.vectorSearch ?? {}),
+                    functionName: requireNextValue()
+                };
+                i += 1;
+                break;
+            case "--top-k": {
+                const parsedTopK = Number.parseInt(requireNextValue(), 10);
+                if (Number.isNaN(parsedTopK) || parsedTopK <= 0) {
+                    throw new Error("--top-k must be a positive integer");
+                }
+                args.vectorSearch = { ...(args.vectorSearch ?? {}), defaultTopK: parsedTopK };
+                i += 1;
+                break;
+            }
             default:
                 throw new Error(`Unknown option: ${token}`);
         }

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { run } from "./main.js";
+export { runCli } from "./cli.js";
+export { collectConfig } from "./prompt.js";
+export { createVectorSearchClient, searchByVector } from "./search-client.js";
+export type { CliArgs, PersistedBootstrapConfig, RunResult, SetupConfig, SetupTargetConfig, VectorSearchConfig } from "./types.js";
+export type { SearchByVectorInput, VectorSearchClientOptions, VectorSearchHit, VectorSearchResponse } from "./search-client.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { run } from "./main.js";
+export { runCli } from "./cli.js";
+export { collectConfig } from "./prompt.js";
+export { createVectorSearchClient, searchByVector } from "./search-client.js";

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+import type { RunResult, SetupConfig } from "./types.js";
+export declare function run(config: SetupConfig): Promise<RunResult>;