gigarag-claude-code 0.1.1 → 0.2.1

package/cli/commands/status.js

@@ -1,6 +1,7 @@
 import { parseArgs } from 'node:util';
 import { readConfig } from '../config.js';
-import { credentialSource, loadCredential, mask } from '../auth/credentials.js';
+import { ACCOUNT_SLOT, credentialSource, loadAccountCredential, loadCredential, LEGACY_SLOT, mask, workspaceSlot } from '../auth/credentials.js';
+import { resolveWorkspace } from '../binding.js';
 import { launcherIsStale } from '../clients/inspect.js';
 import { detect, hereNow, loadRegistry } from '../clients/registry.js';
 import { createClient, resolveUrl } from '../mcp/session.js';
@@ -21,28 +22,38 @@ export async function status(argv) {
         return 0;
     }
     const config = readConfig();
-    const credential = loadCredential();
+    const resolved = resolveWorkspace();
+    const account = loadAccountCredential() !== undefined;
+    const credential = loadCredential(process.env, resolved?.id) ?? (resolved ? undefined : loadCredential());
     const endpoint = resolveUrl();
     const report = {
-        signedIn: credential !== undefined,
+        signedIn: credential !== undefined || account,
         endpoint,
         clients: [],
         repos: [],
+        account,
+        ...(resolved ? { workspace: { id: resolved.id, name: config.workspaceNames?.[resolved.id], source: resolved.source } } : {}),
     };
     if (credential) {
         report.credential = credential.type === 'key' ? `key ${mask(credential.key)}` : 'browser sign-in';
-        report.storedIn = credentialSource();
-        if (!values.offline) {
-            try {
-                const tools = await createClient({ credential }).rpc('tools/list');
-                report.reachable = { ok: true, detail: `accepted, ${tools.tools.length} tools` };
-            }
-            catch (e) {
-                report.reachable = {
-                    ok: false,
-                    detail: e instanceof McpHttpError ? e.message : `could not reach ${endpoint}: ${e.message}`,
-                };
-            }
+        report.storedIn = credentialSource(process.env, resolved ? workspaceSlot(resolved.id) : LEGACY_SLOT);
+    }
+    else if (account) {
+        report.credential = 'account sign-in, no workspace token yet';
+        report.storedIn = credentialSource(process.env, ACCOUNT_SLOT);
+    }
+    if ((credential || account) && !values.offline) {
+        // Resolving by workspaceId, never by passing the credential directly, so a refreshed token is
+        // written back to that workspace's own slot and never to the legacy one.
+        try {
+            const tools = await createClient({ workspaceId: resolved?.id ?? null }).rpc('tools/list');
+            report.reachable = { ok: true, detail: `accepted, ${tools.tools.length} tools` };
+        }
+        catch (e) {
+            report.reachable = {
+                ok: false,
+                detail: e instanceof McpHttpError ? e.message : `could not reach ${endpoint}: ${e.message}`,
+            };
         }
     }
     const registry = loadRegistry();
@@ -90,6 +101,13 @@ function detectedButUnwritten(registry, written, where) {
 }
 function print(r, missing) {
     out(r.signedIn ? `Signed in with ${r.credential}, stored in ${r.storedIn}.` : 'Not signed in. Run: gigarag login');
+    if (r.workspace) {
+        const how = { env: 'from GIGARAG_WORKSPACE', binding: 'from .gigarag.json', default: 'your default, since this folder has no link' }[r.workspace.source];
+        out(`Workspace here: ${r.workspace.name ?? r.workspace.id}, ${how}.`);
+    }
+    else if (r.account) {
+        out('Workspace here: none. Run: gigarag use <workspace>');
+    }
     out(`Endpoint: ${r.endpoint}`);
     if (r.reachable)
         out(`Key check: ${r.reachable.ok ? r.reachable.detail : `FAILED. ${r.reachable.detail}`}`);

package/cli/commands/sync.js

@@ -0,0 +1,223 @@
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { State } from '../state.js';
+import { out } from '../ui.js';
+import { HooksOutsideRepoError, hookStatus, installHooks, refreshHooks } from './gitHooks.js';
+import { INTERACTIVE_LOCK_MS, bucketCacheKey, clearInteractiveRun, finishSync, holderName, markInteractiveRun, pushUnpushed, runStage } from '../sync/stage.js';
+import { RepoSyncRemote, findBucketId } from '../sync/remote.js';
+import { maxRewriteFiles, readNote, renderNote } from '../sync/notes.js';
+import { syncTarget } from '../sync/target.js';
+/**
+ * Clears the interactive marker and, if a hook-mode sync deferred behind it (a `deferred` note),
+ * starts the background worker again right away, instead of leaving that commit waiting for
+ * another one to arrive. Every caller of `clearInteractiveRun` in this file goes through this
+ * instead, since any of them can be the one that frees a sync a hook queued behind it.
+ */
+async function releaseInteractive(state, target) {
+    clearInteractiveRun(state, target.slug);
+    if (target.git && readNote(state, target.slug)?.kind === 'deferred') {
+        (await import('../sync/worker.js')).spawnWorker(target.root);
+    }
+}
+const HELP = `Usage: gigarag sync begin|end|status [path]
+
+Keeps a repository's memos in step with its git history. /gigasync runs begin, then the
+indexer, then end. The git hooks run the same steps in the background after a commit.
+
+  begin [--force]   Claim this repository's sync lease, apply renames and deletions that need
+                    no model, and mark the memos of changed files stale. Exit 3 means stop and
+                    tell the person what was printed. --force syncs another branch, a checkout
+                    behind the last synced commit, or a mass deletion
+  end [--init]      Save what the indexer recorded, move the last synced commit when nothing is
+                    left, and release the lease. --init also records this branch as the one to
+                    sync and installs the git hooks (/gigaindex does this)
+  status [--json]   The bucket, branch, last synced commit, lease, hooks and last note`;
+/** Exit status that tells a slash command to stop and relay stdout. */
+const STOP = 3;
+/**
+ * The instructive refusal for a repository whose `.gigarag.json` has not been trusted. `begin` and
+ * `end` print this and stop rather than let `runStage` (which `begin` alone goes through) be the
+ * only place that catches it: `end` never calls `runStage`, so it needs its own check, for a person
+ * running it directly and for the worker-mode fast path a stray `GIGARAG_SYNC_WORKER=1 gigarag sync
+ * end` would otherwise reach.
+ */
+function untrustedSyncMessage(target) {
+    return (`${target.root}'s .gigarag.json links this repository to workspace ${target.untrustedWorkspace}, which has not been trusted, so sync did not run and will not until it is. ` +
+        'Retrying will not help. If you placed or reviewed this file yourself, run: gigarag trust. To use a different workspace instead: gigarag use <workspace>.');
+}
+export async function sync(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            force: { type: 'boolean' },
+            init: { type: 'boolean' },
+            json: { type: 'boolean' },
+            hook: { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    if (values.hook !== undefined)
+        return (await import('../sync/worker.js')).hookEntry(values.hook);
+    const [action, path] = positionals;
+    if (values.help || !action) {
+        out(HELP);
+        return 0;
+    }
+    if (action === 'worker')
+        return (await import('../sync/worker.js')).runWorker(resolve(path ?? '.'));
+    const target = syncTarget(resolve(path ?? '.'));
+    const inWorker = Boolean(process.env['GIGARAG_SYNC_WORKER']);
+    const state = new State();
+    try {
+        switch (action) {
+            case 'begin': {
+                if (inWorker) {
+                    out('The background sync holds this repository and has already applied renames, deletions and stale marks. Continue with the scan.');
+                    return 0;
+                }
+                if (target.git)
+                    refreshHooks(target.root, state);
+                // Held until `end` clears it, so the hook-mode worker steps aside for the whole of
+                // /gigasync, including the indexer run in between, not just this deterministic stage.
+                markInteractiveRun(state, target.slug);
+                let stage;
+                try {
+                    stage = await runStage(state, target, { mode: 'interactive', force: values.force });
+                }
+                catch (e) {
+                    // A crash here must not leave the marker standing for its full hour: nothing else
+                    // clears it, so every commit's hook would silently defer behind a session that no
+                    // longer exists.
+                    await releaseInteractive(state, target);
+                    throw e;
+                }
+                if (stage.kind === 'stop')
+                    await releaseInteractive(state, target);
+                out(stage.message);
+                return stage.kind === 'stop' ? STOP : 0;
+            }
+            case 'end': {
+                if (target.untrustedWorkspace) {
+                    out(untrustedSyncMessage(target));
+                    if (!inWorker)
+                        await releaseInteractive(state, target);
+                    return STOP;
+                }
+                const bucketId = state.getMeta(bucketCacheKey(target)) || (await findBucketId(target.rag(), target.slug));
+                if (!bucketId) {
+                    out(`GigaRAG has no bucket for ${target.slug}, so there is nothing to save. The indexer creates it; run /gigaindex.`);
+                    if (!inWorker)
+                        await releaseInteractive(state, target);
+                    return STOP;
+                }
+                state.setMeta(bucketCacheKey(target), bucketId);
+                const remote = new RepoSyncRemote(target.rag(), bucketId);
+                if (inWorker) {
+                    await pushUnpushed(state, target.slug, remote);
+                    out('Saved. The background sync finishes the rest.');
+                    return 0;
+                }
+                try {
+                    // The lease is 600s and the indexer can run longer than that, so `end` always
+                    // renews here rather than trusting the token `begin` cached: a live lease
+                    // renews, a lapsed one is free and re-granted to us, and only another
+                    // machine's live lease is refused. Sending the cached token straight to
+                    // advance instead would read as a lease this machine never lost.
+                    const cached = state.getMeta(`lease:${target.slug}`) || undefined;
+                    const claim = await remote.claim(holderName(state), cached);
+                    if (!claim.granted) {
+                        out(claim.message);
+                        return STOP;
+                    }
+                    const token = claim.token;
+                    const fin = await finishSync(state, target, { bucketId, token, init: values.init, mode: 'interactive' });
+                    out(fin.message);
+                    if (values.init && target.git) {
+                        try {
+                            const installed = installHooks(target.root, false, state).filter(r => r.result !== 'foreign' && r.result !== 'tracked').length;
+                            out(`Installed ${installed} git hooks, so GigaRAG syncs after each commit on this branch. gigarag hooks uninstall removes them.`);
+                        }
+                        catch (e) {
+                            if (!(e instanceof HooksOutsideRepoError))
+                                throw e;
+                            out(e.message);
+                            out('The rest of the sync is saved; only the automatic hooks are missing.');
+                        }
+                    }
+                    return 0;
+                }
+                finally {
+                    // /gigasync (begin, indexer, end) is over either way: the hook-mode worker can run again.
+                    await releaseInteractive(state, target);
+                }
+            }
+            case 'status': {
+                // An untrusted binding is never followed for sync, so status never resolves or queries a
+                // bucket for it either: doing so would report on whatever the default workspace happens to
+                // hold for this repository's unbound slug, which reads as this binding having been used.
+                const untrusted = target.untrustedWorkspace;
+                const bucketId = untrusted ? undefined : state.getMeta(bucketCacheKey(target)) || (await findBucketId(target.rag(), target.slug));
+                const s = bucketId ? await new RepoSyncRemote(target.rag(), bucketId).state() : undefined;
+                const note = untrusted ? undefined : readNote(state, target.slug);
+                // A hooks path outside both .git and the work tree (a machine-wide core.hooksPath)
+                // makes hookStatus refuse, the same way install and uninstall do. Status is a read: it
+                // reports that and moves on, rather than crashing on something install already explains.
+                let hooks = 0;
+                let hooksError;
+                if (target.git) {
+                    try {
+                        hooks = hookStatus(target.root).filter(h => h.result === 'installed').length;
+                    }
+                    catch (e) {
+                        if (!(e instanceof HooksOutsideRepoError))
+                            throw e;
+                        hooks = null;
+                        hooksError = e.message;
+                    }
+                }
+                // A live marker blocks every hook-mode sync on this machine for up to an hour, silently
+                // if the interactive session that set it crashed or was abandoned before `end`. Status
+                // says so and how to clear it, since nothing else here will.
+                const interactiveSince = Number(state.getMeta(`sync_interactive:${target.slug}`) ?? 0);
+                const interactiveUntil = interactiveSince > 0 && Date.now() - interactiveSince < INTERACTIVE_LOCK_MS ? new Date(interactiveSince + INTERACTIVE_LOCK_MS).toISOString() : null;
+                const report = {
+                    bucket: target.slug,
+                    untrusted_workspace: untrusted ?? null,
+                    initialised: s?.initialised ?? false,
+                    branch: s?.branch ?? null,
+                    last_commit: s?.last_commit ?? null,
+                    lease: s?.lease ?? null,
+                    hooks_installed: hooks,
+                    hooks_error: hooksError ?? null,
+                    interactive_until: interactiveUntil,
+                    note: note && note.kind ? renderNote(note, target.slug, maxRewriteFiles()) : null,
+                };
+                if (values.json)
+                    out(JSON.stringify(report, null, 2));
+                else {
+                    if (untrusted)
+                        out(`${target.root}'s .gigarag.json links this repository to workspace ${untrusted}, which has not been trusted, so it is not used for sync. Run gigarag trust to use it, or gigarag use <workspace> to pick another.`);
+                    out(`${report.bucket}: ${report.initialised ? `syncs ${report.branch}, last synced ${report.last_commit?.slice(0, 7) ?? 'never'}` : 'not set up for automatic sync (run /gigaindex)'}`);
+                    if (hooksError)
+                        out(`hooks: unavailable (${hooksError})`);
+                    else
+                        out(`Git hooks installed: ${hooks} of 4`);
+                    if (report.lease)
+                        out(`Lease held by ${report.lease.holder} until ${report.lease.expires_at}`);
+                    if (interactiveUntil)
+                        out(`An interactive /gigasync marker is live on this machine until ${interactiveUntil}, so the background sync steps aside until then. If that session already ended, gigarag sync end clears it.`);
+                    if (report.note)
+                        out(report.note);
+                }
+                return 0;
+            }
+            default:
+                out(HELP);
+                return 2;
+        }
+    }
+    finally {
+        state.close();
+    }
+}

package/cli/commands/trust.js

@@ -0,0 +1,31 @@
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { readBinding, trustBinding } from '../binding.js';
+import { out, UsageError } from '../ui.js';
+const HELP = `Usage: gigarag trust [path]
+
+Trusts this repository's .gigarag.json, the way running gigarag use here would,
+without rewriting the file. Run it once after a checkout inherits a binding
+someone else committed and you have looked at which workspace it names.
+
+Until a binding is trusted, GigaRAG ignores it and falls back to your machine's
+default workspace, and says so.`;
+export async function trust(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { help: { type: 'boolean', short: 'h' } },
+    });
+    if (values.help) {
+        out(HELP);
+        return 0;
+    }
+    const cwd = resolve(positionals[0] ?? '.');
+    const found = readBinding(cwd);
+    if (!found) {
+        throw new UsageError(`No .gigarag.json binding was found above ${cwd}. To create one: gigarag use <workspace>`);
+    }
+    trustBinding(found.root, found.binding.workspace);
+    out(`Trusted. ${found.root} now uses ${found.binding.workspaceName ?? found.binding.workspace}${found.binding.bucket ? `, bucket ${found.binding.bucket}` : ''}.`);
+    return 0;
+}

package/cli/commands/use.js

@@ -0,0 +1,81 @@
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { exchangeForWorkspace, listAccountWorkspaces } from '../auth/account.js';
+import { trustBinding, writeBinding } from '../binding.js';
+import { updateConfig } from '../config.js';
+import { resolveUrl } from '../mcp/session.js';
+import { findRepoRoot } from '../scan/repo.js';
+import { GigaRag } from '../sdk.js';
+import { out, UsageError } from '../ui.js';
+const HELP = `Usage: gigarag use <workspace> [--bucket <slug>] [--default] [path]
+
+Links this repository to a GigaRAG workspace by writing .gigarag.json at its
+root. The file holds no secret, so it can be committed. <workspace> is a name or
+an id from: gigarag workspaces
+
+  --bucket <slug>  The bucket this repository is indexed into. Required where you
+                   are a guest, because a guest cannot create buckets.
+  --default        Make it the workspace for every folder with no link, instead
+                   of linking this repository`;
+export function pickWorkspace(list, wanted) {
+    const byId = list.find(w => w.id === wanted.toLowerCase());
+    if (byId)
+        return byId;
+    const byName = list.filter(w => w.name.toLowerCase() === wanted.toLowerCase());
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        throw new UsageError(`More than one workspace is called ${wanted}. Use its id instead:\n${byName.map(w => `  ${w.id}  ${w.name}, owned by ${w.owner_name ?? 'you'}`).join('\n')}`);
+    }
+    throw new UsageError(`Your account cannot reach a workspace called ${wanted}. To see the ones it can: gigarag workspaces`);
+}
+/** Slugs of the buckets a guest may write to, read with the workspace's own token. */
+export async function writableSlugs(rag, grants) {
+    const writable = new Set(grants.filter(g => g.permission === 'write').map(g => g.bucket_id));
+    const page = await rag.listBuckets({ limit: 200 });
+    return (page.items ?? [])
+        .filter(b => writable.has(String(b['id'])))
+        .map(b => String(b['slug']));
+}
+export async function use(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { bucket: { type: 'string' }, default: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+    });
+    if (values.help || positionals.length === 0) {
+        out(HELP);
+        return values.help ? 0 : 2;
+    }
+    const target = pickWorkspace(await listAccountWorkspaces(), positionals[0]);
+    // Exchanged now, so a refusal reaches the person here, in a terminal, rather
+    // than later inside an editor that shows it as a failed tool call.
+    await exchangeForWorkspace(target.id, { mcpUrl: resolveUrl() });
+    if (target.access_via === 'bucket') {
+        const slugs = await writableSlugs(new GigaRag({ workspaceId: target.id }), target.buckets ?? []);
+        if (!values.bucket || !slugs.includes(values.bucket)) {
+            throw new UsageError(slugs.length === 0
+                ? `You are a guest in ${target.name} and cannot write to any of its buckets, so this repository cannot be indexed there. Ask ${target.owner_name ?? 'the owner'} for write access to a bucket at gigarag.com/teams.`
+                : `You are a guest in ${target.name}, and guests cannot create buckets. Name one you can write to with --bucket: ${slugs.join(', ')}`);
+        }
+    }
+    if (values.default) {
+        updateConfig(c => void (c.workspaceId = target.id));
+        out(`Folders with no link now use ${target.name}.`);
+        return 0;
+    }
+    const { root } = findRepoRoot(resolve(positionals[1] ?? '.'));
+    const path = writeBinding(root, {
+        workspace: target.id,
+        workspaceName: target.name,
+        ...(values.bucket ? { bucket: values.bucket } : {}),
+    });
+    // Running `use` is the trust: the person named this workspace themselves, so
+    // the binding it just wrote is followed from here on without another prompt.
+    // A teammate whose checkout inherits the committed file has not done that,
+    // and needs `gigarag trust` once they have looked at it.
+    trustBinding(root, target.id);
+    out(`Linked ${root} to ${target.name}${values.bucket ? `, bucket ${values.bucket}` : ''}. Wrote ${path}.`);
+    out('It holds no secret, so you can commit it and teammates reach the same workspace, after they run: gigarag trust');
+    return 0;
+}

