Merge pull request #7 from mallaire77/pgf-446-file-search-extension

feat(extensions): add file search retrieval extension (PGF-446)

Author: mallaire77

README-badal.md

@@ -0,0 +1,132 @@
+# Badal Gemini CLI Notes
+
+This document explains the long-lived Badal-specific shape of the
+`badal-io/gemini-cli` fork. It is meant to capture fork-level operational and
+development context, not ticket-specific work.
+
+## What This Repo Is
+
+- This repository is a fork of `google-gemini/gemini-cli`.
+- Badal uses the fork in `badal-io/gemini-cli`.
+- The `badal` branch is the effective Badal baseline branch.
+
+Important: a lot of upstream identity still remains in the codebase.
+
+- Package names are still largely `@google/*`.
+- The root `package.json` repository URL still points at the upstream Google
+  repository.
+- The root `README.md` and many GitHub workflows still describe the upstream
+  project rather than Badal's operational use.
+
+## How Badal Uses This Fork
+
+Badal does not use this repo only as a local CLI. This fork is also used as the
+runtime for containerized agent sessions launched by Backstage.
+
+The high-level Badal-specific shape is:
+
+- a custom runtime image defined in `deploy/cloudrun/Dockerfile`
+- a Badal-managed image build workflow in `.github/workflows/cloudrun-image.yml`
+- bundled extensions installed into the runtime image
+- extra operational tooling added to the container for agent use
+- integration with Backstage, which is responsible for launching sessions and
+  injecting runtime configuration
+
+## Runtime Image
+
+The custom runtime image is built from `deploy/cloudrun/Dockerfile`.
+
+At a high level it:
+
+- builds and packs the Gemini CLI monorepo packages
+- installs the packed CLI artifacts globally in the runtime container
+- installs operational tools used by agent sessions such as `gh`, `gcloud`,
+  `terraform`, `vault`, `bun`, and `bd`
+- installs extensions under `/root/.gemini/extensions`
+- copies in Badal-managed Gemini settings and the container entrypoint
+
+Known note:
+
+- the `hookwise` / `captain-hook` extension is intentionally disabled in the
+  Dockerfile because of build issues
+
+## Extensions
+
+Gemini CLI already supports extensions natively. The extension docs live under
+`docs/extensions/`.
+
+For Badal, extensions matter because they are part of the deployed agent
+runtime, not just a user-side convenience feature.
+
+General extension-related locations to know:
+
+- `docs/extensions/`
+- `packages/`
+- `deploy/cloudrun/Dockerfile`
+
+When working on extensions in this fork, verify both:
+
+- the extension package itself
+- whether the runtime image is bundling it correctly
+
+## Workflows
+
+Current workflow reality:
+
+- the repository still contains a large inherited set of upstream Google
+  workflows
+- only some workflows reflect Badal-specific operational needs
+- `.github/workflows/cloudrun-image.yml` is the clearest Badal-specific workflow
+  today
+
+### `cloudrun-image.yml`
+
+Purpose:
+
+- build and publish the `gemini-a2a` runtime image to GHCR
+
+Behavior to verify when editing it:
+
+- which branches trigger builds
+- which pull request targets trigger builds
+- which paths are included in the workflow filters
+- how the image name and tags are computed
+
+## Code Areas That Matter Most For Badal
+
+If you need to understand or modify the Badal flavor, start here:
+
+- `deploy/cloudrun/Dockerfile`
+- `.github/workflows/cloudrun-image.yml`
+- `docs/extensions/`
+- `packages/`
+
+If the work involves agent launch behavior, credentials, or session wiring, the
+other repo to read is `repo-devex-backstage`, especially the Gemini agent
+backend that injects runtime configuration into this container.
+
+## Testing Notes
+
+Useful baseline commands in this repo:
+
+```bash
+npm ci
+npm run build
+npm test
+```
+
+When making Badal-specific changes, also verify the behavior that matters for
+the deployment path you touched, for example:
+
+- image build behavior if you changed `deploy/cloudrun/Dockerfile`
+- workflow behavior if you changed `.github/workflows/`
+- extension packaging if you changed extension-related code
+
+## Practical Takeaways
+
+- Treat this repo as "upstream Gemini CLI plus Badal deployment/runtime
+  customizations".
+- Do not assume upstream docs, README badges, workflow names, or repository URLs
+  reflect Badal's actual usage.
+- For agent-runtime work, the Dockerfile, workflows, and extension packaging are
+  more important than the upstream marketing/docs surface.

