gigarag-claude-code 0.1.0

package/cli/scan/scan.js

@@ -0,0 +1,262 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, openSync, readSync, closeSync, readFileSync, readdirSync } from 'node:fs';
+import { extname, join, relative, resolve, sep } from 'node:path';
+import { planChunks } from './chunk.js';
+import { Ignore } from './ignore.js';
+import { repoInfo } from './repo.js';
+const ALWAYS_SKIP_DIRS = new Set([
+    '.git',
+    'node_modules',
+    '.venv',
+    'venv',
+    '__pycache__',
+    '.next',
+    '.nuxt',
+    '.turbo',
+    '.gigarag',
+    '.idea',
+    '.gradle',
+    'target',
+    'Pods',
+]);
+const SKIP_FILES = new Set([
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'bun.lockb',
+    'Cargo.lock',
+    'poetry.lock',
+    'composer.lock',
+    'Gemfile.lock',
+    'go.sum',
+    '.DS_Store',
+    '.gitignore',
+    '.gitattributes',
+    '.gigaragignore',
+    'Thumbs.db',
+]);
+/**
+ * Files that hold credentials. A scan feeds file contents to an agent that writes them into a shared
+ * workspace, so these are left out however the ignore files read.
+ */
+const SECRET_NAME = /^(\.env(\..*)?|\.npmrc|\.pypirc|\.netrc|\.git-credentials|id_(rsa|dsa|ecdsa|ed25519)|credentials(\.json)?|secrets?\.(json|ya?ml|toml)|.*\.(pem|key|p12|pfx|jks|keystore|kdbx|tfstate))$/i;
+const ENV_EXAMPLE = /^\.env\.(example|sample|template|dist)$/i;
+const BINARY_EXT = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.bmp', '.tiff', '.pdf', '.zip', '.gz', '.tar', '.tgz', '.7z',
+    '.rar', '.jar', '.war', '.exe', '.dll', '.so', '.dylib', '.bin', '.o', '.a', '.class', '.pyc', '.woff', '.woff2',
+    '.ttf', '.otf', '.eot', '.mp3', '.mp4', '.mov', '.avi', '.wav', '.ogg', '.webm', '.sqlite', '.db', '.wasm',
+    '.psd', '.ai', '.map',
+]);
+const LANGUAGES = {
+    '.ts': 'typescript', '.tsx': 'typescript', '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript',
+    '.cjs': 'javascript', '.py': 'python', '.rs': 'rust', '.go': 'go', '.java': 'java', '.kt': 'kotlin',
+    '.rb': 'ruby', '.php': 'php', '.cs': 'csharp', '.cpp': 'cpp', '.c': 'c', '.h': 'c', '.swift': 'swift',
+    '.md': 'markdown', '.mdx': 'markdown', '.json': 'json', '.yaml': 'yaml', '.yml': 'yaml', '.toml': 'toml',
+    '.sql': 'sql', '.sh': 'shell', '.ps1': 'powershell', '.html': 'html', '.css': 'css', '.scss': 'css',
+    '.vue': 'vue', '.svelte': 'svelte', '.txt': 'text',
+};
+/** Lines as an editor counts them: a trailing newline ends the last line rather than starting another. */
+export function countLines(text) {
+    if (text === '')
+        return 0;
+    const n = text.split('\n').length;
+    return text.endsWith('\n') ? n - 1 : n;
+}
+/** True when the first 8 KB contains a NUL byte, the usual tell for a binary file. */
+function looksBinary(path) {
+    const fd = openSync(path, 'r');
+    try {
+        const buf = Buffer.alloc(8192);
+        const n = readSync(fd, buf, 0, 8192, 0);
+        return buf.subarray(0, n).includes(0);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+const readIgnore = (path) => {
+    try {
+        const ig = new Ignore(readFileSync(path, 'utf8'));
+        return ig.empty ? undefined : ig;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The verdict of the nearest ignore file that speaks to `abs`, checking outward from the deepest. */
+function ignored(scopes, abs, isDir) {
+    for (let i = scopes.length - 1; i >= 0; i--) {
+        const scope = scopes[i];
+        const rel = relative(scope.base, abs).split(sep).join('/');
+        const verdict = scope.ignore.test(rel, isDir);
+        if (verdict !== undefined)
+            return verdict;
+    }
+    return false;
+}
+/**
+ * Walks a tree the way git would, hashing what it finds and comparing against
+ * what was indexed before. The judgement about what a file means stays with the
+ * agent; this only answers which files it needs to read.
+ */
+export function scanTree(start, options = {}) {
+    const repo = repoInfo(resolve(start));
+    const root = resolve(start);
+    const maxFiles = options.maxFiles ?? 5000;
+    const maxBytes = options.maxBytes ?? 512 * 1024;
+    const known = options.state?.files(repo.slug) ?? new Map();
+    const files = [];
+    const skipped = [];
+    const seen = new Set();
+    let truncated = false;
+    let skippedCount = 0;
+    const skip = (path, reason) => {
+        skippedCount++;
+        if (options.verbose)
+            skipped.push({ path, reason });
+    };
+    const walk = (dir, scopes) => {
+        if (truncated)
+            return;
+        const local = [...scopes];
+        for (const name of ['.gitignore', '.gigaragignore']) {
+            const ig = readIgnore(join(dir, name));
+            if (ig)
+                local.push({ base: dir, ignore: ig });
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1));
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (truncated)
+                return;
+            const abs = join(dir, entry.name);
+            const rel = relative(repo.root, abs).split(sep).join('/');
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (ALWAYS_SKIP_DIRS.has(entry.name) || ignored(local, abs, true))
+                    continue;
+                walk(abs, local);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (SKIP_FILES.has(entry.name)) {
+                skip(rel, 'lockfile or system file');
+                continue;
+            }
+            if (ignored(local, abs, false))
+                continue;
+            if (SECRET_NAME.test(entry.name) && !ENV_EXAMPLE.test(entry.name)) {
+                skip(rel, 'may hold credentials');
+                continue;
+            }
+            const ext = extname(entry.name).toLowerCase();
+            if (BINARY_EXT.has(ext) || /\.min\.(js|css)$/.test(entry.name)) {
+                skip(rel, 'binary or minified');
+                continue;
+            }
+            let stat;
+            try {
+                stat = lstatSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (stat.size > maxBytes) {
+                skip(rel, `larger than ${Math.round(maxBytes / 1024)} KB`);
+                continue;
+            }
+            try {
+                if (stat.size > 0 && looksBinary(abs)) {
+                    skip(rel, 'binary');
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (files.length >= maxFiles) {
+                truncated = true;
+                return;
+            }
+            let buf;
+            try {
+                buf = readFileSync(abs);
+            }
+            catch {
+                continue;
+            }
+            // The file can grow between the size check and the read.
+            if (buf.length > maxBytes) {
+                skip(rel, `larger than ${Math.round(maxBytes / 1024)} KB`);
+                continue;
+            }
+            const hash = createHash('sha256').update(buf).digest('hex').slice(0, 32);
+            const text = buf.toString('utf8');
+            const prior = known.get(rel);
+            // A file the hook marked dirty whose bytes match the index was saved without changing. Nothing to redo.
+            const status = !prior ? 'new' : prior.hash === hash ? 'unchanged' : 'changed';
+            seen.add(rel);
+            // Nothing will call record for an unchanged file, so this is the only place its flag can be cleared.
+            if (prior && prior.dirty === 1 && status === 'unchanged')
+                options.state?.clearDirty(repo.slug, rel);
+            const chunks = planChunks(text);
+            files.push({
+                path: rel,
+                status,
+                hash,
+                bytes: buf.length,
+                lines: countLines(text),
+                language: LANGUAGES[ext] ?? 'text',
+                ...(chunks.length > 0 ? { chunks } : {}),
+                nodeIds: options.state?.nodesOf(repo.slug, rel) ?? [],
+            });
+        }
+    };
+    // Ignore files between the repository root and the scanned directory still apply to it.
+    const inherited = [];
+    const between = relative(repo.root, root).split(sep).filter(Boolean);
+    const ancestors = between.length === 0 ? [] : [repo.root];
+    for (let i = 0; i < between.length - 1; i++)
+        ancestors.push(join(repo.root, ...between.slice(0, i + 1)));
+    for (const dir of ancestors) {
+        for (const name of ['.gitignore', '.gigaragignore']) {
+            const ig = readIgnore(join(dir, name));
+            if (ig)
+                inherited.push({ base: dir, ignore: ig });
+        }
+    }
+    walk(root, inherited);
+    // Only files under the scanned directory can be reported gone. A scan of one folder says nothing about the rest.
+    const prefix = between.join('/');
+    const inScope = (p) => prefix === '' || p === prefix || p.startsWith(`${prefix}/`);
+    const gone = truncated ? [] : [...known.keys()].filter(p => inScope(p) && !seen.has(p));
+    const orphans = options.state?.orphansIfRemoved(repo.slug, gone) ?? new Map();
+    const removed = gone.map(path => ({
+        path,
+        nodeIds: options.state?.nodesOf(repo.slug, path) ?? [],
+        deleteNodeIds: orphans.get(path) ?? [],
+    }));
+    const count = (s) => files.filter(f => f.status === s).length;
+    return {
+        repo,
+        scannedAt: new Date().toISOString(),
+        summary: {
+            new: count('new'),
+            changed: count('changed'),
+            unchanged: count('unchanged'),
+            removed: removed.length,
+            skipped: skippedCount,
+        },
+        files: options.all ? files : files.filter(f => f.status !== 'unchanged'),
+        removed,
+        ...(options.verbose ? { skipped } : {}),
+        truncated,
+    };
+}

package/cli/scan.js

@@ -0,0 +1,5 @@
+/** `gigarag/scan`: the tree walker behind `gigarag scan`. */
+export { scanTree } from './scan/scan.js';
+export { planChunks } from './scan/chunk.js';
+export { repoInfo, slugFromRemote, slugify } from './scan/repo.js';
+export { Ignore } from './scan/ignore.js';

package/cli/sdk.js

@@ -0,0 +1,130 @@
+import { McpHttpClient, McpHttpError } from './mcp/client.js';
+import { createClient } from './mcp/session.js';
+import { version } from './constants.js';
+export { McpHttpError };
+/**
+ * GigaRAG from your own code. Everything goes through the same client the
+ * stdio bridge uses, so batches are split under the server's ceiling and a 429
+ * is waited out rather than thrown.
+ */
+export class GigaRag {
+    client;
+    actor;
+    initialised;
+    constructor(options = {}) {
+        this.client = createClient(options);
+        this.actor = options.actor;
+    }
+    init() {
+        this.initialised ??= this.client
+            .rpc('initialize', {
+            protocolVersion: '2025-03-26',
+            capabilities: {},
+            clientInfo: { name: 'gigarag-sdk', version: version() },
+        })
+            .then(() => this.client.notify('notifications/initialized'))
+            .catch(err => {
+            this.initialised = undefined;
+            throw err;
+        });
+        return this.initialised;
+    }
+    async listTools() {
+        await this.init();
+        const result = await this.client.rpc('tools/list');
+        return result.tools;
+    }
+    /**
+     * Calls any tool the server offers and returns its parsed result. A tool added
+     * to core works here the day it ships.
+     */
+    async callTool(name, args = {}) {
+        await this.init();
+        const result = await this.client.rpc('tools/call', { name, arguments: args });
+        const text = result.content?.find(part => part.type === 'text')?.text ?? '';
+        if (result.isError)
+            throw new McpHttpError(text || `Tool ${name} failed.`, 200);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    withActor(args) {
+        return this.actor ? { ...args, actor: this.actor } : args;
+    }
+    async search(query, options = {}) {
+        const out = await this.callTool('search_nodes', {
+            query,
+            limit: options.limit,
+            bucket_id: options.bucketId,
+            thread_id: options.threadId,
+            node_type: options.nodeType,
+        });
+        return out.results;
+    }
+    /** One document in full: body, sections, links and near neighbours. */
+    fetch(nodeId, options = {}) {
+        return this.callTool('fetch_node', { node_id: nodeId, ...options });
+    }
+    listBuckets(options = {}) {
+        return this.callTool('list_buckets', options);
+    }
+    listThreads(options = {}) {
+        return this.callTool('list_threads', {
+            bucket_id: options.bucketId,
+            limit: options.limit,
+            after: options.after,
+        });
+    }
+    listNodes(options = {}) {
+        return this.callTool('list_nodes', {
+            bucket_id: options.bucketId,
+            thread_id: options.threadId,
+            node_type: options.nodeType,
+            limit: options.limit,
+            after: options.after,
+        });
+    }
+    /** Every document, following the cursor. Stops at `max` so a large workspace cannot run away. */
+    async *iterateNodes(options = {}) {
+        let after;
+        let seen = 0;
+        const max = options.max ?? Infinity;
+        do {
+            const page = await this.listNodes({ ...options, limit: 200, after });
+            for (const item of page.items) {
+                if (seen++ >= max)
+                    return;
+                yield item;
+            }
+            after = page.next_cursor ?? undefined;
+        } while (after);
+    }
+    createNode(input) {
+        return this.callTool('create_node', this.withActor({
+            thread_id: input.threadId,
+            slug: input.slug,
+            title: input.title,
+            summary: input.summary,
+            content: input.content,
+            node_type: input.nodeType,
+        }));
+    }
+    updateNode(nodeId, input) {
+        return this.callTool('update_node', this.withActor({
+            node_id: nodeId,
+            title: input.title,
+            summary: input.summary,
+            content: input.content,
+            thread_id: input.threadId,
+        }));
+    }
+    async deleteNode(nodeId) {
+        await this.callTool('delete_node', { node_id: nodeId });
+    }
+    usage() {
+        return this.callTool('usage');
+    }
+}

package/cli/secrets.js

@@ -0,0 +1,192 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureStateDir } from './config.js';
+import { stateDir } from './paths.js';
+const SERVICE = 'gigarag';
+function run(cmd, args, opts = {}) {
+    return spawnSync(cmd, args, {
+        encoding: 'utf8',
+        input: opts.input,
+        env: { ...process.env, ...opts.env },
+        timeout: 15_000,
+        windowsHide: true,
+    });
+}
+/** Windows Credential Locker through Windows PowerShell 5.1, which ships with every install. */
+class WindowsStore {
+    name = 'Windows Credential Manager';
+    script(body) {
+        return [
+            "$ErrorActionPreference='Stop'",
+            '[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime]',
+            '$v = New-Object Windows.Security.Credentials.PasswordVault',
+            body,
+        ].join('\n');
+    }
+    ps(body, secret) {
+        return run('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', this.script(body)], { env: secret === undefined ? {} : { GIGARAG_SECRET: secret } });
+    }
+    get(account) {
+        const r = this.ps(`try { $c = $v.Retrieve('${SERVICE}','${account}'); $c.RetrievePassword(); [Console]::Out.Write($c.Password) } catch { exit 3 }`);
+        return r.status === 0 && r.stdout ? r.stdout : undefined;
+    }
+    set(account, value) {
+        this.delete(account);
+        const r = this.ps(`$c = New-Object Windows.Security.Credentials.PasswordCredential -ArgumentList '${SERVICE}','${account}',$env:GIGARAG_SECRET; $v.Add($c)`, value);
+        return r.status === 0;
+    }
+    delete(account) {
+        this.ps(`try { $c = $v.Retrieve('${SERVICE}','${account}'); $v.Remove($c) } catch { }`);
+    }
+}
+class MacStore {
+    name = 'macOS Keychain';
+    get(account) {
+        const r = run('security', ['find-generic-password', '-s', SERVICE, '-a', account, '-w']);
+        return r.status === 0 ? r.stdout.replace(/\n$/, '') : undefined;
+    }
+    set(account, value) {
+        // -U updates in place. The value is on the command line for the length of one
+        // call, which `security` offers no stdin form to avoid.
+        return run('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', account, '-w', value]).status === 0;
+    }
+    delete(account) {
+        run('security', ['delete-generic-password', '-s', SERVICE, '-a', account]);
+    }
+}
+class LinuxStore {
+    name = 'the system keyring (libsecret)';
+    get(account) {
+        const r = run('secret-tool', ['lookup', 'service', SERVICE, 'account', account]);
+        return r.status === 0 && r.stdout ? r.stdout : undefined;
+    }
+    set(account, value) {
+        return (run('secret-tool', ['store', '--label=GigaRAG', 'service', SERVICE, 'account', account], { input: value })
+            .status === 0);
+    }
+    delete(account) {
+        run('secret-tool', ['clear', 'service', SERVICE, 'account', account]);
+    }
+}
+/** Windows refuses a rename over a file that another process has open for a moment, so it is tried a few times. */
+function renameWithRetry(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            renameSync(from, to);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            if (attempt >= 5 || (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES'))
+                throw err;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20 * (attempt + 1));
+        }
+    }
+}
+/** A file only the owner can read. The fallback, and the test backend. */
+export class FileStore {
+    dir;
+    name;
+    constructor(dir = stateDir) {
+        this.dir = dir;
+        this.name = 'a private file in ~/.gigarag';
+    }
+    file(account) {
+        return join(this.dir(), `${account}.secret`);
+    }
+    get(account) {
+        try {
+            return readFileSync(this.file(account), 'utf8') || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    set(account, value) {
+        try {
+            ensureStateDir();
+            mkdirSync(this.dir(), { recursive: true, mode: 0o700 });
+            // Written beside the target and renamed over it: a crash leaves the old secret rather than half a
+            // new one, and a bridge reading while another refreshes never sees a torn file. The temp file is
+            // private from the moment it exists.
+            const target = this.file(account);
+            const temp = `${target}.${process.pid}.tmp`;
+            try {
+                writeFileSync(temp, value, { mode: 0o600 });
+                chmodSync(temp, 0o600);
+                renameWithRetry(temp, target);
+            }
+            catch (err) {
+                try {
+                    unlinkSync(temp);
+                }
+                catch {
+                    /* never created */
+                }
+                throw err;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    delete(account) {
+        try {
+            if (existsSync(this.file(account)))
+                unlinkSync(this.file(account));
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/**
+ * The OS store, where there is one worth using.
+ *
+ * Not on Windows unless asked for with GIGARAG_KEYCHAIN=native. The Credential Locker has no
+ * command line, so reading it means starting PowerShell to call the vault API, and a program that
+ * starts PowerShell to read stored credentials is what behavioural antivirus engines are built to
+ * catch. Kaspersky flagged this very build as a credential-dumping tool for it. A key in a file under
+ * the user's profile, which Windows already restricts to that user, is what the AWS and npm CLIs use.
+ */
+function nativeStore() {
+    if (process.env['GIGARAG_KEYCHAIN'] === 'file')
+        return undefined;
+    if (process.platform === 'win32')
+        return process.env['GIGARAG_KEYCHAIN'] === 'native' ? new WindowsStore() : undefined;
+    if (process.platform === 'darwin')
+        return new MacStore();
+    const probe = spawnSync('secret-tool', ['--version'], { encoding: 'utf8', windowsHide: true });
+    return probe.error ? undefined : new LinuxStore();
+}
+const file = new FileStore();
+/**
+ * Reads the file first, then the OS store. The file costs nothing to read, and it holds the
+ * secret whenever the OS store was unavailable or refused it at write time. Trying it first also
+ * means a bridge start spawns no process at all in the common case.
+ */
+export function getSecret(account) {
+    const fileValue = file.get(account);
+    if (fileValue !== undefined)
+        return { value: fileValue, store: file.name };
+    const native = nativeStore();
+    const nativeValue = native?.get(account);
+    return native && nativeValue !== undefined ? { value: nativeValue, store: native.name } : undefined;
+}
+/** Writes to the OS store, or to the private file when there is none. Returns where it landed. */
+export function setSecret(account, value) {
+    const native = nativeStore();
+    if (native?.set(account, value)) {
+        file.delete(account);
+        return native.name;
+    }
+    if (!file.set(account, value))
+        throw new Error('Could not store the credential anywhere on this machine.');
+    return file.name;
+}
+export function deleteSecret(account) {
+    nativeStore()?.delete(account);
+    file.delete(account);
+}

package/cli/secureUrl.js

@@ -0,0 +1,18 @@
+/**
+ * The endpoint must be https, except a loopback address for local testing. The key is sent to
+ * whatever this names, so a config file, an environment variable or a flag that could point it
+ * at plain http or another host would hand the key to anyone on the path.
+ */
+export function assertSecureUrl(url, what = 'The GigaRAG endpoint') {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`${what} is not a valid URL: ${url}`);
+    }
+    const loopback = ['127.0.0.1', 'localhost', '[::1]', '::1'].includes(parsed.hostname);
+    if (parsed.protocol === 'https:' || (parsed.protocol === 'http:' && loopback))
+        return url;
+    throw new Error(`${what} must use https (http is only allowed for localhost): ${url}`);
+}