gigarag-cursor 0.1.2 → 0.2.1

package/cli/sync/worker.js

@@ -0,0 +1,159 @@
+import { spawn } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isSea } from 'node:sea';
+import { stateDir } from '../paths.js';
+import { State } from '../state.js';
+import { isClean } from '../git/git.js';
+import { maxRewriteFiles, writeNote } from './notes.js';
+import { syncSlug } from './slug.js';
+import { RepoSyncRemote } from './remote.js';
+import { claudeInvocation, findClaude, runRewriter } from './rewriter.js';
+import { finishSync, holderFor, leaseMetaKey, runStage, WORKER_LOCK_MS as LOCK_MS } from './stage.js';
+import { syncTarget } from './target.js';
+const TICK_MS = 4 * 60_000;
+const CHILD_TIMEOUT_MS = 40 * 60_000;
+const quietMs = () => {
+    const n = Number(process.env['GIGARAG_SYNC_QUIET_MS']);
+    return Number.isFinite(n) && n >= 0 ? n : 20_000;
+};
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+/** Starts the background worker for `root`, detached from whatever is calling this, and does not
+ * wait for it. Used by a git hook, and by `sync end`/`sync begin` when clearing the interactive
+ * marker frees a hook-mode sync that deferred behind it (its `deferred` note), so that commit
+ * gets synced once the marker is gone instead of waiting for another one to arrive. */
+export function spawnWorker(root) {
+    const [cmd, args] = isSea()
+        ? [process.execPath, ['sync', 'worker', root]]
+        : [process.execPath, [fileURLToPath(new URL('../bin.js', import.meta.url)), 'sync', 'worker', root]];
+    spawn(cmd, args, { detached: true, stdio: 'ignore', windowsHide: true, cwd: root }).unref();
+}
+/**
+ * What a git hook runs. Records that a sync was asked for and starts the
+ * worker detached, then returns, so the hook costs one Node start in the
+ * background. Every failure ends as exit 0 and silence.
+ */
+export async function hookEntry(_hook) {
+    try {
+        if (process.env['GIGARAG_NO_SYNC'] || process.env['GIGARAG_SYNC_WORKER'])
+            return 0;
+        const { root, git, slug } = syncSlug(process.cwd());
+        if (!git)
+            return 0;
+        const state = new State();
+        try {
+            state.setMeta(`sync_request:${slug}`, String(Date.now()));
+        }
+        finally {
+            state.close();
+        }
+        spawnWorker(root);
+    }
+    catch {
+        /* a hook never fails the git command that ran it */
+    }
+    return 0;
+}
+/**
+ * The background run. One per repository at a time (a local lock), started no
+ * sooner than the quiet period after the latest request, and run again if a
+ * request arrived while it worked, so a burst of commits costs one run.
+ */
+export async function runWorker(root) {
+    const target = syncTarget(resolve(root));
+    const state = new State();
+    const lockKey = `sync_run:${target.slug}`;
+    try {
+        if (!state.tryAcquire(lockKey, LOCK_MS))
+            return 0;
+        for (;;) {
+            const requested = Number(state.getMeta(`sync_request:${target.slug}`) ?? 0);
+            const wait = requested + quietMs() - Date.now();
+            if (wait > 0) {
+                await sleep(wait);
+                continue;
+            }
+            const started = Date.now();
+            state.setMeta(lockKey, String(started));
+            try {
+                await syncOnce(state, target);
+            }
+            finally {
+                // Release before looking for another request. A hook that fires between the sync
+                // finishing and this check must find the lock free, or its request is lost: this
+                // run is about to decide there is nothing left to do, and nothing else would ever
+                // look again.
+                state.setMeta(lockKey, '0');
+            }
+            if (Number(state.getMeta(`sync_request:${target.slug}`) ?? 0) <= started)
+                return 0;
+            if (!state.tryAcquire(lockKey, LOCK_MS))
+                return 0;
+        }
+    }
+    catch (e) {
+        state.setMeta(lockKey, '0');
+        writeNote(state, target.slug, { kind: 'failed', detail: e.message });
+        return 1;
+    }
+    finally {
+        state.close();
+    }
+}
+async function syncOnce(state, target) {
+    const stage = await runStage(state, target, { mode: 'hook' });
+    if (stage.kind === 'stop') {
+        if (stage.note)
+            writeNote(state, target.slug, stage.note);
+        return;
+    }
+    const remote = new RepoSyncRemote(target.rag(), stage.bucketId);
+    let token = stage.token;
+    try {
+        const { plan } = stage;
+        const work = plan.rewrite.length + plan.partial.length;
+        const commit = stage.head;
+        if (plan.suspicious) {
+            writeNote(state, target.slug, { kind: 'mass_delete', files: plan.goneCount });
+            return;
+        }
+        if (work === 0) {
+            await finishSync(state, target, { bucketId: stage.bucketId, token, mode: 'hook' });
+            return;
+        }
+        if (work > maxRewriteFiles()) {
+            writeNote(state, target.slug, { kind: 'needs_approval', files: work, ...(commit ? { commit } : {}) });
+            return;
+        }
+        if (!isClean(target.root)) {
+            writeNote(state, target.slug, { kind: 'dirty', files: plan.stale.length, ...(commit ? { commit } : {}) });
+            return;
+        }
+        const claude = process.env['GIGARAG_NO_REWRITE'] ? undefined : findClaude(process.env, process.platform);
+        if (!claude) {
+            writeNote(state, target.slug, { kind: 'no_agent', files: plan.stale.length, ...(commit ? { commit } : {}) });
+            return;
+        }
+        const outcome = await runRewriter(claudeInvocation(claude, process.platform), target.root, join(stateDir(), 'logs', `sync-${target.slug}.log`), {
+            timeoutMs: CHILD_TIMEOUT_MS,
+            tickMs: TICK_MS,
+            onTick: async () => {
+                const renewed = await remote.claim(holderFor(state, 'hook'), token);
+                if (renewed.granted)
+                    token = renewed.token;
+            },
+            env: { ...process.env, GIGARAG_SYNC_WORKER: '1' },
+        });
+        if (outcome.timedOut || outcome.code !== 0) {
+            writeNote(state, target.slug, { kind: 'failed', detail: outcome.timedOut ? 'it ran past 40 minutes and was stopped' : `claude exited with code ${outcome.code ?? 'none'}` });
+            return;
+        }
+        const fin = await finishSync(state, target, { bucketId: stage.bucketId, token, mode: 'hook' });
+        if (!fin.advanced)
+            writeNote(state, target.slug, { kind: 'failed', detail: `the agent finished with ${fin.remaining} files still to rewrite` });
+    }
+    finally {
+        await remote.release(token);
+        state.setMeta(leaseMetaKey(target.slug, 'hook'), '');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gigarag-cursor",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "The GigaRAG plugin for Cursor. Skills and an MCP server that carry the gigarag CLI inside them.",
   "license": "UNLICENSED",
   "files": [

package/skills/gigaindex/SKILL.md

@@ -17,7 +17,7 @@ The work is split on purpose. The `gigarag` command does the mechanical half: it
 
 ## 1. Scan
 
-Run `gigarag scan <path>` with the path you were given, or the current directory. It prints a JSON manifest. Read these fields:
+Run `gigarag scan <path>` with the path you were given, or the current directory. If it exits nonzero and prints a line about an untrusted workspace instead of JSON, stop immediately: do not run `gigarag use` yourself, and do not fall back to indexing without a manifest. Report the line it printed and end there. Otherwise it prints a JSON manifest. Read these fields:
 
 - `repo.slug` is the bucket. `repo.root` is the repository root.
 - `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).
@@ -28,7 +28,7 @@ If `files` and `removed` are both empty, report "Up to date" and stop.
 
 ## 2. Find or create the bucket and threads
 
-Call `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.
+Call `list_buckets` with `q` set to the slug and use the bucket whose slug matches exactly. If `repo.bound` is true in the manifest, the bucket was chosen in `.gigarag.json`: never call `create_bucket`. If it is not in the list, stop and tell the person that the bucket named in .gigarag.json is not reachable with their access, and that `gigarag use <workspace> --bucket <slug>` links another. Otherwise, when no bucket matches, `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.
 
 Group 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.
 
@@ -42,13 +42,16 @@ Work in batches of about ten files. For each file:
 - 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`.
 - 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.
 - 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.
+- A memo whose source changed carries `stale: true`. Rewriting its content with `update_node` clears the mark. If you read the file and the memo is still right, send its body back unchanged, which clears the mark too.
 - 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.
 
 ## 4. Record progress after every batch
 
-After 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:
+After 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 with a heredoc, so the command line stays `gigarag record` and nothing else:
 
+gigarag record <<'JSON'
 {"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}]}]}
+JSON
 
 `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.
 

package/skills/gigasync/SKILL.md

@@ -19,7 +19,7 @@ The work is split on purpose. The `gigarag` command does the mechanical half: it
 
 ## 1. Scan
 
-Run `gigarag scan <path>` with the path you were given, or the current directory. It prints a JSON manifest. Read these fields:
+Run `gigarag scan <path>` with the path you were given, or the current directory. If it exits nonzero and prints a line about an untrusted workspace instead of JSON, stop immediately: do not run `gigarag use` yourself, and do not fall back to indexing without a manifest. Report the line it printed and end there. Otherwise it prints a JSON manifest. Read these fields:
 
 - `repo.slug` is the bucket. `repo.root` is the repository root.
 - `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).
@@ -30,7 +30,7 @@ If `files` and `removed` are both empty, report "Up to date" and stop.
 
 ## 2. Find or create the bucket and threads
 
-Call `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.
+Call `list_buckets` with `q` set to the slug and use the bucket whose slug matches exactly. If `repo.bound` is true in the manifest, the bucket was chosen in `.gigarag.json`: never call `create_bucket`. If it is not in the list, stop and tell the person that the bucket named in .gigarag.json is not reachable with their access, and that `gigarag use <workspace> --bucket <slug>` links another. Otherwise, when no bucket matches, `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.
 
 Group 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.
 
@@ -44,13 +44,16 @@ Work in batches of about ten files. For each file:
 - 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`.
 - 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.
 - 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.
+- A memo whose source changed carries `stale: true`. Rewriting its content with `update_node` clears the mark. If you read the file and the memo is still right, send its body back unchanged, which clears the mark too.
 - 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.
 
 ## 4. Record progress after every batch
 
-After 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:
+After 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 with a heredoc, so the command line stays `gigarag record` and nothing else:
 
+gigarag record <<'JSON'
 {"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}]}]}
+JSON
 
 `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.