gigarag-cursor 0.1.0

package/.cursor-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "gigarag",
+  "description": "Your GigaRAG knowledge base inside Cursor: index a codebase, save decisions, recall them later.",
+  "version": "0.1.0",
+  "author": { "name": "GigaRAG", "url": "https://gigarag.com" },
+  "homepage": "https://gigarag.com/connect/cursor",
+  "license": "UNLICENSED",
+  "keywords": ["memory", "rag", "knowledge-base", "mcp"]
+}

package/README.md

@@ -0,0 +1,29 @@
+# GigaRAG for Cursor
+
+Your GigaRAG knowledge base inside Cursor.
+
+## Install
+
+Install the CLI first, with `npm install -g gigarag` or the standalone installer, because the plugin's own copy is not on your terminal's PATH. Then run `gigarag connect cursor` for the MCP server alone. For the skills as well, install this folder as a plugin: copy it to `~/.cursor/plugins/local/gigarag` for local use, or import the repository through a team marketplace.
+
+Sign in once with `gigarag login`.
+
+## Skills
+
+| Skill | Does |
+|---|---|
+| `/gigaindex [path]` | Index a codebase into a bucket named for the repository |
+| `/gigasync` | Update only the files that changed since the last index |
+| `/gigasave` | Write this session's decisions into memos |
+| `/gigarecall <query>` | Search, and load the results into the conversation |
+| `/gigadocs <url>` | Ingest external documentation |
+
+These are generated from the Claude Code plugin by `scripts/build-plugins.mjs`, so the prompts match.
+
+## Not included yet
+
+Hooks. Cursor's hook payloads are supported by `gigarag hook sessionStart|afterFileEdit|stop`, but where a plugin declares them is not documented well enough to ship, so wire them by hand in `.cursor/hooks.json` if you want them.
+
+## How it finds the CLI
+
+`scripts/run.mjs` uses, in order: the `GIGARAG_CLI` path, the copy in the plugin's `cli/` folder, a `gigarag` on your PATH, then `npx`.

package/cli/auth/credentials.js

@@ -0,0 +1,106 @@
+import { readConfig } from '../config.js';
+import { assertSecureUrl } from '../secureUrl.js';
+import { DEFAULT_ISSUER } from '../constants.js';
+import { deleteSecret, getSecret, setSecret } from '../secrets.js';
+const ACCOUNT = 'default';
+/**
+ * The shape agent keys take, `gr_live_<region>_<32 base62>_<6 hex>`. Checked
+ * loosely: a format that changes must not lock people out.
+ */
+export function looksLikeAgentKey(value) {
+    return /^gr_[a-z]+_[a-z0-9]+_[A-Za-z0-9_]{16,}$/.test(value.trim());
+}
+/**
+ * The key from `GIGARAG_API_KEY`, or undefined. An empty value is nothing, and so is an
+ * unfilled `${...}` template: a host that failed to substitute its own setting must not
+ * have that text sent to the server as a credential.
+ */
+export function envKey(env = process.env) {
+    const value = env['GIGARAG_API_KEY']?.trim();
+    return value && !value.startsWith('${') ? value : undefined;
+}
+/** `GIGARAG_API_KEY` wins, so CI and containers need no login step. */
+export function loadCredential(env = process.env) {
+    const fromEnv = envKey(env);
+    if (fromEnv)
+        return { type: 'key', key: fromEnv };
+    const stored = getSecret(ACCOUNT);
+    if (!stored)
+        return undefined;
+    try {
+        const parsed = JSON.parse(stored.value);
+        if (parsed.type === 'key' && parsed.key)
+            return parsed;
+        if (parsed.type === 'oauth' && parsed.accessToken)
+            return parsed;
+    }
+    catch {
+        /* fall through */
+    }
+    return undefined;
+}
+/** Stores a credential and returns where it went, for the "connected" line. */
+export function saveCredential(credential) {
+    return setSecret(ACCOUNT, JSON.stringify(credential));
+}
+export function clearCredential() {
+    deleteSecret(ACCOUNT);
+}
+export function credentialSource(env = process.env) {
+    if (envKey(env))
+        return 'the GIGARAG_API_KEY environment variable';
+    return getSecret(ACCOUNT)?.store;
+}
+/** `gr_live_eu_*****`, for printing. */
+export function mask(key) {
+    const m = /^(gr_[a-z]+_[a-z0-9]+_)/.exec(key);
+    return `${m ? m[1] : key.slice(0, 6)}*****`;
+}
+const REFRESH_MARGIN_MS = 60_000;
+/**
+ * The Authorization header value, refreshing an OAuth token that is about to
+ * lapse and writing the rotated pair back. Refresh tokens are single use on the
+ * server, so a refresh that succeeds but is not saved would lock the next call
+ * out.
+ */
+export async function authorizationHeader(credential, fetchImpl = fetch, now = Date.now) {
+    if (credential.type === 'key')
+        return `Bearer ${credential.key}`;
+    if (credential.expiresAt && credential.refreshToken && credential.expiresAt - now() < REFRESH_MARGIN_MS) {
+        const refreshed = await refreshOAuth(credential, fetchImpl, now);
+        return `Bearer ${refreshed.accessToken}`;
+    }
+    return `Bearer ${credential.accessToken}`;
+}
+export async function refreshOAuth(credential, fetchImpl = fetch, now = Date.now) {
+    if (!credential.refreshToken)
+        throw new Error('The sign-in has expired. Run: gigarag login');
+    assertSecureUrl(credential.tokenEndpoint, 'The token endpoint');
+    const res = await fetchImpl(credential.tokenEndpoint, {
+        signal: AbortSignal.timeout(30_000),
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+        body: new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: credential.refreshToken,
+            client_id: credential.clientId,
+        }),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || typeof body['access_token'] !== 'string') {
+        throw new Error(body['error'] === 'invalid_grant'
+            ? 'The sign-in has expired or was revoked. Run: gigarag login'
+            : `Could not refresh the sign-in (HTTP ${res.status}).`);
+    }
+    const next = {
+        ...credential,
+        accessToken: body['access_token'],
+        refreshToken: typeof body['refresh_token'] === 'string' ? body['refresh_token'] : credential.refreshToken,
+        expiresAt: typeof body['expires_in'] === 'number' ? now() + body['expires_in'] * 1000 : undefined,
+    };
+    saveCredential(next);
+    return next;
+}
+export function configuredIssuer() {
+    return readConfig().issuer ?? DEFAULT_ISSUER;
+}

