gigarag-claude-code 0.1.0

package/cli/mcp/client.js

@@ -0,0 +1,156 @@
+import { DEFAULT_MCP_URL, MAX_BATCH, version } from '../constants.js';
+export class McpHttpError extends Error {
+    status;
+    code;
+    constructor(message, status, code = undefined) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'McpHttpError';
+    }
+}
+const defaultSleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/**
+ * The one HTTP path to core's /mcp. The bridge, the library and the status
+ * command all go through it, so the 20-message ceiling and the 429 handling
+ * exist once.
+ */
+export class McpHttpClient {
+    url;
+    opts;
+    nextId = 1;
+    constructor(opts) {
+        this.opts = opts;
+        this.url = opts.url ?? DEFAULT_MCP_URL;
+    }
+    /** Sends one message or one batch. A batch over MAX_BATCH is split, never sent whole. */
+    async post(message) {
+        if (Array.isArray(message) && message.length > MAX_BATCH) {
+            const merged = [];
+            let status = 200;
+            for (let i = 0; i < message.length; i += MAX_BATCH) {
+                const part = await this.post(message.slice(i, i + MAX_BATCH));
+                status = part.status;
+                if (Array.isArray(part.body))
+                    merged.push(...part.body);
+                else if (part.body)
+                    merged.push(part.body);
+            }
+            return { status, body: merged };
+        }
+        return this.send(message, false);
+    }
+    async send(message, retriedAuth) {
+        const fetchImpl = this.opts.fetch ?? fetch;
+        const sleep = this.opts.sleep ?? defaultSleep;
+        const maxRetries = this.opts.maxRetries ?? 5;
+        const maxWait = this.opts.maxWaitSeconds ?? 60;
+        for (let attempt = 0;; attempt++) {
+            const auth = await this.opts.authorization();
+            const res = await fetchImpl(this.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/json, text/event-stream',
+                    'user-agent': this.opts.userAgent ?? `gigarag/${version()}`,
+                    ...(auth ? { authorization: auth } : {}),
+                },
+                body: JSON.stringify(message),
+                // A server that accepts the connection and never answers must not hold a client's request for good.
+                signal: AbortSignal.timeout(this.opts.timeoutMs ?? 120_000),
+            });
+            if (res.status === 429 && attempt < maxRetries) {
+                const asked = Number(res.headers.get('retry-after'));
+                // A missing header still backs off, so a limiter that forgets it does not get hammered.
+                const wait = Math.min(Number.isFinite(asked) && asked > 0 ? asked : 2 ** attempt, maxWait);
+                this.opts.onRetry?.(wait, attempt + 1);
+                await sleep(wait * 1000);
+                continue;
+            }
+            if (res.status === 401 && !retriedAuth && this.opts.onUnauthorized && (await this.opts.onUnauthorized())) {
+                return this.send(message, true);
+            }
+            return this.readResponse(res);
+        }
+    }
+    async readResponse(res) {
+        const text = await res.text();
+        const type = res.headers.get('content-type') ?? '';
+        let body;
+        if (text.trim()) {
+            try {
+                body = type.includes('text/event-stream') ? parseEventStream(text) : JSON.parse(text);
+            }
+            catch {
+                body = undefined;
+                // A proxy's HTML page on a 200 is not a reply, and passing it on as nothing would hang the caller.
+                if (res.status < 400)
+                    throw new McpHttpError('GigaRAG sent a reply that is not JSON. Something between here and the server may be rewriting it.', res.status);
+            }
+        }
+        if (res.status >= 400) {
+            const first = Array.isArray(body) ? body[0] : body;
+            throw new McpHttpError(describeFailure(res.status, first?.error?.message), res.status, codeOf(text));
+        }
+        return { status: res.status, body };
+    }
+    /** A single request, its id assigned here. Returns `result`, throws on a JSON-RPC error. */
+    async rpc(method, params) {
+        const id = this.nextId++;
+        const { body } = await this.post({ jsonrpc: '2.0', id, method, params });
+        const message = Array.isArray(body) ? body.find(m => m.id === id) : body;
+        if (!message)
+            throw new McpHttpError('The server sent no reply.', 0);
+        if (message.error)
+            throw new McpHttpError(message.error.message, 200, String(message.error.code));
+        return message.result;
+    }
+    async notify(method, params) {
+        await this.post({ jsonrpc: '2.0', method, params });
+    }
+}
+function codeOf(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.code === 'string')
+            return parsed.code;
+        if (typeof parsed.error === 'string')
+            return parsed.error;
+    }
+    catch {
+        /* not JSON */
+    }
+    return /invalid_api_key/.exec(text)?.[0];
+}
+export function describeFailure(status, detail) {
+    if (status === 401)
+        return 'GigaRAG did not accept the key (401). Run: gigarag login';
+    if (status === 403)
+        return 'This key is not allowed to do that (403).';
+    if (status === 429)
+        return 'GigaRAG is rate limiting this key (429) and retries ran out.';
+    if (status >= 500)
+        return `GigaRAG had a problem (HTTP ${status}). Try again shortly.`;
+    return detail ? `${detail} (HTTP ${status})` : `GigaRAG answered HTTP ${status}.`;
+}
+/** The `data:` payloads of a server-sent event stream, as messages. */
+export function parseEventStream(text) {
+    const messages = [];
+    for (const block of text.split(/\r?\n\r?\n/)) {
+        const data = block
+            .split(/\r?\n/)
+            .filter(line => line.startsWith('data:'))
+            .map(line => line.slice(5).trimStart())
+            .join('\n');
+        if (!data)
+            continue;
+        const parsed = JSON.parse(data);
+        if (Array.isArray(parsed))
+            messages.push(...parsed);
+        else
+            messages.push(parsed);
+    }
+    if (messages.length === 0)
+        return undefined;
+    return messages.length === 1 ? messages[0] : messages;
+}