package/cli/commands/workspaces.js

@@ -0,0 +1,40 @@
+import { parseArgs } from 'node:util';
+import { listAccountWorkspaces } from '../auth/account.js';
+import { resolveWorkspace } from '../binding.js';
+import { out, table } from '../ui.js';
+const HELP = `Usage: gigarag workspaces [--json]
+
+Lists every workspace your account can reach: your own, ones shared with you,
+ones reached through someone's account, and ones where you are a guest in some
+buckets. The one this folder uses is marked with *.
+
+To link this repository to one: gigarag use <workspace>`;
+const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+export function describeAccess(w) {
+    const owner = w.owner_name ?? 'someone';
+    if (w.access_via === 'owner')
+        return 'Owner';
+    if (w.access_via === 'account')
+        return `${cap(w.role)} in all of ${owner}'s workspaces`;
+    if (w.access_via === 'bucket') {
+        const n = w.buckets?.length ?? 0;
+        return `Guest, ${n} ${n === 1 ? 'bucket' : 'buckets'} from ${owner}`;
+    }
+    return `${cap(w.role)}, shared by ${owner}`;
+}
+export async function workspaces(argv) {
+    const { values } = parseArgs({ args: argv, options: { json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
+    if (values.help) {
+        out(HELP);
+        return 0;
+    }
+    const list = await listAccountWorkspaces();
+    const current = resolveWorkspace()?.id;
+    if (values.json) {
+        out(JSON.stringify(list.map(w => ({ ...w, current: w.id === current })), null, 2));
+        return 0;
+    }
+    for (const line of table(list.map(w => [w.id === current ? '*' : ' ', w.name, describeAccess(w), w.id])))
+        out(line);
+    return 0;
+}

package/cli/git/git.js

@@ -0,0 +1,187 @@
+import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { HOOKS } from './hookScript.js';
+/**
+ * The process runner behind every `git()` call, swappable only by tests so they can stub what a
+ * git binary (an old version's quirks included) would have answered, without needing that version
+ * installed or fighting a real OS's PATH resolution to shadow it.
+ */
+let runGitProcess = spawnSync;
+/** @internal test seam only. `undefined` restores the real git binary. */
+export function __setGitProcessRunnerForTests(fn) {
+    runGitProcess = fn ?? spawnSync;
+}
+/**
+ * Every question the sync asks git, in one place. Runs the git binary, which a
+ * repository with hooks already has, and never prompts: GIT_TERMINAL_PROMPT=0,
+ * no stdin, and a timeout, because these run from a detached worker nobody is
+ * watching.
+ */
+export function git(root, args) {
+    const r = runGitProcess('git', args, {
+        cwd: root,
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 15_000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    return { ok: !r.error && r.status === 0, status: r.error ? null : r.status, out: (r.stdout ?? '').trim() };
+}
+export function isGitRepo(root) {
+    return git(root, ['rev-parse', '--is-inside-work-tree']).out === 'true';
+}
+export function headCommit(root) {
+    const r = git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']);
+    return r.ok && /^[0-9a-f]{40,64}$/.test(r.out) ? r.out : undefined;
+}
+/** The checked out branch, or undefined on a detached HEAD, which is what every step of a rebase is. */
+export function currentBranch(root) {
+    const r = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+    return r.ok && r.out ? r.out : undefined;
+}
+/**
+ * Whether `ancestor` is an ancestor of `descendant` (HEAD by default). True or false when git can
+ * tell, undefined when either commit is unknown here (not fetched, or garbage collected).
+ */
+export function isAncestor(root, ancestor, descendant = 'HEAD') {
+    const r = git(root, ['merge-base', '--is-ancestor', ancestor, descendant]);
+    if (r.status === 0)
+        return true;
+    if (r.status === 1)
+        return false;
+    return undefined;
+}
+/**
+ * Our own hook files, as pathspecs relative to `root`, when installing put them inside the work
+ * tree (`.husky`, or a repo-relative `core.hooksPath`). `.git/hooks` itself is never in the work
+ * tree, so this is empty for a plain repository.
+ */
+function ownHookPathspecs(root) {
+    const loc = hooksDir(root);
+    if (!loc || !loc.insideWorkTree)
+        return [];
+    return HOOKS.map(h => `:(exclude)${relative(root, resolve(loc.dir, h)).split(sep).join('/')}`);
+}
+/**
+ * No staged, unstaged or untracked changes. A background rewrite reads files from disk, so it
+ * needs this. Our own hook files are excluded: when they live inside the work tree, installing or
+ * updating them would otherwise make every repository look permanently dirty and the rewrite would
+ * never run.
+ */
+export function isClean(root) {
+    const excludes = ownHookPathspecs(root);
+    const r = git(root, ['status', '--porcelain', '--', '.', ...excludes]);
+    return r.ok && r.out === '';
+}
+/** Every file in HEAD's tree. A path gone from disk but still here is an uncommitted deletion. */
+export function pathsAtHead(root) {
+    const r = spawnSync('git', ['ls-tree', '-r', '--name-only', '-z', 'HEAD'], {
+        cwd: root,
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 15_000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (r.error || r.status !== 0)
+        return new Set();
+    return new Set((r.stdout ?? '').split('\0').filter(Boolean));
+}
+/**
+ * Turns a `rev-parse` answer into an absolute path, or undefined when it doesn't look like one.
+ * `--path-format=absolute` is never sent: a git older than 2.31 doesn't know that flag, and rather
+ * than failing, `rev-parse` echoes it back as an extra output line and answers the rest of the
+ * command as if it had never been given, in its only format, which is relative to the cwd the
+ * command ran with. Resolving against `root` (always that cwd) is therefore correct on every git
+ * version, once the flag itself is gone. What's left guards against exactly that echo, or any
+ * other output that isn't a single path: something starting with `--` (an option, echoed or
+ * otherwise) or carrying more than one line.
+ */
+function resolveGitPath(root, out) {
+    if (!out || out.startsWith('--') || out.includes('\n'))
+        return undefined;
+    return resolve(root, out);
+}
+/**
+ * The repository's own git directory (the common one, so a worktree answers with the main
+ * checkout's) and work tree top level, both absolute. Undefined where git can't say, such as a
+ * bare repository for the work tree.
+ */
+function repoPaths(root) {
+    const gd = git(root, ['rev-parse', '--git-common-dir']);
+    const wt = git(root, ['rev-parse', '--show-toplevel']);
+    return {
+        gitDir: gd.ok ? resolveGitPath(root, gd.out) : undefined,
+        workTree: wt.ok && wt.out ? resolve(wt.out) : undefined,
+    };
+}
+/**
+ * The path git itself would see: symlinks and junctions followed, and (on Windows) a `subst`
+ * drive resolved to the real one. Falls back to the input when nothing exists there yet, such as
+ * a `core.hooksPath` directory install hasn't created. Comparing this, not the raw string, is what
+ * keeps `insideGitDir` and `insideWorkTree` from reading as false on a path that only differs from
+ * git's own answer by an alias.
+ */
+function canonical(path) {
+    // A hooks folder that does not exist yet cannot be resolved itself, so resolve its nearest
+    // existing parent and put the rest back. Returning the raw path instead leaves a Windows short
+    // name (RUNNER~1) or a symlinked parent unexpanded, and the folder then reads as outside the repo.
+    let head = resolve(path);
+    const rest = [];
+    for (;;) {
+        try {
+            return join(realpathSync.native(head), ...rest);
+        }
+        catch {
+            const parent = dirname(head);
+            if (parent === head)
+                return path;
+            rest.unshift(basename(head));
+            head = parent;
+        }
+    }
+}
+/** Case-insensitive on Windows, where two paths that differ only in a drive letter's case, or in
+ * a directory's case, name the same file. */
+function comparable(path) {
+    const c = canonical(path);
+    return process.platform === 'win32' ? c.toLowerCase() : c;
+}
+function isWithin(dir, parent) {
+    if (!parent)
+        return false;
+    const d = comparable(dir);
+    const p = comparable(parent);
+    return d === p || d.startsWith(p + sep);
+}
+/**
+ * Where hooks go. `--git-path hooks` answers for worktrees and core.hooksPath.
+ * Husky 9 points core.hooksPath at `.husky/_` and regenerates that folder on
+ * every install, so our lines go into `.husky/<hook>`, which husky's own
+ * stubs call. Neither inside the git dir nor the work tree means a hooks
+ * path pointed somewhere else entirely, such as a global core.hooksPath
+ * shared by every repository on the machine: callers refuse to install there.
+ */
+export function hooksDir(root) {
+    const r = git(root, ['rev-parse', '--git-path', 'hooks']);
+    if (!r.ok)
+        return undefined;
+    const rawDir = resolveGitPath(root, r.out);
+    if (!rawDir)
+        return undefined;
+    const husky = basename(rawDir) === '_' && basename(dirname(rawDir)) === '.husky';
+    const dir = husky ? dirname(rawDir) : rawDir;
+    const { gitDir, workTree } = repoPaths(root);
+    const insideGitDir = isWithin(dir, gitDir);
+    const insideWorkTree = !insideGitDir && isWithin(dir, workTree);
+    return { dir, husky, insideGitDir, insideWorkTree };
+}
+/**
+ * `<git-common-dir>/info/exclude`, the per-repository ignore list nothing commits, for hook files
+ * that live inside the work tree. Undefined where the common git dir can't be found.
+ */
+export function gitInfoExcludeFile(root) {
+    const { gitDir } = repoPaths(root);
+    return gitDir ? join(gitDir, 'info', 'exclude') : undefined;
+}