privateer-agent 0.1.0

package/src/mcp/client.ts

@@ -0,0 +1,236 @@
+import { existsSync, readFileSync } from "node:fs";
+import { tool, jsonSchema, type ToolSet } from "ai";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { globalPaths, projectPaths } from "../config/paths.ts";
+import { type PermissionGate, PermissionDeniedError } from "../permissions/gate.ts";
+import { FileOAuthProvider, type AuthorizePrompt } from "./oauth.ts";
+
+// A local stdio server (launched as a child process) or a remote HTTP server.
+export type StdioServerConfig = { command: string; args?: string[]; env?: Record<string, string> };
+export type HttpServerConfig = { url: string; headers?: Record<string, string>; transport?: "http" | "sse" };
+export type McpServerConfig = StdioServerConfig | HttpServerConfig;
+export type McpServers = Record<string, McpServerConfig>;
+
+function isStdio(cfg: McpServerConfig): cfg is StdioServerConfig {
+  return typeof (cfg as StdioServerConfig).command === "string";
+}
+
+export interface McpToolDef {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+}
+
+// Read mcp.json from project then user scope (project overrides). Accepts either a
+// top-level map or a { "mcpServers": {...} } wrapper. An entry is kept if it names a
+// stdio `command` or a remote `url`; anything else is dropped.
+export function loadMcpServers(cwd: string = process.cwd()): McpServers {
+  const merge = (path: string, into: McpServers) => {
+    if (!existsSync(path)) return;
+    try {
+      const raw = JSON.parse(readFileSync(path, "utf8"));
+      const map = (raw && typeof raw === "object" && raw.mcpServers) || raw;
+      if (map && typeof map === "object") {
+        for (const [name, cfg] of Object.entries(map as Record<string, unknown>)) {
+          if (cfg && typeof cfg === "object") {
+            const c = cfg as Partial<StdioServerConfig & HttpServerConfig>;
+            if (typeof c.command === "string" || typeof c.url === "string") {
+              into[name] = cfg as McpServerConfig;
+            }
+          }
+        }
+      }
+    } catch {
+      /* malformed mcp.json → skip */
+    }
+  };
+  const servers: McpServers = {};
+  merge(globalPaths().mcp, servers);
+  merge(projectPaths(cwd).mcp, servers);
+  return servers;
+}
+
+// process.env as a clean string map, so stdio servers inherit our environment
+// (StdioClientTransport otherwise launches with a minimal default env).
+function inheritedEnv(extra?: Record<string, string>): Record<string, string> {
+  const base: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) if (v !== undefined) base[k] = v;
+  return { ...base, ...extra };
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} timed out`)), ms);
+    p.then((v) => (clearTimeout(timer), resolve(v)), (e) => (clearTimeout(timer), reject(e)));
+  });
+}
+
+// An MCP client over the official SDK, transport chosen from config: a local child
+// process (stdio) or a remote server (Streamable HTTP, falling back to legacy SSE).
+// Exposes only what the agent needs: connect, tools/list, tools/call, close.
+export class McpClient {
+  private client?: Client;
+
+  constructor(
+    private readonly name: string,
+    private readonly cfg: McpServerConfig,
+    private readonly cwd: string,
+    private readonly onAuthorize?: AuthorizePrompt,
+  ) {}
+
+  async connect(timeoutMs = 10_000): Promise<void> {
+    const client = new Client({ name: "privateer", version: "0.1.0" }, { capabilities: {} });
+    if (isStdio(this.cfg)) {
+      const transport = new StdioClientTransport({
+        command: this.cfg.command,
+        args: this.cfg.args ?? [],
+        env: inheritedEnv(this.cfg.env),
+        cwd: this.cwd,
+        stderr: "ignore", // keep server logs out of the TUI
+      });
+      await withTimeout(client.connect(transport), timeoutMs, `MCP server "${this.name}" connect`);
+      this.client = client;
+      return;
+    }
+
+    const url = new URL(this.cfg.url);
+    const requestInit = this.cfg.headers ? { headers: this.cfg.headers } : undefined;
+    // Static header auth wins. Otherwise attach an interactive OAuth provider — it
+    // stays dormant unless the server actually answers 401.
+    const authProvider = this.cfg.headers
+      ? undefined
+      : new FileOAuthProvider(this.name, this.cfg.url, this.onAuthorize);
+    const sse = () => new SSEClientTransport(url, { requestInit, authProvider });
+
+    if (this.cfg.transport === "sse") {
+      await this.tryConnect(client, sse, authProvider, timeoutMs);
+    } else {
+      const http = () => new StreamableHTTPClientTransport(url, { requestInit, authProvider });
+      try {
+        await this.tryConnect(client, http, authProvider, timeoutMs);
+      } catch (err) {
+        // A server that only speaks the legacy HTTP+SSE transport rejects the
+        // Streamable-HTTP handshake; retry once over SSE before giving up.
+        if (this.cfg.transport !== "http") await this.tryConnect(client, sse, authProvider, timeoutMs);
+        else throw err;
+      }
+    }
+    this.client = client;
+  }
+
+  // Connect with one transport kind. On a 401 with an OAuth provider configured,
+  // run the interactive consent dance (browser → loopback redirect → code →
+  // token exchange) and reconnect with a fresh transport that picks up the tokens.
+  private async tryConnect(
+    client: Client,
+    make: () => StreamableHTTPClientTransport | SSEClientTransport,
+    provider: FileOAuthProvider | undefined,
+    timeoutMs: number,
+  ): Promise<void> {
+    const transport = make();
+    try {
+      await withTimeout(client.connect(transport), timeoutMs, `MCP server "${this.name}" connect`);
+    } catch (err) {
+      if (err instanceof UnauthorizedError && provider) {
+        const code = await provider.waitForCode();
+        await transport.finishAuth(code);
+        await withTimeout(client.connect(make()), timeoutMs, `MCP server "${this.name}" reconnect`);
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  async listTools(): Promise<McpToolDef[]> {
+    const res = await this.client!.listTools();
+    return Array.isArray(res?.tools)
+      ? res.tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema as Record<string, unknown> }))
+      : [];
+  }
+
+  async callTool(name: string, args: unknown): Promise<string> {
+    const res = await this.client!.callTool({ name, arguments: (args ?? {}) as Record<string, unknown> });
+    return formatContent(res);
+  }
+
+  close(): void {
+    void this.client?.close();
+  }
+}
+
+function formatContent(result: any): string {
+  const content = result?.content;
+  if (Array.isArray(content)) {
+    const text = content
+      .map((c: any) => (c?.type === "text" ? c.text : `[${c?.type ?? "content"}]`))
+      .join("\n");
+    return result?.isError ? `Error: ${text}` : text || "(no output)";
+  }
+  return JSON.stringify(result ?? {});
+}
+
+// Adapt one server's MCP tools into AI-SDK tools, namespaced as "<server>__<tool>" and
+// routed through the permission gate (MCP calls are external, so they prompt by default).
+export function adaptMcpTools(
+  server: string,
+  client: McpClient,
+  defs: McpToolDef[],
+  gate: PermissionGate,
+): ToolSet {
+  const set: ToolSet = {};
+  for (const d of defs) {
+    const name = `${server}__${d.name}`;
+    set[name] = tool({
+      description: d.description ?? `${d.name} (MCP server: ${server})`,
+      inputSchema: jsonSchema((d.inputSchema as any) ?? { type: "object", properties: {} }),
+      execute: async (args: unknown) => {
+        const decision = await gate.request({
+          tool: name,
+          kind: "fetch",
+          title: `MCP ${server}: ${d.name}`,
+          detail: JSON.stringify(args ?? {}).slice(0, 120),
+        });
+        if (decision === "deny") throw new PermissionDeniedError(name);
+        return client.callTool(d.name, args);
+      },
+    });
+  }
+  return set;
+}
+
+export interface McpConnection {
+  tools: ToolSet;
+  clients: McpClient[];
+  status: { server: string; tools: number; error?: string }[];
+}
+
+// Connect every configured server, returning the merged toolset, the live clients (to
+// close on teardown), and a per-server status. Failures are isolated per server.
+export async function connectMcpServers(
+  servers: McpServers,
+  cwd: string,
+  gate: PermissionGate,
+  onAuthorize?: AuthorizePrompt,
+): Promise<McpConnection> {
+  const tools: ToolSet = {};
+  const clients: McpClient[] = [];
+  const status: McpConnection["status"] = [];
+  for (const [name, cfg] of Object.entries(servers)) {
+    const client = new McpClient(name, cfg, cwd, onAuthorize);
+    try {
+      await client.connect();
+      const defs = await client.listTools();
+      Object.assign(tools, adaptMcpTools(name, client, defs, gate));
+      clients.push(client);
+      status.push({ server: name, tools: defs.length });
+    } catch (err) {
+      client.close();
+      status.push({ server: name, tools: 0, error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+  return { tools, clients, status };
+}

package/src/mcp/oauth.ts

@@ -0,0 +1,245 @@
+import { createServer, type Server as HttpServer } from "node:http";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type {
+  OAuthClientInformation,
+  OAuthClientInformationFull,
+  OAuthClientMetadata,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import { globalPaths } from "../config/paths.ts";
+
+// Called when interactive consent is needed, so the host (e.g. the TUI) can show
+// the URL in case the browser doesn't open on its own.
+export type AuthorizePrompt = (info: { server: string; url: string }) => void;
+
+// Everything we persist between runs for one remote server. Written owner-only
+// (0600) since it holds OAuth tokens. `port` is pinned so the loopback redirect
+// URI stays stable across runs (and thus matches the registered client).
+interface AuthStore {
+  port?: number;
+  state?: string;
+  codeVerifier?: string;
+  clientInformation?: OAuthClientInformationFull;
+  tokens?: OAuthTokens;
+}
+
+const DEFAULT_PORT = 7777;
+const CALLBACK_PATH = "/oauth/callback";
+
+function authDir(): string {
+  return join(globalPaths().dir, "mcp-auth");
+}
+
+// One file per server, keyed by a short hash of its URL.
+function storePath(serverUrl: string): string {
+  const hash = createHash("sha256").update(serverUrl).digest("hex").slice(0, 16);
+  return join(authDir(), `${hash}.json`);
+}
+
+// An interactive OAuth 2.1 (PKCE + dynamic client registration) provider that
+// persists credentials to disk and catches the redirect on a loopback server.
+// One instance per remote server connection.
+export class FileOAuthProvider implements OAuthClientProvider {
+  private store: AuthStore;
+  private readonly path: string;
+  private port: number;
+  private server?: HttpServer;
+  private redirect?: { resolve: (code: string) => void; reject: (e: Error) => void };
+
+  constructor(
+    private readonly serverName: string,
+    private readonly serverUrl: string,
+    private readonly onAuthorize?: AuthorizePrompt,
+  ) {
+    this.path = storePath(serverUrl);
+    this.store = readStore(this.path);
+    const envPort = Number(process.env.PRIVATEER_OAUTH_PORT);
+    this.port = this.store.port ?? (Number.isInteger(envPort) ? envPort : DEFAULT_PORT);
+  }
+
+  get redirectUrl(): string {
+    return `http://127.0.0.1:${this.port}${CALLBACK_PATH}`;
+  }
+
+  get clientMetadata(): OAuthClientMetadata {
+    return {
+      client_name: "Privateer",
+      redirect_uris: [this.redirectUrl],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none", // public client (PKCE), no secret
+    };
+  }
+
+  clientInformation(): OAuthClientInformation | undefined {
+    return this.store.clientInformation;
+  }
+
+  saveClientInformation(info: OAuthClientInformationFull): void {
+    this.store.clientInformation = info;
+    this.persist();
+  }
+
+  tokens(): OAuthTokens | undefined {
+    return this.store.tokens;
+  }
+
+  saveTokens(tokens: OAuthTokens): void {
+    this.store.tokens = tokens;
+    this.persist();
+  }
+
+  saveCodeVerifier(verifier: string): void {
+    this.store.codeVerifier = verifier;
+    this.persist();
+  }
+
+  codeVerifier(): string {
+    if (!this.store.codeVerifier) throw new Error("no PKCE code verifier saved");
+    return this.store.codeVerifier;
+  }
+
+  state(): string {
+    this.store.state = randomBytes(16).toString("hex");
+    this.persist();
+    return this.store.state;
+  }
+
+  // Drop persisted credentials when the server says they're stale, so the next
+  // connect re-runs discovery / re-authorizes instead of looping on 401s.
+  invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): void {
+    if (scope === "all") this.store = { port: this.store.port };
+    else if (scope === "client") delete this.store.clientInformation;
+    else if (scope === "tokens") delete this.store.tokens;
+    else if (scope === "verifier") delete this.store.codeVerifier;
+    this.persist();
+  }
+
+  // Bind the loopback listener, open the browser, and arm the wait. The SDK calls
+  // this during auth() right before it throws UnauthorizedError.
+  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    await this.listen();
+    this.onAuthorize?.({ server: this.serverName, url: authorizationUrl.toString() });
+    openBrowser(authorizationUrl.toString());
+  }
+
+  // Resolves with the authorization code once the user is redirected back. Caller
+  // passes it to transport.finishAuth(). Always tears the listener down after.
+  waitForCode(timeoutMs = 300_000): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      const done = (fn: () => void) => {
+        clearTimeout(timer);
+        this.closeServer();
+        fn();
+      };
+      const timer = setTimeout(
+        () => done(() => reject(new Error(`OAuth for "${this.serverName}" timed out`))),
+        timeoutMs,
+      );
+      this.redirect = {
+        resolve: (code) => done(() => resolve(code)),
+        reject: (e) => done(() => reject(e)),
+      };
+    });
+  }
+
+  private listen(): Promise<void> {
+    if (this.server) return Promise.resolve();
+    return new Promise<void>((resolve, reject) => {
+      const server = createServer((req, res) => this.handleCallback(req.url ?? "", res));
+      server.once("error", (err) => reject(new Error(`OAuth loopback on port ${this.port}: ${err.message}`)));
+      server.listen(this.port, "127.0.0.1", () => {
+        this.server = server;
+        // Capture the actually-bound port (matters when port 0 = ephemeral) and pin
+        // it, so future runs reuse the same redirect URI the client registered with.
+        const addr = server.address();
+        if (addr && typeof addr === "object") this.port = addr.port;
+        this.store.port = this.port;
+        this.persist();
+        resolve();
+      });
+    });
+  }
+
+  private handleCallback(rawUrl: string, res: import("node:http").ServerResponse): void {
+    const url = new URL(rawUrl, this.redirectUrl);
+    if (url.pathname !== CALLBACK_PATH) {
+      res.writeHead(404).end();
+      return;
+    }
+    const code = url.searchParams.get("code");
+    const err = url.searchParams.get("error");
+    const state = url.searchParams.get("state");
+    res.writeHead(200, { "content-type": "text/html" });
+    res.end(
+      `<!doctype html><body style="font-family:system-ui;padding:2rem">` +
+        `<h2>${code ? "Authorized — you can close this tab." : "Authorization failed."}</h2>` +
+        `</body>`,
+    );
+    if (err) return this.redirect?.reject(new Error(`authorization error: ${err}`));
+    if (state && this.store.state && state !== this.store.state) {
+      return this.redirect?.reject(new Error("OAuth state mismatch (possible CSRF)"));
+    }
+    if (code) this.redirect?.resolve(code);
+    else this.redirect?.reject(new Error("authorization callback missing code"));
+  }
+
+  private closeServer(): void {
+    this.server?.close();
+    this.server = undefined;
+  }
+
+  private persist(): void {
+    mkdirSync(authDir(), { recursive: true });
+    tryChmod(authDir(), 0o700);
+    writeFileSync(this.path, JSON.stringify(this.store, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+    tryChmod(this.path, 0o600);
+  }
+}
+
+function readStore(path: string): AuthStore {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as AuthStore;
+  } catch {
+    return {};
+  }
+}
+
+function tryChmod(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    /* non-POSIX filesystem — best effort */
+  }
+}
+
+// Open a URL in the user's default browser. Best-effort and non-blocking; if it
+// fails the URL was already surfaced via the AuthorizePrompt callback.
+function openBrowser(url: string): void {
+  // Headless / CI / tests: skip the launch; the URL is surfaced via AuthorizePrompt.
+  if (process.env.PRIVATEER_NO_BROWSER) return;
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    const child = spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    /* headless / no browser — user uses the printed URL */
+  }
+}
+
+// Wipe stored OAuth state for one server (used by `/mcp logout`).
+export function clearStoredAuth(serverUrl: string): void {
+  const path = storePath(serverUrl);
+  if (existsSync(path)) rmSync(path, { force: true });
+}
+
+// Whether we hold an OAuth access token for this server (for `/mcp` status).
+export function hasStoredAuth(serverUrl: string): boolean {
+  return Boolean(readStore(storePath(serverUrl)).tokens?.access_token);
+}

