gigarag-cursor 0.3.0 → 0.3.2

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gigarag",
   "description": "Your GigaRAG knowledge base inside Cursor: index a codebase, save decisions, recall them later.",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "author": { "name": "GigaRAG", "url": "https://gigarag.com" },
   "homepage": "https://gigarag.com/connect/cursor",
   "license": "UNLICENSED",

package/cli/cli.js

@@ -1,4 +1,8 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { version } from './constants.js';
+import { stateDir } from './paths.js';
+import { tryOpenState } from './state.js';
 import { err, out, UsageError } from './ui.js';
 const HELP = `gigarag ${version()}
 
@@ -41,10 +45,47 @@ const COMMANDS = {
     'auth-header': async () => (await import('./commands/authHeader.js')).authHeader,
     'index-sync': async () => (await import('./commands/indexSync.js')).indexSync,
 };
+/**
+ * Commands a person reads, never a script: the ones whose stdout `gigarag hook`, `mcp`, `index-sync`,
+ * `record` and `scan` are read by something else stays clear of. `status` also stays clear of it: it
+ * already puts the same notice on its own stdout, and printing it again on stderr would just repeat
+ * it. Each of the rest gets one line on stderr, after it runs, when a newer version is available.
+ */
+const INTERACTIVE_COMMANDS = new Set(['login', 'logout', 'connect', 'workspaces', 'use', 'trust']);
+/**
+ * Prints the one-line update notice, or nothing at all: not signed in, never checked, already
+ * current, or stderr isn't a terminal a person is reading (a pipe, a redirect, another program
+ * capturing it). `update.js` and the state it reads are loaded here, on demand, so a hook or the
+ * MCP bridge, which never call this, never pay to load them.
+ */
+export async function notifyIfOutdated() {
+    if (!process.stderr.isTTY)
+        return;
+    try {
+        if (!existsSync(join(stateDir(), 'state.db')))
+            return;
+        const state = tryOpenState();
+        if (!state)
+            return;
+        try {
+            const { terminalNotice } = await import('./update.js');
+            const notice = terminalNotice(state);
+            if (notice)
+                err(notice);
+        }
+        finally {
+            state.close();
+        }
+    }
+    catch {
+        /* a command's own result is never held up by this */
+    }
+}
 export async function main(argv) {
     const [command, ...rest] = argv;
     if (!command || command === 'help' || command === '--help' || command === '-h') {
         out(HELP);
+        await notifyIfOutdated();
         return 0;
     }
     if (command === '--version' || command === '-v' || command === 'version') {
@@ -60,7 +101,12 @@ export async function main(argv) {
         return 2;
     }
     try {
-        return await (await load())(rest);
+        const code = await (await load())(rest);
+        // Only after the command actually succeeded: a command that threw never gets this line, since
+        // whatever it failed to do is the thing that needs attention, not a version bump.
+        if (INTERACTIVE_COMMANDS.has(command))
+            await notifyIfOutdated();
+        return code;
     }
     catch (e) {
         if (e instanceof UsageError) {

package/cli/commands/indexSync.js

@@ -1,6 +1,7 @@
 import { parseArgs } from 'node:util';
 import { GigaRag } from '../sdk.js';
 import { State } from '../state.js';
+import { checkForUpdate } from '../update.js';
 const MAX_NODES = 5000;
 /** A worker that started less than this long ago owns the sync. */
 const LOCK_MS = 2 * 60_000;
@@ -23,7 +24,7 @@ async function pendingImports(rag) {
  * so it is what makes memos saved from other clients, a chat app or another
  * machine, show up in the next session. Runs detached from a hook, never in one.
  */
-export async function indexSync(argv = []) {
+export async function indexSync(argv = [], opts = {}) {
     const { values } = parseArgs({ args: argv, options: { workspace: { type: 'string' } } });
     const workspace = values.workspace;
     const state = new State();
@@ -33,6 +34,15 @@ export async function indexSync(argv = []) {
         held = state.tryAcquire('sync_lock', LOCK_MS);
         if (!held)
             return 0;
+        // Never lets an update check turn a real sync failure into something else, or the reverse:
+        // a throwing or hanging registry never keeps the memo sync below from running or from
+        // recording that it finished.
+        try {
+            await checkForUpdate(state, { fetch: opts.fetch });
+        }
+        catch {
+            /* an update check is not worth failing a sync over */
+        }
         const rag = new GigaRag(workspace ? { workspaceId: workspace } : {});
         const rows = [];
         for await (const n of rag.iterateNodes({ max: MAX_NODES })) {

package/cli/commands/status.js

@@ -8,6 +8,7 @@ import { createClient, resolveUrl } from '../mcp/session.js';
 import { McpHttpError } from '../mcp/client.js';
 import { tildify } from '../paths.js';
 import { tryOpenState } from '../state.js';
+import { terminalNotice } from '../update.js';
 import { out, table } from '../ui.js';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
@@ -74,6 +75,7 @@ export async function status(argv) {
             try {
                 const last = state.getMeta('last_sync');
                 report.index = { memos: state.nodeCount(), ...(last ? { lastSync: new Date(Number(last)).toISOString() } : {}) };
+                report.update = terminalNotice(state);
                 for (const r of state.listRepos()) {
                     report.repos.push({
                         slug: r.slug,
@@ -124,6 +126,8 @@ function print(r, missing) {
     if (r.index) {
         out(`\nMemo index: ${r.index.memos} memos${r.index.lastSync ? `, synced ${r.index.lastSync}` : ', not synced yet'}`);
     }
+    if (r.update)
+        out(`\nUpdate available: ${r.update}`);
     if (r.repos.length > 0) {
         out('\nIndexed repositories:');
         for (const line of table(r.repos.map(p => [`  ${p.slug}`, p.indexedAt ? `indexed ${p.indexedAt}` : 'never indexed', p.dirty ? `${p.dirty} changed since` : '']))) {

package/cli/hooks.js

@@ -11,6 +11,7 @@ import { findRepoRoot, repoInfo } from './scan/repo.js';
 import { tryOpenState } from './state.js';
 import { maxRewriteFiles, readNote, renderNote } from './sync/notes.js';
 import { syncSlug } from './sync/slug.js';
+import { sessionStartNotice } from './update.js';
 /** Rows the SessionStart index carries at most. */
 export const INDEX_ROWS = 40;
 /** A sync worker is started at the end of a session only if the last one is older than this. */
@@ -73,6 +74,8 @@ export function renderIndex(rows, total, dirty, repoSlug, extras = {}) {
             ? '1 imported item is waiting to be filed. /gigainbox files it.'
             : `${pending} imported items are waiting to be filed. /gigainbox files them.`);
     }
+    if (extras.update)
+        lines.push(extras.update);
     return lines.join('\n');
 }
 export async function runHook(rawEvent, raw, dir = stateDir()) {
@@ -134,6 +137,7 @@ function sessionStart(state, input, cursor) {
     const text = renderIndex(state.recentNodes(INDEX_ROWS, ws), state.nodeCount(ws), state.hasRepo(slug) ? state.dirtyCount(slug) : 0, slug, {
         note: noteLine,
         importsPending,
+        update: sessionStartNotice(state),
     });
     if (!process.env['GIGARAG_SYNC_WORKER'])
         maybeSpawnSync(state, ws);

package/cli/package.json

@@ -1,5 +1,6 @@
 {
   "name": "gigarag",
-  "version": "0.3.0",
-  "type": "module"
+  "version": "0.3.2",
+  "type": "module",
+  "gigaragHost": "cursor"
 }

package/cli/update.js

@@ -0,0 +1,197 @@
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isSea } from 'node:sea';
+import { version } from './constants.js';
+/** Where the CLI's own npm package answers with the newest published version. */
+export const REGISTRY_URL = 'https://registry.npmjs.org/gigarag/latest';
+/** Where the Claude Code plugin's npm package answers with the newest published version. */
+export const PLUGIN_REGISTRY_URL = 'https://registry.npmjs.org/gigarag-claude-code/latest';
+/** How long a checked timestamp holds off the next attempt, success or failure alike. */
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** How long the registry request is given before it counts as a failure. */
+export const CHECK_TIMEOUT_MS = 3000;
+/** How long a SessionStart line, once shown for a given version, stays quiet before it can show again. */
+export const NOTICE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const CHECKED_AT_KEY = 'update_checked_at';
+const LATEST_KEY = 'latest_version';
+const PLUGIN_LATEST_KEY = 'latest_plugin_version';
+/** What a version is allowed to look like before it is trusted: no prerelease, no build metadata, three parts, each capped so a hostile answer can't grow unbounded. */
+const PLAIN_VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}$/;
+/**
+ * True when the check is turned off for this run: an opt-out, or a CI environment nobody is
+ * watching. `CI=false`, which some runners set deliberately to mean "this is not CI", never
+ * disables it: only a truthy value that isn't the literal string "false" does.
+ */
+export function updateCheckDisabled(env = process.env) {
+    return Boolean(env['GIGARAG_NO_UPDATE_CHECK']) || Boolean(env['CI'] && env['CI'] !== 'false');
+}
+async function fetchVersion(doFetch, url, timeoutMs) {
+    try {
+        const res = await doFetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        const v = typeof body.version === 'string' ? body.version : '';
+        return PLAIN_VERSION.test(v) ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Asks npm for the newest published version of both `gigarag` and `gigarag-claude-code`, at most
+ * once a day, and remembers what it heard, each under its own key. Runs inside the detached
+ * `index-sync` worker, never in a hook, so a slow or blocked network never touches a session's
+ * budget. The checked timestamp is written before either request, so a machine that cannot reach
+ * the registry is not retried on every worker run; each version is written only on a clean,
+ * well-shaped answer for that package, independently of the other. A bad status, a body that is
+ * not a plain x.y.z, a timeout, a thrown error stores nothing beyond the attempt for that package
+ * and is otherwise silent.
+ */
+export async function checkForUpdate(state, opts = {}) {
+    if (updateCheckDisabled(opts.env ?? process.env))
+        return;
+    const now = opts.now ?? Date.now();
+    const last = Number(state.getMeta(CHECKED_AT_KEY) ?? 0);
+    // A clock that jumped backward (a stored timestamp now in the future) never holds off a check:
+    // only a `last` that is genuinely in the past and inside the interval does.
+    if (last <= now && now - last < CHECK_INTERVAL_MS)
+        return;
+    state.setMeta(CHECKED_AT_KEY, String(now));
+    const doFetch = opts.fetch ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? CHECK_TIMEOUT_MS;
+    const [cliVersion, pluginVersion] = await Promise.all([
+        fetchVersion(doFetch, opts.url ?? REGISTRY_URL, timeoutMs),
+        fetchVersion(doFetch, opts.pluginUrl ?? PLUGIN_REGISTRY_URL, timeoutMs),
+    ]);
+    if (cliVersion)
+        state.setMeta(LATEST_KEY, cliVersion);
+    if (pluginVersion)
+        state.setMeta(PLUGIN_LATEST_KEY, pluginVersion);
+}
+/** Numeric major.minor.patch compare. A prerelease or anything else that is not a plain x.y.z never prompts, on either side. */
+export function isNewerVersion(current, latest) {
+    if (!PLAIN_VERSION.test(current) || !PLAIN_VERSION.test(latest))
+        return false;
+    const a = current.split('.').map(Number);
+    const b = latest.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (b[i] > a[i])
+            return true;
+        if (b[i] < a[i])
+            return false;
+    }
+    return false;
+}
+/**
+ * The CLI version the worker last stored against `gigarag`, when it is validly shaped and strictly
+ * newer than this build. Undefined whenever the check itself is disabled, so the opt-out also
+ * silences a notice a still-running worker stored before the variable was set.
+ */
+export function pendingUpdate(state, env = process.env) {
+    if (updateCheckDisabled(env))
+        return undefined;
+    const latest = state.getMeta(LATEST_KEY);
+    if (!latest || !PLAIN_VERSION.test(latest))
+        return undefined;
+    return isNewerVersion(version(), latest) ? latest : undefined;
+}
+/** The plugin version the worker last stored against `gigarag-claude-code`, under the same rules as {@link pendingUpdate}. */
+export function pendingPluginUpdate(state, env = process.env) {
+    if (updateCheckDisabled(env))
+        return undefined;
+    const latest = state.getMeta(PLUGIN_LATEST_KEY);
+    if (!latest || !PLAIN_VERSION.test(latest))
+        return undefined;
+    return isNewerVersion(version(), latest) ? latest : undefined;
+}
+/**
+ * How this copy of the CLI reached the machine, so a notice names the right next step.
+ * `isSea()` is the standalone binary. The plugin's vendored copy is the one path
+ * `scripts/vendor-cli.mjs` always writes to, a `cli/` folder holding `bin.js` directly;
+ * anything else is the npm package, global, local, or run once through `npx`.
+ */
+export function detectInstallKind(binPath = fileURLToPath(new URL('./bin.js', import.meta.url)), sea = isSea()) {
+    if (sea)
+        return 'binary';
+    return basename(dirname(binPath)) === 'cli' ? 'plugin' : 'npm';
+}
+/** True when this run's own path runs through npm's `_npx` cache, so the npm suggestion should name `npx` rather than a global install. */
+export function isNpxInstall(binPath = fileURLToPath(new URL('./bin.js', import.meta.url))) {
+    return /[\\/]_npx[\\/]/.test(binPath);
+}
+/**
+ * Which plugin vendored this copy, read from the `gigaragHost` field `scripts/vendor-cli.mjs`
+ * writes into the vendored `package.json` next to `bin.js`. Undefined for anything without that
+ * field: an npm install, a standalone binary, or a copy without it is treated as not Claude Code.
+ */
+function pluginHost(binPath) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dirname(binPath), 'package.json'), 'utf8'));
+        return typeof pkg.gigaragHost === 'string' ? pkg.gigaragHost : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether this copy is the Claude Code plugin's own vendored copy, deciding the SessionStart
+ * wording. `gigaragHost` decides it, and only it: `scripts/vendor-cli.mjs` always writes the field,
+ * so there is no real vendored copy without one to fall back for, and a path-shape guess would only
+ * add a second, weaker way to answer the same question. Its absence, an npm install or a standalone
+ * binary, is "not Claude Code".
+ */
+function isClaudeCodeHost(binPath) {
+    return pluginHost(binPath) === 'claude-code';
+}
+/** The next action for the install kind this copy is running from. */
+export function updateCommand(kind, npx = false) {
+    switch (kind) {
+        case 'binary':
+            return ('Run: curl -fsSL https://gigarag.com/install | GIGARAG_NO_SETUP=1 sh ' +
+                '(Windows PowerShell: $env:GIGARAG_NO_SETUP=1; irm https://gigarag.com/install.ps1 | iex)');
+        case 'plugin':
+            return 'Run: claude plugin marketplace update gigarag, then claude plugin update gigarag@gigarag, and restart Claude Code';
+        default:
+            return npx ? 'Run: npx gigarag@latest' : 'Run: npm install -g gigarag@latest';
+    }
+}
+/** One line for an interactive command's stderr, or undefined when this copy is current. */
+export function terminalNotice(state, env = process.env) {
+    const latest = pendingUpdate(state, env);
+    if (!latest)
+        return undefined;
+    const binPath = fileURLToPath(new URL('./bin.js', import.meta.url));
+    return `gigarag ${version()} is out of date; ${latest} is available. ${updateCommand(detectInstallKind(binPath), isNpxInstall(binPath))}`;
+}
+/**
+ * The one line SessionStart adds for the agent, at most once every 24 hours for a given target
+ * version, so a session that starts every few minutes doesn't repeat itself. The hook only ever
+ * runs from a plugin's own vendored copy, so the next action is always the plugin's, not a guess
+ * at how this machine installed the CLI proper; a Cursor or Copilot vendored copy, or anything else
+ * that isn't the Claude Code plugin's own copy (see {@link isClaudeCodeHost}), never gets the
+ * Claude Code wording.
+ */
+export function sessionStartNotice(state, now = Date.now(), binPath = fileURLToPath(new URL('./bin.js', import.meta.url)), env = process.env) {
+    if (!isClaudeCodeHost(binPath))
+        return undefined;
+    const latest = pendingPluginUpdate(state, env);
+    if (!latest)
+        return undefined;
+    const shownKey = `update_notified:${latest}`;
+    const last = Number(state.getMeta(shownKey) ?? 0);
+    if (last <= now && now - last < NOTICE_INTERVAL_MS)
+        return undefined;
+    // A write that can't happen right now (SQLITE_BUSY, a concurrent writer) must never cost the
+    // agent the rest of the SessionStart index over one throttling timestamp; worst case, the line
+    // repeats a little sooner than every 24 hours next time.
+    try {
+        state.setMeta(shownKey, String(now));
+    }
+    catch {
+        /* the memo index this is appended to matters far more than this one timestamp */
+    }
+    return (`GigaRAG plugin ${version()} is installed and ${latest} is available. Ask the user whether to update: run ` +
+        '`claude plugin marketplace update gigarag` then `claude plugin update gigarag@gigarag`, and restart Claude Code.');
+}

package/package.json

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