package/cli/auth/oauth.js

@@ -0,0 +1,203 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { DEFAULT_MCP_URL } from '../constants.js';
+import { assertSecureUrl } from '../secureUrl.js';
+import { PAGE_HEADERS, pageConnected, pageFailed, pageForeign } from './page.js';
+/** Ports the CLI tries, in order. The app accepts a redirect on any loopback port in this range. */
+export const LOGIN_PORTS = [8765, 8766, 8767, 8768, 8769, 8770, 8771, 8772, 8773, 8774, 8775];
+const b64url = (buf) => buf.toString('base64url');
+export function pkcePair() {
+    const verifier = b64url(randomBytes(48));
+    return { verifier, challenge: b64url(createHash('sha256').update(verifier).digest()) };
+}
+export async function discover(issuer, fetchImpl) {
+    const url = `${issuer.replace(/\/$/, '')}/.well-known/oauth-authorization-server`;
+    assertSecureUrl(issuer, 'The sign-in server');
+    const res = await fetchImpl(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(30_000) });
+    if (!res.ok)
+        throw new Error(`Could not reach GigaRAG sign-in at ${issuer} (HTTP ${res.status}).`);
+    const meta = (await res.json().catch(() => undefined));
+    if (!meta || typeof meta.authorization_endpoint !== 'string' || typeof meta.token_endpoint !== 'string') {
+        throw new Error('GigaRAG sign-in metadata is incomplete.');
+    }
+    // The metadata names where a code and a refresh token get sent, so it must name the server that was asked
+    // and only endpoints that are encrypted.
+    if (meta.issuer !== undefined && meta.issuer.replace(/\/$/, '') !== issuer.replace(/\/$/, '')) {
+        throw new Error(`The sign-in server at ${issuer} says it is ${meta.issuer}, so it was not trusted.`);
+    }
+    assertSecureUrl(meta.authorization_endpoint, 'The sign-in page');
+    assertSecureUrl(meta.token_endpoint, 'The token endpoint');
+    if (meta.registration_endpoint)
+        assertSecureUrl(meta.registration_endpoint, 'The registration endpoint');
+    return meta;
+}
+/** Tries each port until one is free. The machine that already has 8765 bound is somebody's daily driver. */
+export function listenOnFirstFree(server, ports) {
+    return new Promise((resolve, reject) => {
+        const attempt = (i) => {
+            const port = ports[i];
+            if (port === undefined) {
+                reject(new Error(`No free port for the sign-in callback (tried ${ports[0]} to ${ports[ports.length - 1]}).`));
+                return;
+            }
+            const onError = (err) => {
+                server.off('listening', onListening);
+                if (err.code === 'EADDRINUSE' || err.code === 'EACCES')
+                    attempt(i + 1);
+                else
+                    reject(err);
+            };
+            const onListening = () => {
+                server.off('error', onError);
+                resolve(server.address().port);
+            };
+            server.once('error', onError);
+            server.once('listening', onListening);
+            server.listen(port, '127.0.0.1');
+        };
+        attempt(0);
+    });
+}
+export function openBrowser(url) {
+    const [cmd, args] = process.platform === 'win32'
+        ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+        : process.platform === 'darwin'
+            ? ['open', [url]]
+            : ['xdg-open', [url]];
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true });
+    child.on('error', () => {
+        /* the URL is printed too, so a missing opener is not fatal */
+    });
+    child.unref();
+}
+/**
+ * Authorization code with PKCE, redirecting to a loopback port.
+ *
+ * Nothing here handles a password or a key. The browser does the signing in,
+ * and what comes back is a single-use code that only this process can redeem,
+ * because only it holds the verifier.
+ */
+export async function runOAuthLogin(opts) {
+    const fetchImpl = opts.fetch ?? fetch;
+    const log = opts.log ?? (() => undefined);
+    const now = opts.now ?? Date.now;
+    const meta = await discover(opts.issuer, fetchImpl);
+    const resource = opts.resource ?? DEFAULT_MCP_URL;
+    const scope = opts.scope ?? 'read write offline_access';
+    const state = b64url(randomBytes(24));
+    const { verifier, challenge } = pkcePair();
+    let settle;
+    const outcome = new Promise(resolve => {
+        settle = resolve;
+    });
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        if (url.pathname !== '/callback') {
+            res.writeHead(404).end();
+            return;
+        }
+        const fail = (message) => {
+            // Settle only once the page has been sent. The caller closes this server as soon as it is
+            // settled, and closing first cut the connection before the browser got the explanation.
+            res.once('close', () => settle({ error: message }));
+            res.writeHead(400, PAGE_HEADERS).end(pageFailed(message));
+        };
+        // Anything on this machine can hit the port. A request that does not carry this login's state is
+        // turned away without ending the login, or a stray request could cancel it.
+        if (url.searchParams.get('state') !== state) {
+            res.writeHead(400, PAGE_HEADERS).end(pageForeign());
+            return;
+        }
+        const err = url.searchParams.get('error');
+        if (err)
+            return fail(`GigaRAG reported: ${url.searchParams.get('error_description') ?? err}.`);
+        const iss = url.searchParams.get('iss');
+        if (meta.authorization_response_iss_parameter_supported && iss !== meta.issuer) {
+            return fail('The sign-in response came from an unexpected server.');
+        }
+        const code = url.searchParams.get('code');
+        if (!code)
+            return fail('The sign-in response carried no code.');
+        res
+            .writeHead(200, PAGE_HEADERS)
+            .end(pageConnected());
+        settle({ code });
+    });
+    const port = await listenOnFirstFree(server, opts.ports ?? LOGIN_PORTS);
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    try {
+        let clientId = opts.clientId;
+        if (!clientId) {
+            if (!meta.registration_endpoint)
+                throw new Error('GigaRAG sign-in does not allow new clients.');
+            const reg = await fetchImpl(meta.registration_endpoint, {
+                signal: AbortSignal.timeout(30_000),
+                method: 'POST',
+                headers: { 'content-type': 'application/json', accept: 'application/json' },
+                body: JSON.stringify({
+                    client_name: 'GigaRAG CLI',
+                    redirect_uris: [redirectUri],
+                    grant_types: ['authorization_code', 'refresh_token'],
+                    response_types: ['code'],
+                    token_endpoint_auth_method: 'none',
+                    scope,
+                }),
+            });
+            const regBody = (await reg.json().catch(() => ({})));
+            if (!reg.ok || !regBody.client_id)
+                throw new Error(`Could not register with GigaRAG sign-in (HTTP ${reg.status}).`);
+            clientId = regBody.client_id;
+        }
+        const authorize = new URL(meta.authorization_endpoint);
+        authorize.search = new URLSearchParams({
+            response_type: 'code',
+            client_id: clientId,
+            redirect_uri: redirectUri,
+            code_challenge: challenge,
+            code_challenge_method: 'S256',
+            state,
+            scope,
+            resource,
+        }).toString();
+        log(`Opening your browser. If nothing opens, go to:\n${authorize.toString()}`);
+        await (opts.open ?? openBrowser)(authorize.toString());
+        const timeout = new Promise(resolve => setTimeout(() => resolve({ error: 'Timed out waiting for the browser. Run gigarag login again.' }), opts.timeoutMs ?? 300_000).unref());
+        const result = await Promise.race([outcome, timeout]);
+        if ('error' in result)
+            throw new Error(result.error);
+        const tokenRes = await fetchImpl(meta.token_endpoint, {
+            signal: AbortSignal.timeout(30_000),
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+            body: new URLSearchParams({
+                grant_type: 'authorization_code',
+                code: result.code,
+                redirect_uri: redirectUri,
+                client_id: clientId,
+                code_verifier: verifier,
+                resource,
+            }),
+        });
+        const tokens = (await tokenRes.json().catch(() => ({})));
+        if (!tokenRes.ok || typeof tokens['access_token'] !== 'string') {
+            throw new Error(`GigaRAG would not issue a token (${String(tokens['error_description'] ?? tokens['error'] ?? tokenRes.status)}).`);
+        }
+        return {
+            clientId,
+            scope: typeof tokens['scope'] === 'string' ? tokens['scope'] : undefined,
+            credential: {
+                type: 'oauth',
+                accessToken: tokens['access_token'],
+                refreshToken: typeof tokens['refresh_token'] === 'string' ? tokens['refresh_token'] : undefined,
+                expiresAt: typeof tokens['expires_in'] === 'number' ? now() + tokens['expires_in'] * 1000 : undefined,
+                clientId,
+                tokenEndpoint: meta.token_endpoint,
+            },
+        };
+    }
+    finally {
+        server.close();
+        server.closeAllConnections?.();
+    }
+}