deploy/cloudrun/Dockerfile

@@ -116,6 +116,12 @@ RUN mkdir -p /root/.gemini/extensions
 # ai-plugin-translator extension
 COPY --from=translator-builder /build /root/.gemini/extensions/ai-plugin-translator
 
+# File Search extension
+COPY packages/file-search-extension /root/.gemini/extensions/file-search-extension
+RUN cd /root/.gemini/extensions/file-search-extension && \
+    npm install --omit=dev && \
+    npm cache clean --force
+
 # TODO: hookwise extension disabled (see comment at top of file)
 # COPY --from=hookwise-builder /build/target/release/hookwise /root/.gemini/extensions/captain-hook/captain-hook
 # COPY --from=hookwise-builder /build/.claude-plugin /root/.gemini/extensions/captain-hook/.claude-plugin

package-lock.json

@@ -0,0 +1,26 @@
+# File Search Retrieval
+
+This extension gives you repository-scoped retrieval against Gemini File Search.
+
+Use it when:
+- you need context that is not present in the current workspace checkout
+- you need to inspect indexed files without broad local scanning
+- you suspect the current answer is missing adjacent files, callers, callees, or partial definitions
+
+Retrieval strategy:
+- Search first and fetch narrowly second.
+- Prefer `search_store` to locate likely files or concepts before calling a more specific fetch tool.
+- Use `fetch_file_context` when you already know the file path you want.
+- Use `fetch_symbol_context` when the task is centered on a declaration, type, function, or symbol name.
+- Use `expand_related_context` when the first retrieval shows the context is partial or points to neighboring files.
+
+When to do follow-up retrieval:
+- the retrieved answer says context is incomplete
+- a symbol is referenced but not defined
+- a file references callers, imports, or implementation details in another file
+- the user asks for behavior that likely spans multiple files
+
+Bound retrieval:
+- do not fan out across many files at once
+- follow the recommended next steps from the previous retrieval
+- stop once the extension reports that the current context is sufficient

packages/file-search-extension/GEMINI.md

@@ -0,0 +1,12 @@
+{
+  "name": "file-search-extension",
+  "version": "0.1.0",
+  "contextFileName": "GEMINI.md",
+  "mcpServers": {
+    "fileSearch": {
+      "command": "node",
+      "args": ["${extensionPath}${/}src${/}server.js"],
+      "cwd": "${extensionPath}"
+    }
+  }
+}

packages/file-search-extension/gemini-extension.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "BeforeAgent": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${extensionPath}/scripts/before-agent.js"
+          }
+        ]
+      }
+    ]
+  }
+}

packages/file-search-extension/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "name": "@badal/file-search-extension",
+  "version": "0.1.0",
+  "description": "Gemini CLI extension for repository-scoped Gemini File Search retrieval",
+  "private": true,
+  "type": "module",
+  "main": "src/server.js",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.23.0",
+    "zod": "^3.23.8"
+  }
+}

packages/file-search-extension/package.json

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Badal
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const storeName = process.env.FILE_SEARCH_STORE_NAME;
+const repo = process.env.FILE_SEARCH_REPO;
+const sourceRepository = process.env.FILE_SEARCH_SOURCE_REPOSITORY;
+const authMode = process.env.FILE_SEARCH_AUTH_MODE || 'unconfigured';
+
+const lines = [];
+if (storeName) {
+  lines.push(`File Search store: ${storeName}`);
+}
+if (repo) {
+  lines.push(`File Search repo tag: ${repo}`);
+}
+if (sourceRepository) {
+  lines.push(`Source repository: ${sourceRepository}`);
+}
+lines.push(`File Search auth mode: ${authMode}`);
+lines.push(
+  'Use File Search tools when local context is missing, partial, or points to neighboring files.',
+);
+lines.push('Search first, then fetch narrowly, then expand only if needed.');
+
+console.log(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'BeforeAgent',
+      additionalContext: lines.join('\n'),
+    },
+  }),
+);