package/cli/mcp/session.js

@@ -0,0 +1,79 @@
+import { readConfig } from '../config.js';
+import { DEFAULT_MCP_URL } from '../constants.js';
+import { loadCredential, refreshOAuth } from '../auth/credentials.js';
+import { McpHttpClient } from './client.js';
+import { assertSecureUrl } from '../secureUrl.js';
+export { assertSecureUrl };
+export class NotSignedInError extends Error {
+    constructor() {
+        super('Not signed in to GigaRAG. Run: gigarag login');
+        this.name = 'NotSignedInError';
+    }
+}
+/** The endpoint: an explicit option, then `GIGARAG_MCP_URL`, then what login stored, then production. */
+export function resolveUrl(explicit) {
+    return assertSecureUrl(explicit ?? process.env['GIGARAG_MCP_URL'] ?? readConfig().mcpUrl ?? DEFAULT_MCP_URL);
+}
+const REFRESH_MARGIN_MS = 60_000;
+/**
+ * A client wired to whatever credential this machine holds. OAuth tokens refresh themselves, on
+ * expiry and on a 401.
+ *
+ * A refresh token works once. Three things follow. The refreshed pair replaces the one held here,
+ * so the next call does not present a spent token. Concurrent calls share one refresh. And before
+ * refreshing, the stored credential is read again, because a bridge runs in every client the person
+ * uses and another of them may have refreshed already, in which case its pair is the one to use.
+ */
+export function createClient(options = {}) {
+    let credential = options.apiKey
+        ? { type: 'key', key: options.apiKey }
+        : (options.credential ?? loadCredential());
+    const fetchImpl = options.fetch ?? fetch;
+    let refreshing;
+    const refresh = (current) => {
+        refreshing ??= (async () => {
+            const stored = options.credential || options.apiKey ? undefined : loadCredential();
+            if (stored?.type === 'oauth' && stored.accessToken !== current.accessToken) {
+                const fresh = !stored.expiresAt || stored.expiresAt - Date.now() > REFRESH_MARGIN_MS;
+                if (fresh)
+                    return stored;
+            }
+            try {
+                return await refreshOAuth(current, fetchImpl);
+            }
+            catch (err) {
+                // Another process may have spent this refresh token a moment ago and saved a new pair.
+                const again = options.credential || options.apiKey ? undefined : loadCredential();
+                if (again?.type === 'oauth' && again.refreshToken !== current.refreshToken)
+                    return again;
+                throw err;
+            }
+        })().finally(() => {
+            refreshing = undefined;
+        });
+        return refreshing;
+    };
+    return new McpHttpClient({
+        ...options,
+        url: resolveUrl(options.url),
+        authorization: async () => {
+            if (!credential)
+                throw new NotSignedInError();
+            if (credential.type === 'oauth' && credential.refreshToken && credential.expiresAt && credential.expiresAt - Date.now() < REFRESH_MARGIN_MS) {
+                credential = await refresh(credential);
+            }
+            return `Bearer ${credential.type === 'key' ? credential.key : credential.accessToken}`;
+        },
+        onUnauthorized: async () => {
+            if (credential?.type !== 'oauth' || !credential.refreshToken)
+                return false;
+            try {
+                credential = await refresh(credential);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    });
+}

package/cli/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "gigarag",
+  "version": "0.1.0",
+  "type": "module"
+}

package/cli/paths.js

@@ -0,0 +1,34 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** The state directory. `GIGARAG_HOME` exists so tests never touch the real one. */
+export function stateDir(env = process.env) {
+    return env['GIGARAG_HOME'] || join(homedir(), '.gigarag');
+}
+export function currentPlatform() {
+    const p = process.platform;
+    return p === 'win32' || p === 'darwin' ? p : 'linux';
+}
+/**
+ * Expands the path forms clients.json uses: `~`, `%APPDATA%`, `%USERPROFILE%`,
+ * `%LOCALAPPDATA%`, `$XDG_CONFIG_HOME`, `$CLAUDE_CONFIG_DIR`. Pure, so every platform is testable
+ * from any platform.
+ */
+export function expandPath(input, platform, env, home) {
+    const appData = env['APPDATA'] || join(home, 'AppData', 'Roaming');
+    const localAppData = env['LOCALAPPDATA'] || join(home, 'AppData', 'Local');
+    const xdg = env['XDG_CONFIG_HOME'] || join(home, '.config');
+    let out = input
+        .replace(/^~(?=$|[\\/])/, () => home)
+        .replaceAll('%APPDATA%', () => appData)
+        .replaceAll('%LOCALAPPDATA%', () => localAppData)
+        .replaceAll('%USERPROFILE%', () => home)
+        .replaceAll('$XDG_CONFIG_HOME', () => xdg)
+        // Claude Code keeps ~/.claude.json inside this folder when it is set.
+        .replaceAll('$CLAUDE_CONFIG_DIR', () => env['CLAUDE_CONFIG_DIR'] || home);
+    out = platform === 'win32' ? out.replaceAll('/', '\\') : out.replaceAll('\\', '/');
+    return out;
+}
+/** The tilde form of a path, for printing. Keeps output short and free of usernames in logs. */
+export function tildify(path, home = homedir()) {
+    return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}

package/cli/prompts.generated.js

@@ -0,0 +1,44 @@
+// Generated by scripts/gen-prompts.mjs from plugins/claude-code. Do not edit by hand.
+// Run `npm run build` after changing a command.
+export const PROMPTS = [
+    {
+        name: "gigadocs",
+        description: "Ingest external documentation into GigaRAG so it can be searched later",
+        argumentHint: "<url>",
+        arguments: [{ "name": "url", "description": "Documentation URL to ingest.", "required": true }],
+        needsShell: false,
+        text: "Run the CLI as `gigarag`. If the shell says it is not found, use `npx -y gigarag` in its place, with the same arguments.\n\nIngest the documentation at $ARGUMENTS into GigaRAG.\n\nIf that is empty or is not a URL, ask me for one and stop.\n\nThe bucket is named for the site: the hostname with dots turned into hyphens and any leading `www` dropped, so docs.stripe.com becomes `docs-stripe-com`. Find it with `list_buckets`, and create it if it is missing, with the site name as the title.\n\nThen:\n1. Fetch the page. Follow links that stay on the same host and sit under the same path prefix as the starting URL, up to two levels deep and at most 30 pages. Skip anchors, downloads, login pages and anything that repeats a page you already have. Say so if you hit the 30 page limit.\n2. For each page, first call `search_nodes` for its URL. If a memo already carries that URL, update it in place with `update_node` instead of creating a duplicate, so running this twice does not double the bucket.\n3. Otherwise `create_node`. The title is the page's own title. The summary is one or two sentences on what the page covers. The body opens with the line `Source: <url>, retrieved <today's date>`, then the page's content as clean markdown: keep headings, code blocks and tables, drop navigation, footers, cookie banners and repeated menus.\n4. A memo body holds at most 10,000 characters. For a longer page, split at a heading into several memos titled \"Page title, part 2\" and so on, and link each part to the next in its text as `[Page title, part 2](N:12)`.\n5. Set `node_type` to `doc` and `actor` to `agent:claude-code`.\n\nWhen you finish, tell me the bucket, how many pages you created and updated, how many you skipped and why, and one example query I could try with `/gigarecall`.",
+    },
+    {
+        name: "gigaindex",
+        description: "Index a codebase into GigaRAG, one bucket per repository",
+        argumentHint: "[path]",
+        arguments: [{ "name": "path", "description": "Folder to index. Defaults to the current directory.", "required": false }],
+        needsShell: true,
+        text: "Run the CLI as `gigarag`. If the shell says it is not found, use `npx -y gigarag` in its place, with the same arguments.\n\nThis needs a shell tool, because it runs the `gigarag` command. If you have no way to run shell commands, say so in one sentence and stop. Do not guess at what the repository contains.\n\nIndex a codebase into GigaRAG. The path to index is: \"$ARGUMENTS\". If that is empty, use the current directory.\n\nDo the work yourself, in this conversation, following the procedure below. When you finish, tell the user in five lines or fewer: the bucket, how many memos you created, updated and deleted, anything you could not index and why, and whether the index is up to date. Do not paste the file list.\n\n## Procedure\n\nThe work is split on purpose. The `gigarag` command does the mechanical half: it walks the tree, respects gitignore, hashes contents, plans chunk boundaries and works out what changed. You do the judgement half: what a module is for, what is worth summarising, and what links to what. Never walk the filesystem yourself with ls or find. The manifest names every file you need.\n\n## 1. Scan\n\nRun `gigarag scan <path>` with the path you were given, or the current directory. It prints a JSON manifest. Read these fields:\n\n- `repo.slug` is the bucket. `repo.root` is the repository root.\n- `files` lists new and changed files, each with `path`, `hash`, `status`, `lines`, `language`, `nodeIds` (memos already made from it) and sometimes `chunks` (line ranges, when the file is too long for one memo).\n- `removed` lists files that are gone, each with `nodeIds` and `deleteNodeIds`.\n- `truncated: true` means the walk hit its limit. Tell the user in your report and carry on with what you have.\n\nIf `files` and `removed` are both empty, report \"Up to date\" and stop.\n\n## 2. Find or create the bucket and threads\n\nCall `list_buckets` with `q` set to the slug. Use the bucket whose slug matches exactly, or `create_bucket` with that slug, the repository name as the title, and a one line description. Slugs are lowercase letters, digits and hyphens, at most 64 characters.\n\nGroup memos into threads by the top level area of the repository: `src`, `docs`, `tests`, `config`. Look them up with `list_threads` for the bucket and create the missing ones. Keep the number of threads under about ten.\n\n## 3. Write the memos\n\nWork in batches of about ten files. For each file:\n\n- Read it with the Read tool. When it has `chunks`, read one range at a time using `offset` and `limit`.\n- Write a memo that explains the file to somebody who has not read it. Cover what it is for, its public surface (exported names and signatures, not their bodies), how it connects to the rest of the system, and any non-obvious constraint. Aim for 500 to 2,500 characters. Do not paste the source. A memo that only restates the code is worse than none.\n- Very small files that only make sense together, such as a folder of three tiny helpers, may share one memo. Give each of those files the same node when you record them.\n- The title says what the module is, for example \"Session token refresh\". The summary is one or two sentences. `node_type` is `code` for source, `doc` for markdown and prose, `config` for configuration. The slug comes from the path, for example `src-auth-session-ts`. Set `actor` to `agent:gigarag-indexer`.\n- A body holds at most 10,000 characters. For a long file with `chunks`, write one memo per chunk and a short parent memo that links to them.\n- If `nodeIds` is not empty, the file was indexed before. Call `update_node` on that node instead of creating a second one, and keep the `[Title](N:12)` links already in its text unless the thing they point at is gone.\n- Where this memo depends on another module, link it in the text as `[Module name](N:12)`. Get the ref from `find_nodes` with part of the title, or from a memo you have already written this run. Never write a UUID as a link target. After each write, look at `unresolved_links` in the reply and fix or remove any ref that did not resolve.\n\n## 4. Record progress after every batch\n\nAfter each batch, pipe the result to `gigarag record` so a later run updates in place and an interrupted run can resume. Send JSON on stdin:\n\n{\"repo\":\"<slug>\",\"files\":[{\"path\":\"src/auth.ts\",\"hash\":\"<hash from the manifest>\",\"nodes\":[{\"id\":\"<node id>\",\"ref\":\"N:12\",\"title\":\"Session token refresh\",\"type\":\"code\",\"tokens\":600}]}]}\n\n`tokens` is your rough estimate of what fetching the memo costs, at about four characters a token. Do this per batch, not once at the end.\n\n## 5. Remove what is gone\n\nFor each entry in `removed`, call `delete_node` for every id in its `deleteNodeIds`. For memos that other files still feed, use `update_node` to take the removed file out of the text. Then record it:\n\n{\"repo\":\"<slug>\",\"removed\":[{\"path\":\"src/old.ts\",\"deletedNodeIds\":[\"<node id>\"]}]}\n\nWithout this half the index only ever grows and drifts away from the repository while still looking correct.\n\n## Rate limits\n\nIf a tool answers that you are rate limited, wait and continue. Do not start over. Files you have already recorded are skipped by the next `gigarag scan`, so an interrupted index resumes where it stopped.\n\n## Report\n\nEnd with this, and nothing longer:\n\n- Bucket: the slug\n- Memos: created N, updated N, deleted N\n- Not indexed: what and why, or \"none\"\n- Status: up to date, or what is left",
+    },
+    {
+        name: "gigarecall",
+        description: "Search GigaRAG and load what it knows into this conversation",
+        argumentHint: "<what to recall>",
+        arguments: [{ "name": "query", "description": "What to recall.", "required": true }],
+        needsShell: false,
+        text: "Run the CLI as `gigarag`. If the shell says it is not found, use `npx -y gigarag` in its place, with the same arguments.\n\nRecall what GigaRAG knows about: $ARGUMENTS\n\nIf that is empty, ask me what to recall and stop.\n\n1. Call `search_nodes` with my question in plain words, limit 8. It combines exact-term and meaning-based search, so a paraphrase works as well as an identifier.\n2. Read the two to four most relevant hits in full with `fetch_node`. Search returns only a snippet, so do not answer from snippets alone.\n3. If a memo links to another that looks necessary to answer, read that one too with `fetch_node`, or use `neighbors`. Stop after about six memos in total.\n4. Give me what you found: the facts that answer the question, each with the ref of the memo it came from, like N:12. Say which memos disagree, if any do, and which is newer. If a memo is marked superseded, say so and prefer what replaced it.\n\nIf nothing relevant came back, say that plainly and suggest one different phrasing to try. Do not fill the gap from general knowledge, and do not save anything.",
+    },
+    {
+        name: "gigasave",
+        description: "Save this session's decisions and discoveries to GigaRAG as memos",
+        argumentHint: "[what to focus on]",
+        arguments: [{ "name": "focus", "description": "What to save. Defaults to the whole conversation.", "required": false }],
+        needsShell: false,
+        text: "Run the CLI as `gigarag`. If the shell says it is not found, use `npx -y gigarag` in its place, with the same arguments.\n\nSave what this session decided or learned into GigaRAG, so the next session, on any machine or in any client, can find it. If I gave a focus (\"$ARGUMENTS\"), save only that. Otherwise go through the whole conversation.\n\nFind the bucket first: run `gigarag repo --slug` and use that slug. If no bucket has it yet, create one with that slug.\n\nWhat is worth a memo:\n- A decision, with why it was made and what was rejected. \"We chose X over Y because Z\" is the best kind.\n- A discovery that took effort: why something behaves as it does, a constraint nobody wrote down, a bug's real cause.\n- A convention agreed for this codebase.\n- An open question somebody still has to answer.\n\nWhat is not: chatter, status updates, anything already obvious from the code or the git log, and anything secret. Never save keys, tokens, passwords or personal data, even if they appeared in the conversation.\n\nFor each one:\n1. Call `search_nodes` with the topic first. If a memo already covers it, update that memo with `update_node`, keeping the links already in its text, instead of creating a second one.\n2. Otherwise `create_node` in a thread called `decisions` in that bucket (create the thread if it is missing). Use the type `decision` for decisions and `note` for everything else. Set `actor` to `agent:claude-code`.\n3. The title states the point (\"Use cursor pagination for /events\"), not the topic (\"Pagination\"). The summary is one or two sentences. The body has the context, the decision, why, and what was rejected.\n4. Where a memo relates to another, link it in the text as `[Title](N:12)`, using the ref from `find_nodes`. Never write a UUID as a link target.\n\nAt the end, list what you saved as one line each: the ref, the title, and whether it was created or updated. If there was nothing worth saving, say so and save nothing.",
+    },
+    {
+        name: "gigasync",
+        description: "Bring GigaRAG up to date with the files that changed since the last index",
+        argumentHint: "",
+        arguments: [],
+        needsShell: true,
+        text: "Run the CLI as `gigarag`. If the shell says it is not found, use `npx -y gigarag` in its place, with the same arguments.\n\nThis needs a shell tool, because it runs the `gigarag` command. If you have no way to run shell commands, say so in one sentence and stop. Do not guess at what the repository contains.\n\nRun `gigarag scan --summary` in the current directory and read the counts.\n\nIf nothing is new, changed or gone, say \"GigaRAG is up to date with this repository.\" and stop.\n\nOtherwise do an incremental sync yourself, in this conversation, following the procedure below and touching only the files the scan reports. When you finish, tell the user in three lines or fewer what changed: memos created, updated and deleted.\n\n## Procedure\n\nThe work is split on purpose. The `gigarag` command does the mechanical half: it walks the tree, respects gitignore, hashes contents, plans chunk boundaries and works out what changed. You do the judgement half: what a module is for, what is worth summarising, and what links to what. Never walk the filesystem yourself with ls or find. The manifest names every file you need.\n\n## 1. Scan\n\nRun `gigarag scan <path>` with the path you were given, or the current directory. It prints a JSON manifest. Read these fields:\n\n- `repo.slug` is the bucket. `repo.root` is the repository root.\n- `files` lists new and changed files, each with `path`, `hash`, `status`, `lines`, `language`, `nodeIds` (memos already made from it) and sometimes `chunks` (line ranges, when the file is too long for one memo).\n- `removed` lists files that are gone, each with `nodeIds` and `deleteNodeIds`.\n- `truncated: true` means the walk hit its limit. Tell the user in your report and carry on with what you have.\n\nIf `files` and `removed` are both empty, report \"Up to date\" and stop.\n\n## 2. Find or create the bucket and threads\n\nCall `list_buckets` with `q` set to the slug. Use the bucket whose slug matches exactly, or `create_bucket` with that slug, the repository name as the title, and a one line description. Slugs are lowercase letters, digits and hyphens, at most 64 characters.\n\nGroup memos into threads by the top level area of the repository: `src`, `docs`, `tests`, `config`. Look them up with `list_threads` for the bucket and create the missing ones. Keep the number of threads under about ten.\n\n## 3. Write the memos\n\nWork in batches of about ten files. For each file:\n\n- Read it with the Read tool. When it has `chunks`, read one range at a time using `offset` and `limit`.\n- Write a memo that explains the file to somebody who has not read it. Cover what it is for, its public surface (exported names and signatures, not their bodies), how it connects to the rest of the system, and any non-obvious constraint. Aim for 500 to 2,500 characters. Do not paste the source. A memo that only restates the code is worse than none.\n- Very small files that only make sense together, such as a folder of three tiny helpers, may share one memo. Give each of those files the same node when you record them.\n- The title says what the module is, for example \"Session token refresh\". The summary is one or two sentences. `node_type` is `code` for source, `doc` for markdown and prose, `config` for configuration. The slug comes from the path, for example `src-auth-session-ts`. Set `actor` to `agent:gigarag-indexer`.\n- A body holds at most 10,000 characters. For a long file with `chunks`, write one memo per chunk and a short parent memo that links to them.\n- If `nodeIds` is not empty, the file was indexed before. Call `update_node` on that node instead of creating a second one, and keep the `[Title](N:12)` links already in its text unless the thing they point at is gone.\n- Where this memo depends on another module, link it in the text as `[Module name](N:12)`. Get the ref from `find_nodes` with part of the title, or from a memo you have already written this run. Never write a UUID as a link target. After each write, look at `unresolved_links` in the reply and fix or remove any ref that did not resolve.\n\n## 4. Record progress after every batch\n\nAfter each batch, pipe the result to `gigarag record` so a later run updates in place and an interrupted run can resume. Send JSON on stdin:\n\n{\"repo\":\"<slug>\",\"files\":[{\"path\":\"src/auth.ts\",\"hash\":\"<hash from the manifest>\",\"nodes\":[{\"id\":\"<node id>\",\"ref\":\"N:12\",\"title\":\"Session token refresh\",\"type\":\"code\",\"tokens\":600}]}]}\n\n`tokens` is your rough estimate of what fetching the memo costs, at about four characters a token. Do this per batch, not once at the end.\n\n## 5. Remove what is gone\n\nFor each entry in `removed`, call `delete_node` for every id in its `deleteNodeIds`. For memos that other files still feed, use `update_node` to take the removed file out of the text. Then record it:\n\n{\"repo\":\"<slug>\",\"removed\":[{\"path\":\"src/old.ts\",\"deletedNodeIds\":[\"<node id>\"]}]}\n\nWithout this half the index only ever grows and drifts away from the repository while still looking correct.\n\n## Rate limits\n\nIf a tool answers that you are rate limited, wait and continue. Do not start over. Files you have already recorded are skipped by the next `gigarag scan`, so an interrupted index resumes where it stopped.\n\n## Report\n\nEnd with this, and nothing longer:\n\n- Bucket: the slug\n- Memos: created N, updated N, deleted N\n- Not indexed: what and why, or \"none\"\n- Status: up to date, or what is left",
+    },
+];

package/cli/prompts.js

@@ -0,0 +1,48 @@
+import { PROMPTS } from './prompts.generated.js';
+export { PROMPTS };
+export function listPrompts() {
+    return PROMPTS.map(p => ({
+        name: p.name,
+        // The command name is the product, so it is also the display name.
+        title: `/${p.name}`,
+        description: p.description,
+        arguments: p.arguments,
+    }));
+}
+export class UnknownPromptError extends Error {
+    constructor(name) {
+        super(`Unknown prompt: ${name}`);
+        this.name = 'UnknownPromptError';
+    }
+}
+export class MissingArgumentError extends Error {
+    constructor(prompt, argument) {
+        super(`Prompt ${prompt} needs the argument "${argument}"`);
+        this.name = 'MissingArgumentError';
+    }
+}
+/**
+ * Renders one prompt. Prompt arguments are always strings in MCP, and this
+ * package's commands each take at most one, so the value replaces `$ARGUMENTS`
+ * wherever it appears. An unknown argument name is ignored rather than refused,
+ * because clients differ in how they name the single free-text slot.
+ */
+export function getPrompt(name, args = {}) {
+    const def = PROMPTS.find(p => p.name === name);
+    if (!def)
+        throw new UnknownPromptError(name);
+    const first = def.arguments[0];
+    let value = '';
+    if (first) {
+        const given = args[first.name];
+        // A client that fills in one free-text box may not use our argument name, so take the only value it sent.
+        const fallback = Object.values(args).find(v => typeof v === 'string');
+        value = typeof given === 'string' ? given : typeof fallback === 'string' ? fallback : '';
+        if (first.required && value.trim() === '')
+            throw new MissingArgumentError(name, first.name);
+    }
+    return {
+        description: def.description,
+        messages: [{ role: 'user', content: { type: 'text', text: def.text.replaceAll('$ARGUMENTS', () => value.trim()) } }],
+    };
+}

package/cli/scan/chunk.js

@@ -0,0 +1,43 @@
+import { MAX_CONTENT_LENGTH } from '../constants.js';
+const BOUNDARY = /^(#{1,6}\s|(export\s+)?(async\s+)?(function|class|interface|type|const|def|fn|func|pub|impl|struct|enum|module|package)\b)/;
+/**
+ * Splits a file into ranges of lines, each short enough for one memo.
+ *
+ * A memo body is capped at 10,000 characters and headings decide how the server
+ * sections it, so the plan breaks where a heading or a top-level declaration
+ * starts, or at a blank line, and only mid-block when a block is longer than
+ * the limit by itself. The limit here is lower than the server's, so the agent
+ * has room for a title line and a summary around the excerpt.
+ */
+export function planChunks(text, max = MAX_CONTENT_LENGTH - 1000) {
+    if (text.length <= max)
+        return [];
+    const lines = text.split('\n');
+    // A trailing newline ends the last line; it does not start another one.
+    if (lines.length > 1 && lines[lines.length - 1] === '')
+        lines.pop();
+    const chunks = [];
+    let start = 0;
+    let size = 0;
+    let lastBreak = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const cost = line.length + 1;
+        if (size + cost > max && i > start) {
+            // Prefer the last natural boundary in the back half of this chunk.
+            const half = start + Math.floor((i - start) / 2);
+            const cut = lastBreak > half ? lastBreak : i;
+            chunks.push({ start: start + 1, end: cut });
+            start = cut;
+            size = lines.slice(start, i).reduce((n, l) => n + l.length + 1, 0);
+            lastBreak = -1;
+        }
+        if (i > start && (line.trim() === '' || BOUNDARY.test(line))) {
+            lastBreak = BOUNDARY.test(line) ? i : i + 1;
+        }
+        size += cost;
+    }
+    if (start < lines.length)
+        chunks.push({ start: start + 1, end: lines.length });
+    return chunks;
+}

package/cli/scan/ignore.js

@@ -0,0 +1,117 @@
+/**
+ * A gitignore matcher with no dependencies. It covers what real repositories
+ * use: negation, anchoring, directory-only patterns, `**`, `?`, `*` and
+ * character classes. Patterns are relative to the directory that holds the
+ * ignore file, so each .gitignore in a tree gets its own matcher.
+ */
+function escapeRegex(ch) {
+    return /[.+^${}()|\\]/.test(ch) ? `\\${ch}` : ch;
+}
+/** Translates one gitignore glob (already stripped of `!`, leading and trailing slash) to a regex source. */
+function globToRegex(glob) {
+    let out = '';
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === '*') {
+            if (glob[i + 1] === '*') {
+                const before = i === 0 || glob[i - 1] === '/';
+                const after = glob[i + 2] === '/' || i + 2 >= glob.length;
+                if (before && after) {
+                    // `**/` matches zero or more directories, a trailing `/**` matches everything inside.
+                    if (glob[i + 2] === '/') {
+                        out += '(?:.*/)?';
+                        i += 2;
+                    }
+                    else {
+                        out += '.*';
+                        i += 1;
+                    }
+                    continue;
+                }
+                out += '[^/]*';
+                i += 1;
+                continue;
+            }
+            out += '[^/]*';
+        }
+        else if (ch === '?') {
+            out += '[^/]';
+        }
+        else if (ch === '[') {
+            const end = glob.indexOf(']', i + 2);
+            if (end < 0) {
+                out += '\\[';
+            }
+            else {
+                let cls = glob.slice(i + 1, end);
+                if (cls.startsWith('!'))
+                    cls = `^${cls.slice(1)}`;
+                out += `[${cls.replace(/\\/g, '\\\\')}]`;
+                i = end;
+            }
+        }
+        else if (ch === '\\' && i + 1 < glob.length) {
+            out += escapeRegex(glob[++i]);
+        }
+        else {
+            out += escapeRegex(ch);
+        }
+    }
+    return out;
+}
+function parseLine(raw) {
+    let line = raw.replace(/\r$/, '');
+    if (line === '' || line.startsWith('#'))
+        return undefined;
+    // Trailing spaces are dropped unless escaped with a backslash.
+    line = line.replace(/(?<!\\)\s+$/, '');
+    if (line === '')
+        return undefined;
+    let negate = false;
+    if (line.startsWith('!')) {
+        negate = true;
+        line = line.slice(1);
+    }
+    if (line.startsWith('\\#') || line.startsWith('\\!'))
+        line = line.slice(1);
+    let dirOnly = false;
+    if (line.endsWith('/')) {
+        dirOnly = true;
+        line = line.slice(0, -1);
+    }
+    if (line === '')
+        return undefined;
+    // A slash anywhere but the end anchors the pattern to this directory. Without one it matches at any depth.
+    const anchored = line.includes('/');
+    if (line.startsWith('/'))
+        line = line.slice(1);
+    const body = globToRegex(line);
+    const regex = new RegExp(`^${anchored ? '' : '(?:.*/)?'}${body}$`);
+    return { regex, negate, dirOnly };
+}
+export class Ignore {
+    rules;
+    constructor(source) {
+        this.rules = source
+            .split('\n')
+            .map(parseLine)
+            .filter((r) => r !== undefined);
+    }
+    get empty() {
+        return this.rules.length === 0;
+    }
+    /**
+     * `undefined` when no rule speaks to the path, so a parent's verdict can stand.
+     * The last matching rule wins, which is what makes `!keep.log` work.
+     */
+    test(relPath, isDir) {
+        let verdict;
+        for (const rule of this.rules) {
+            if (rule.dirOnly && !isDir)
+                continue;
+            if (rule.regex.test(relPath))
+                verdict = !rule.negate;
+        }
+        return verdict;
+    }
+}