package/cli/auth/page.js

@@ -0,0 +1,68 @@
+/**
+ * The page the browser lands on after sign-in, served from the loopback port.
+ *
+ * It follows the app's design guide (DESIGNS.md in the GigaRAG repo): dark only, the #040709 ground,
+ * a flat #111111 card with a 1px #242424 border, the slate accent, white for the title and the
+ * ink ramp below it, weights 400 and 500, and the brand logomark. No scripts and no external
+ * files, so the content security policy that goes with it can forbid both.
+ */
+/** The text comes from the URL, and any page in a browser can open this port, so it is escaped. */
+const escapeHtml = (s) => s.replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`);
+/** The logomark from the app's brand folder, verbatim, with its one fill lifted onto the svg. */
+const LOGOMARK = '<svg class="mark" role="img" aria-label="GigaRAG" width="60" height="60" viewBox="9.75 9.75 38.5 38.25" fill="#84B8D0" xmlns="http://www.w3.org/2000/svg"><rect width="7.24054" height="7.24054" rx="2.31697" transform="matrix(-1 0 0 1 32.6445 10.3429)"/><path d="M17.8742 22.7966C18.2924 24.2419 18.8644 24.7166 20.3359 25.1135C18.5624 25.4869 18.1457 26.2802 17.5845 27.5753C17.3025 26.2873 16.6843 25.8317 15.5572 25.2584C16.9728 24.7429 17.6397 24.1232 17.8742 22.7966Z"/><path d="M15.3443 32.3496C16.7767 31.8888 17.2343 31.303 17.5874 29.8204C18.0132 31.5821 18.8784 32.1211 20.1896 32.6437C18.9104 32.9637 18.4123 33.5274 17.8726 34.6711C17.3155 33.2713 16.6773 32.5448 15.3443 32.3496Z"/><path d="M22.817 39.8814C24.2494 39.4206 24.7069 38.8348 25.0601 37.3522C25.4858 39.1139 26.3511 39.6529 27.6622 40.1755C26.3831 40.4955 25.9719 41.0576 25.4321 42.2012C24.8751 40.8015 24.1499 40.0765 22.817 39.8814Z"/><path d="M30.3463 32.3513C31.7786 31.8905 32.2362 31.3047 32.5894 29.822C33.0151 31.5837 33.8804 32.1228 35.1915 32.6454C33.9123 32.9654 33.5012 33.5275 32.9614 34.6711C32.4043 33.2713 31.6792 32.5464 30.3463 32.3513Z"/><path d="M32.933 22.507C33.3512 23.9523 33.7784 24.427 35.25 24.8239C33.4765 25.1973 33.2046 26.1354 32.6434 27.4305C32.3614 26.1424 31.5984 25.6869 30.4712 25.1136C31.8869 24.5981 32.6985 23.8335 32.933 22.507Z"/><rect width="7.24054" height="7.24054" rx="2.31697" transform="matrix(-1 0 0 1 25.1133 17.873)"/><rect width="7.24054" height="7.24054" rx="2.31697" transform="matrix(-1 0 0 1 17.584 25.1136)"/><rect width="7.24054" height="7.24054" rx="2.31697" transform="matrix(-1 0 0 1 25.084 32.6437)"/><rect width="7.24054" height="7.24054" rx="2.31697" transform="matrix(-1 0 0 1 32.6445 40.1739)"/><rect width="7.24054" height="7.24054" rx="2.31697" transform="matrix(-1 0 0 1 47.7051 25.1136)"/><rect width="7.24054" height="7.24054" rx="2.31697" transform="matrix(-1 0 0 1 40.1738 32.6437)"/><rect width="7.24054" height="7.24054" rx="2.31697" transform="matrix(-1 0 0 1 32.6445 25.1136)"/><rect width="7.24054" height="7.24054" rx="2.31697" transform="matrix(-1 0 0 1 40.1738 17.5834)"/><path d="M25.4037 15.1216C25.8219 16.567 26.2491 17.1865 27.7207 17.5834C25.9472 17.9568 25.6753 18.8949 25.1141 20.19C24.8321 18.9019 24.0691 18.4464 22.9419 17.873C24.3576 17.3576 25.1692 16.4482 25.4037 15.1216Z"/></svg>';
+/**
+ * The mark is the status. Each cell is numbered so the page can bring them in one after another,
+ * and so a failed sign-in can dim the whole mark and leave a single cell in the danger colour.
+ */
+const cells = (svg) => {
+    let i = 0;
+    return svg.replace(/<(rect|path)\b/g, m => `${m} style="--i:${i++}"`);
+};
+const CSS = `
+:root{color-scheme:dark}
+*{box-sizing:border-box}
+html{background:#040709}
+body{margin:0;min-height:100vh;display:flex;align-items:flex-start;justify-content:center;padding:18vh 16px 48px;background:#040709;color:#c7cbce;font-family:Geist,ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;font-size:15px;line-height:1.6;-webkit-font-smoothing:antialiased}
+main{width:100%;max-width:440px;background:#111111;border:1px solid #242424;border-radius:16px;padding:36px 32px 32px}
+.mark{display:block;width:60px;height:60px;margin-bottom:30px;overflow:visible}
+.ok .mark *{opacity:0;animation:cell .5s ease-out forwards;animation-delay:calc(var(--i) * 55ms + 120ms)}
+@keyframes cell{to{opacity:1}}
+.error .mark{fill:#3a4043}
+.error .mark rect:first-of-type{fill:#ef4444}
+h1{margin:0 0 10px;font-size:22px;font-weight:500;line-height:1.25;letter-spacing:-0.02em;color:#fff}
+p{margin:0;font-size:15px;color:#c7cbce}
+p+p{margin-top:12px;font-size:14px;color:#9ba0a4}
+code{font-family:"Geist Mono",ui-monospace,SFMono-Regular,Consolas,monospace;font-size:14px;color:#c7cbce;background:#1a1e22;border-radius:6px;padding:1px 6px}
+@media (prefers-reduced-motion:reduce){.ok .mark *{opacity:1;animation:none}}
+`;
+export function renderPage({ kind, title, body, hint }) {
+    const hintHtml = hint ? `<p>${hint}</p>` : '';
+    return (`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">` +
+        `<meta name="color-scheme" content="dark"><title>${escapeHtml(title)}</title><style>${CSS}</style></head>` +
+        `<body><main class="${kind}">${cells(LOGOMARK)}` +
+        `<h1>${escapeHtml(title)}</h1><p>${escapeHtml(body)}</p>${hintHtml}</main></body></html>`);
+}
+/** Set with the page: nothing may run and nothing may load, so text from the URL cannot do either. */
+export const PAGE_HEADERS = {
+    'content-type': 'text/html; charset=utf-8',
+    'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff',
+};
+export const pageConnected = () => renderPage({
+    kind: 'ok',
+    title: 'Connected to GigaRAG',
+    body: 'The CLI can now read and write your workspace.',
+    hint: 'You can close this tab and go back to your terminal.',
+});
+export const pageFailed = (message) => renderPage({
+    kind: 'error',
+    title: 'Sign-in did not finish',
+    body: message,
+    hint: 'Run <code>gigarag login</code> in your terminal to try again.',
+});
+export const pageForeign = () => renderPage({
+    kind: 'error',
+    title: 'This is not your sign-in',
+    body: 'That request does not belong to the sign-in that is in progress, so it was ignored.',
+});

package/cli/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+main(process.argv.slice(2)).then(code => {
+    process.exitCode = code;
+}, (e) => {
+    process.stderr.write(`gigarag: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exitCode = 1;
+});

package/cli/cli.js

@@ -0,0 +1,90 @@
+import { version } from './constants.js';
+import { err, out, UsageError } from './ui.js';
+const HELP = `gigarag ${version()}
+
+Connect GigaRAG to your AI clients.
+
+  gigarag login                    Sign in (paste a key, or --browser)
+  gigarag logout                   Delete the stored credential
+  gigarag connect [client...]      Add GigaRAG to your installed clients
+  gigarag status                   What is configured, and whether the key works
+
+  gigarag scan [path]              What changed in a repo since it was last indexed
+  gigarag repo [path]              Which bucket a directory belongs to
+  gigarag record                   Tell the local index what was indexed (reads JSON on stdin)
+
+  gigarag mcp                      The stdio bridge a client's config runs
+  gigarag auth-header              The auth header, for headersHelper
+  gigarag hook <event>             Hook handler for Claude Code (SessionStart, PostToolUse, Stop)
+
+Run gigarag <command> --help for details.`;
+/** Loaded on demand so a hook, which runs on every prompt of every session, pays for nothing it does not use. */
+const COMMANDS = {
+    login: async () => (await import('./commands/login.js')).login,
+    logout: async () => (await import('./commands/login.js')).logout,
+    connect: async () => (await import('./commands/connect.js')).connect,
+    status: async () => (await import('./commands/status.js')).status,
+    scan: async () => (await import('./commands/scan.js')).scan,
+    repo: async () => (await import('./commands/repo.js')).repo,
+    record: async () => (await import('./commands/record.js')).record,
+    mcp: async () => (await import('./commands/mcp.js')).mcp,
+    'auth-header': async () => (await import('./commands/authHeader.js')).authHeader,
+    'index-sync': async () => (await import('./commands/indexSync.js')).indexSync,
+};
+export async function main(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === 'help' || command === '--help' || command === '-h') {
+        out(HELP);
+        return 0;
+    }
+    if (command === '--version' || command === '-v' || command === 'version') {
+        out(version());
+        return 0;
+    }
+    if (command === 'hook')
+        return hook(rest);
+    const load = COMMANDS[command];
+    if (!load) {
+        err(`Unknown command "${command}".\n`);
+        err(HELP);
+        return 2;
+    }
+    try {
+        return await (await load())(rest);
+    }
+    catch (e) {
+        if (e instanceof UsageError) {
+            err(e.message);
+            return 2;
+        }
+        if (process.env['GIGARAG_DEBUG'])
+            throw e;
+        err(`gigarag: ${e.message}`);
+        return 1;
+    }
+}
+async function hook(rest) {
+    const event = rest[0];
+    if (!event) {
+        err('Usage: gigarag hook <SessionStart|PostToolUse|Stop>');
+        return 2;
+    }
+    // A hook must never break the session it runs in, so every failure ends as exit 0 and silence.
+    try {
+        const { runHook } = await import('./hooks.js');
+        const raw = process.stdin.isTTY ? '' : await readAll();
+        const output = await runHook(event, raw);
+        if (output)
+            out(output);
+    }
+    catch {
+        /* swallowed on purpose */
+    }
+    return 0;
+}
+async function readAll() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}