package/src/memory/auto.ts

@@ -0,0 +1,146 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "../config/load.ts";
+import { parseFrontmatter } from "../commands/custom.ts";
+import { projectKey } from "./store.ts";
+
+// Agent-authored "auto-memory": durable facts the agent records across runs, modeled on
+// Claude Code's memory files. Each memory is one markdown file with flat frontmatter
+// (so it round-trips through parseFrontmatter, which only reads `key: value` lines) plus
+// a body. A per-scope MEMORY.md index lists them and is recalled into the system prompt.
+//
+// Two scopes: "project" memories live under the per-project dir (keyed by cwd) and only
+// recall in that project; "global" memories live under the global dir and recall
+// everywhere. Project memories win on a name clash.
+
+export type MemoryType = "user" | "feedback" | "project" | "reference";
+export type MemoryScope = "project" | "global";
+
+export interface MemoryRecord {
+  name: string;
+  description: string;
+  type: MemoryType;
+  scope: MemoryScope;
+  body: string;
+  path: string;
+}
+
+const INDEX_FILE = "MEMORY.md";
+const VALID_TYPES: MemoryType[] = ["user", "feedback", "project", "reference"];
+
+function memoryDir(scope: MemoryScope, cwd: string): string {
+  return scope === "global"
+    ? join(globalDir(), "memory")
+    : join(globalDir(), "projects", projectKey(cwd), "memory");
+}
+
+// Constrain a proposed name to a safe, kebab-ish file stem (no path traversal, no spaces).
+export function sanitizeName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^[-.]+|[-.]+$/g, "")
+    .slice(0, 80);
+}
+
+function coerceType(raw: string | undefined): MemoryType {
+  return VALID_TYPES.includes(raw as MemoryType) ? (raw as MemoryType) : "project";
+}
+
+function readDir(scope: MemoryScope, cwd: string): MemoryRecord[] {
+  const dir = memoryDir(scope, cwd);
+  if (!existsSync(dir)) return [];
+  const out: MemoryRecord[] = [];
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith(".md") || file === INDEX_FILE) continue;
+    const path = join(dir, file);
+    const { meta, body } = parseFrontmatter(readFileSync(path, "utf8"));
+    const name = meta.name || file.replace(/\.md$/, "");
+    out.push({
+      name,
+      description: meta.description ?? "",
+      type: coerceType(meta.type),
+      scope,
+      body: body.trim(),
+      path,
+    });
+  }
+  return out;
+}
+
+// Regenerate a scope's MEMORY.md from the memory files it contains. Regenerating (vs.
+// editing in place) keeps the index free of stale or duplicate lines.
+function rebuildIndex(scope: MemoryScope, cwd: string): void {
+  const dir = memoryDir(scope, cwd);
+  const records = readDir(scope, cwd).sort((a, b) => a.name.localeCompare(b.name));
+  const indexPath = join(dir, INDEX_FILE);
+  if (records.length === 0) {
+    if (existsSync(indexPath)) rmSync(indexPath, { force: true });
+    return;
+  }
+  const lines = [
+    "# Memory Index",
+    "",
+    ...records.map((r) => `- [${r.name}](${r.name}.md) — ${r.description}`),
+    "",
+  ];
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(indexPath, lines.join("\n"), "utf8");
+}
+
+// All memories visible from this cwd: project entries override global on a name clash.
+export function listMemories(cwd: string): MemoryRecord[] {
+  const byName = new Map<string, MemoryRecord>();
+  for (const r of readDir("global", cwd)) byName.set(r.name, r);
+  for (const r of readDir("project", cwd)) byName.set(r.name, r);
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function readMemory(cwd: string, name: string): MemoryRecord | null {
+  const key = sanitizeName(name);
+  return listMemories(cwd).find((r) => r.name === key) ?? null;
+}
+
+export function saveMemory(
+  cwd: string,
+  input: { name: string; description: string; type?: MemoryType; scope?: MemoryScope; body: string },
+): MemoryRecord {
+  const scope: MemoryScope = input.scope === "global" ? "global" : "project";
+  const name = sanitizeName(input.name);
+  if (!name) throw new Error("memory name is empty after sanitizing");
+  const type = coerceType(input.type);
+  const dir = memoryDir(scope, cwd);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${name}.md`);
+  const frontmatter = [
+    "---",
+    `name: ${name}`,
+    `description: ${input.description.replace(/\n/g, " ").trim()}`,
+    `type: ${type}`,
+    `scope: ${scope}`,
+    "---",
+  ].join("\n");
+  writeFileSync(path, `${frontmatter}\n${input.body.trim()}\n`, "utf8");
+  rebuildIndex(scope, cwd);
+  return { name, description: input.description, type, scope, body: input.body.trim(), path };
+}
+
+export function deleteMemory(cwd: string, name: string): MemoryRecord | null {
+  const existing = readMemory(cwd, name);
+  if (!existing) return null;
+  rmSync(existing.path, { force: true });
+  rebuildIndex(existing.scope, cwd);
+  return existing;
+}
+
+// The memory index(es) to recall into the system prompt, or null when there are none.
+export function loadMemoryContext(cwd: string): string | null {
+  const sections: string[] = [];
+  for (const scope of ["project", "global"] as const) {
+    const indexPath = join(memoryDir(scope, cwd), INDEX_FILE);
+    if (!existsSync(indexPath)) continue;
+    const body = readFileSync(indexPath, "utf8").trim();
+    if (body) sections.push(`(${scope})\n${body}`);
+  }
+  return sections.length ? sections.join("\n\n") : null;
+}