package/cli/scan/repo.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+/** Walks up from `start` to the directory holding `.git`, or returns `start` when there is none. */
+export function findRepoRoot(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, '.git')))
+            return { root: dir, git: true };
+        const parent = dirname(dir);
+        if (parent === dir)
+            return { root: resolve(start), git: false };
+        dir = parent;
+    }
+}
+/** The path a checkout's `.git` points at, for worktrees and submodules where `.git` is a file. */
+function gitDir(root) {
+    const dot = join(root, '.git');
+    try {
+        if (statSync(dot).isDirectory())
+            return dot;
+        const text = readFileSync(dot, 'utf8');
+        const m = /^gitdir:\s*(.+)$/m.exec(text);
+        if (!m)
+            return undefined;
+        const target = resolve(root, m[1].trim());
+        // A worktree keeps the config in the main repository, two levels up from its own gitdir.
+        const common = join(target, 'commondir');
+        if (existsSync(common))
+            return resolve(target, readFileSync(common, 'utf8').trim());
+        return target;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `remote "origin"` url, read from the config file so no git binary runs. */
+export function readOriginUrl(root) {
+    const dir = gitDir(root);
+    if (!dir)
+        return undefined;
+    try {
+        const text = readFileSync(join(dir, 'config'), 'utf8');
+        let inOrigin = false;
+        for (const line of text.split(/\r?\n/)) {
+            const header = /^\s*\[(.+)\]\s*$/.exec(line);
+            if (header) {
+                inOrigin = /^remote\s+"origin"$/.test(header[1].trim());
+                continue;
+            }
+            const url = inOrigin ? /^\s*url\s*=\s*(.+?)\s*$/.exec(line) : null;
+            if (url)
+                return url[1];
+        }
+    }
+    catch {
+        /* no config */
+    }
+    return undefined;
+}
+/** `git@github.com:acme/api.git` and `https://github.com/acme/api` both become `acme-api`. */
+export function slugFromRemote(remote) {
+    const cleaned = remote.trim().replace(/\/+$/, '').replace(/\.git$/, '');
+    const m = /[:/]([^:/]+)\/([^:/]+)$/.exec(cleaned) ?? /[:/]([^:/]+)$/.exec(cleaned);
+    if (!m)
+        return undefined;
+    const parts = m.slice(1).filter(Boolean);
+    return slugify(parts.join('-'));
+}
+/** Lowercase letters, digits and hyphens, at most 64 characters: what a bucket slug accepts. */
+export function slugify(input) {
+    const slug = input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64)
+        .replace(/-+$/, '');
+    return slug || 'repo';
+}
+/** The slug for a folder with no remote: its name, then six hex characters of where it is. */
+export function localSlug(root) {
+    const key = process.platform === 'win32' ? root.toLowerCase() : root;
+    const hash = createHash('sha256').update(key).digest('hex').slice(0, 6);
+    return `${slugify(basename(root)).slice(0, 57).replace(/-+$/, '')}-${hash}`;
+}
+/**
+ * One bucket per repository. The slug comes from the remote where there is one,
+ * so two checkouts of the same repo on two machines share a bucket.
+ *
+ * Without a remote it is the directory name plus a short hash of the path. Two projects that are both
+ * called `app` would otherwise share one file table, and a scan of the second would report the
+ * first one's files as deleted and offer to delete their memos.
+ */
+export function repoInfo(start) {
+    const { root, git } = findRepoRoot(start);
+    const remote = git ? readOriginUrl(root) : undefined;
+    const slug = (remote && slugFromRemote(remote)) || localSlug(root);
+    return { root, slug, ...(remote ? { remote } : {}) };
+}