gitnexushub 0.3.0 → 0.4.0

package/dist/index.js

@@ -12,23 +12,12 @@ import { Command } from 'commander';
 import pc from 'picocolors';
 const require = createRequire(import.meta.url);
 const PKG_VERSION = require('../package.json').version;
-import { loadConfig, saveConfig, clearConfig } from './config.js';
-import { HubAPI } from './api.js';
-import { isGitRepo, getGitRemoteUrl, parseGitRemote, matchRepo } from './project.js';
-import { writeProjectContext, removeProjectContext } from './context.js';
-import { generateConnectContext } from './content.js';
-import { detectInstalledEditors } from './editors/detect.js';
-import { cursorEditor } from './editors/cursor.js';
-import { windsurfEditor } from './editors/windsurf.js';
-import { opencodeEditor } from './editors/opencode.js';
-import { claudeCodeEditor } from './editors/claude-code.js';
-const DEFAULT_HUB_URL = process.env.GITNEXUS_HUB_URL || 'https://gitnexus-enterprise-production.up.railway.app';
-const EDITORS = {
-    'claude-code': claudeCodeEditor,
-    cursor: cursorEditor,
-    windsurf: windsurfEditor,
-    opencode: opencodeEditor,
-};
+import { clearConfig } from './config.js';
+import { isGitRepo } from './project.js';
+import { removeProjectContext } from './context.js';
+import { runSync } from './sync-command.js';
+import { ok, info, warn, fail, resolveAuth, DEFAULT_HUB_URL, EDITORS } from './cli-helpers.js';
+import { runConnect } from './connect-command.js';
 const BANNER = [
     ' ██████╗ ██╗████████╗███╗   ██╗███████╗██╗  ██╗██╗   ██╗███████╗',
     '██╔════╝ ██║╚══██╔══╝████╗  ██║██╔════╝╚██╗██╔╝██║   ██║██╔════╝',
@@ -37,10 +26,6 @@ const BANNER = [
     '╚██████╔╝██║   ██║   ██║ ╚████║███████╗██╔╝ ██╗╚██████╔╝███████║',
     ' ╚═════╝ ╚═╝   ╚═╝   ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝',
 ];
-const ok = (msg) => console.log(`  ${pc.green('✔')} ${msg}`);
-const info = (msg) => console.log(`  ${pc.cyan('ℹ')} ${msg}`);
-const warn = (msg) => console.log(`  ${pc.yellow('⚠')} ${msg}`);
-const fail = (msg) => console.error(`  ${pc.red('✗')} ${msg}`);
 function printBanner() {
     console.log('');
     for (const line of BANNER) {
@@ -50,44 +35,9 @@ function printBanner() {
     console.log(`   ${pc.dim('Plug into the living brain of your codebase')}`);
     console.log('');
 }
-/**
- * Resolve token + Hub URL from args/config. Exits on failure.
- */
-async function resolveAuth(tokenArg, hubOpt) {
-    const config = await loadConfig();
-    const token = tokenArg || config.hubToken;
-    const hubUrl = hubOpt || config.hubUrl || DEFAULT_HUB_URL;
-    if (!token) {
-        fail('No API token provided.');
-        console.error('');
-        console.error(`    Usage: ${pc.cyan('npx gitnexushub gnx_YOUR_TOKEN --editor cursor')}`);
-        console.error(`    Generate a token at: ${pc.cyan(hubUrl + '/settings/tokens')}`);
-        console.error('');
-        process.exit(1);
-    }
-    if (!token.startsWith('gnx_')) {
-        fail(`Invalid token format. Tokens must start with ${pc.bold('gnx_')}`);
-        console.error('');
-        process.exit(1);
-    }
-    const api = new HubAPI(hubUrl, token);
-    const user = await api.getMe().catch((err) => {
-        fail(`Authentication failed: ${err.message}`);
-        console.error(`    Check your token and try again.`);
-        console.error('');
-        process.exit(1);
-    });
-    ok(`Hello, ${pc.bold(user.name)}!`);
-    console.log('');
-    await saveConfig({ hubToken: token, hubUrl });
-    return { api, hubUrl, token };
-}
 // ─── CLI Setup ────────────────────────────────────────────────────
 const program = new Command();
-program
-    .name('gnx')
-    .description('Connect your editor to GitNexus Hub')
-    .version(PKG_VERSION);
+program.name('gnx').description('Connect your editor to GitNexus Hub').version(PKG_VERSION);
 // ─── connect command (also the default) ──────────────────────────
 const connectAction = async (tokenArg, opts) => {
     try {
@@ -145,120 +95,22 @@ program
         process.exit(1);
     }
 });
-program.parse();
-// ─── Connect Flow ─────────────────────────────────────────────────
-async function runConnect(tokenArg, opts) {
-    const { api, hubUrl, token } = await resolveAuth(tokenArg, opts.hub);
-    // ── Resolve editor ─────────────────────────────────────────────
-    const config = await loadConfig();
-    let editorId;
-    if (opts.editor) {
-        if (!(opts.editor in EDITORS)) {
-            fail(`Unknown editor: ${pc.bold(opts.editor)}`);
-            console.error(`    Supported: ${pc.cyan(Object.keys(EDITORS).join(', '))}`);
-            console.error('');
-            return process.exit(1);
-        }
-        editorId = opts.editor;
-    }
-    else if (!config.hubToken) {
-        const detected = await detectInstalledEditors();
-        if (detected.length === 1) {
-            editorId = detected[0];
-            info(`Auto-detected editor: ${pc.bold(EDITORS[editorId].name)}`);
-        }
-        else if (detected.length > 1) {
-            warn('Multiple editors detected. Please specify one:');
-            for (const id of detected) {
-                console.error(`      ${pc.cyan('--editor ' + id)}`);
-            }
-            console.error('');
-            return process.exit(1);
-        }
-        else {
-            fail('No editor detected. Please specify one:');
-            console.error(`      ${pc.cyan('--editor claude-code | cursor | windsurf | opencode')}`);
-            console.error('');
-            return process.exit(1);
-        }
-    }
-    // ── Configure editor MCP ────────────────────────────────────────
-    let skills = [];
-    if (editorId) {
-        const editor = EDITORS[editorId];
-        info(`Configuring ${pc.bold(editor.name)}...`);
-        const result = await editor.configure(hubUrl, token);
-        if (result.success) {
-            ok(result.message);
-            if (result.overrodeCli) {
-                console.log('');
-                console.log(`  ${pc.cyan('⬆')} ${pc.bold('GitNexus open-source detected — upgraded to Hub')}`);
-                console.log(`     ${pc.dim('Remote indexing. Deeper analysis. PR blast radius. Auto-reindex on push.')}`);
-                console.log(`     ${pc.dim('Your tools (query, context, impact) are unchanged — just faster and smarter.')}`);
-            }
-        }
-        else {
-            fail(result.message);
-        }
-        try {
-            const bundled = await generateConnectContext('_', {});
-            skills = bundled.skills;
-        }
-        catch {
-            // Skills load failed — continue without
-        }
-        if (editor.installSkills && skills.length > 0) {
-            const count = await editor.installSkills(skills);
-            if (count > 0) {
-                ok(`${count} skills installed`);
-            }
-        }
-    }
-    // ── Write project context ───────────────────────────────────────
-    if (!opts.skipProject && isGitRepo()) {
-        const remoteUrl = getGitRemoteUrl();
-        const remoteFullName = remoteUrl ? parseGitRemote(remoteUrl) : null;
-        if (remoteFullName) {
-            console.log('');
-            info(`Project: ${pc.bold(remoteFullName)}`);
-            try {
-                const repos = await api.listRepos();
-                const matched = matchRepo(remoteFullName, repos);
-                if (matched) {
-                    if (matched.status === 'ready') {
-                        const ctx = await generateConnectContext(matched.fullName, matched.stats || {});
-                        const result = await writeProjectContext(process.cwd(), ctx);
-                        for (const file of result.files) {
-                            ok(file);
-                        }
-                    }
-                    else {
-                        warn(`Repo status: ${pc.yellow(matched.status)} ${pc.dim('(waiting for indexing)')}`);
-                    }
-                }
-                else {
-                    warn('Repo not indexed on Hub yet');
-                    console.log(`      Add it at: ${pc.cyan(hubUrl)}`);
-                }
-            }
-            catch (err) {
-                fail(`Failed to fetch project context: ${err.message}`);
-            }
-        }
-        else {
-            console.log('');
-            warn('No GitHub remote found — skipping project context');
-        }
+// ─── sync command ─────────────────────────────────────────────────
+program
+    .command('sync')
+    .description('Push local working-tree state to the hub for re-indexing')
+    .option('--wait', 'Wait for indexing to complete', false)
+    .option('--hub <url>', 'Hub URL', DEFAULT_HUB_URL)
+    .action(async (opts) => {
+    try {
+        await runSync(opts);
     }
-    else if (!opts.skipProject) {
-        console.log('');
-        info('Not inside a git repo — skipping project context');
+    catch (err) {
+        console.error('  ' + pc.red('✗') + ' ' + (err.message || String(err)));
+        process.exit(1);
     }
-    // ── Summary ────────────────────────────────────────────────────
-    console.log('');
-    console.log(`  ${pc.green('✔')} ${pc.bold('Done!')} Open your editor — GitNexus MCP is ready.`);
-    console.log('');
-}
+});
+program.parse();
 // ─── Disconnect Flow ──────────────────────────────────────────────
 async function runDisconnect(opts) {
     // ── Resolve which editors to clean ─────────────────────────────
@@ -332,7 +184,7 @@ async function runIndex(repo, opts) {
         // Already added — look it up instead of failing
         if (msg.includes('already added')) {
             const repos = await api.listRepos();
-            const existing = repos.find(r => r.fullName === fullName);
+            const existing = repos.find((r) => r.fullName === fullName);
             if (existing) {
                 if (existing.status === 'ready') {
                     ok(`${pc.bold(fullName)} is already indexed and ready.`);
@@ -367,7 +219,7 @@ async function runIndex(repo, opts) {
     const spinFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
     let frame = 0;
     while (true) {
-        await new Promise(r => setTimeout(r, 2000));
+        await new Promise((r) => setTimeout(r, 2000));
         try {
             const detail = await api.getRepo(repoId);
             const spinner = pc.cyan(spinFrames[frame % spinFrames.length]);

package/dist/registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Local repo registry — stored at ~/.gitnexus/connect-registry.json.
+ *
+ * Maps local filesystem paths to hub repo identities so that `gnx sync`
+ * and the editor hook script can resolve cwd → hub_repo_id without
+ * talking to the hub. The registry is written by `gnx sync` when a repo
+ * is first registered and read on every subsequent sync and every hook
+ * invocation.
+ *
+ * Matcher semantics (ported from gitnexus/src/core/augmentation/engine.ts
+ * but intentionally kept separate — the OSS registry has a different
+ * shape keyed by storagePath/lbugPath):
+ *   - longest-path match wins (inner repo beats outer)
+ *   - symlinks in cwd are resolved via fs.realpath before matching
+ *   - match must land on a path-separator boundary so /projects/foo does
+ *     not match /projects/foobar
+ *   - falls back to path.resolve on realpath errors so non-existent
+ *     paths still return a best-effort syntactic match
+ */
+export interface RegistryEntry {
+    localPath: string;
+    fullName: string;
+    hubRepoId: string;
+    lastSyncedSha?: string;
+    lastSyncedAt?: string;
+}
+export declare function readRegistry(): Promise<RegistryEntry[]>;
+export declare function writeRegistry(entries: RegistryEntry[]): Promise<void>;
+export declare function upsertRegistryEntry(entry: RegistryEntry): Promise<void>;
+/**
+ * Resolve a working directory to its best-matching registry entry.
+ *
+ * Uses longest-path matching with symlink resolution and path-boundary
+ * checks so /projects/foo does not match /projects/foobar. When `opts.entries`
+ * is passed, resolution is done against that in-memory list (used by tests
+ * and by callers that already hold the entries); otherwise the registry is
+ * read from disk.
+ */
+export declare function resolveCwdToRepo(cwd: string, opts?: {
+    entries?: RegistryEntry[];
+}): Promise<RegistryEntry | null>;

package/dist/registry.js

@@ -0,0 +1,92 @@
+/**
+ * Local repo registry — stored at ~/.gitnexus/connect-registry.json.
+ *
+ * Maps local filesystem paths to hub repo identities so that `gnx sync`
+ * and the editor hook script can resolve cwd → hub_repo_id without
+ * talking to the hub. The registry is written by `gnx sync` when a repo
+ * is first registered and read on every subsequent sync and every hook
+ * invocation.
+ *
+ * Matcher semantics (ported from gitnexus/src/core/augmentation/engine.ts
+ * but intentionally kept separate — the OSS registry has a different
+ * shape keyed by storagePath/lbugPath):
+ *   - longest-path match wins (inner repo beats outer)
+ *   - symlinks in cwd are resolved via fs.realpath before matching
+ *   - match must land on a path-separator boundary so /projects/foo does
+ *     not match /projects/foobar
+ *   - falls back to path.resolve on realpath errors so non-existent
+ *     paths still return a best-effort syntactic match
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+function getRegistryPath() {
+    return path.join(os.homedir(), '.gitnexus', 'connect-registry.json');
+}
+export async function readRegistry() {
+    try {
+        const raw = await fs.readFile(getRegistryPath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.entries) ? parsed.entries : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function writeRegistry(entries) {
+    const p = getRegistryPath();
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, JSON.stringify({ entries }, null, 2));
+}
+export async function upsertRegistryEntry(entry) {
+    const entries = await readRegistry();
+    const idx = entries.findIndex((e) => e.hubRepoId === entry.hubRepoId);
+    if (idx >= 0)
+        entries[idx] = { ...entries[idx], ...entry };
+    else
+        entries.push(entry);
+    await writeRegistry(entries);
+}
+/**
+ * Resolve a working directory to its best-matching registry entry.
+ *
+ * Uses longest-path matching with symlink resolution and path-boundary
+ * checks so /projects/foo does not match /projects/foobar. When `opts.entries`
+ * is passed, resolution is done against that in-memory list (used by tests
+ * and by callers that already hold the entries); otherwise the registry is
+ * read from disk.
+ */
+export async function resolveCwdToRepo(cwd, opts) {
+    const entries = opts?.entries ?? (await readRegistry());
+    if (entries.length === 0)
+        return null;
+    let resolved;
+    try {
+        resolved = await fs.realpath(path.resolve(cwd));
+    }
+    catch {
+        resolved = path.resolve(cwd);
+    }
+    // Normalize casing on Windows so D:\foo and d:\foo match.
+    const isWindows = process.platform === 'win32';
+    const normalizedCwd = isWindows ? resolved.toLowerCase() : resolved;
+    const sep = path.sep;
+    let best = null;
+    let bestLen = 0;
+    for (const entry of entries) {
+        let entryPath;
+        try {
+            entryPath = await fs.realpath(path.resolve(entry.localPath));
+        }
+        catch {
+            entryPath = path.resolve(entry.localPath);
+        }
+        const normalizedEntry = isWindows ? entryPath.toLowerCase() : entryPath;
+        const matched = normalizedCwd === normalizedEntry || normalizedCwd.startsWith(normalizedEntry + sep);
+        if (matched && normalizedEntry.length > bestLen) {
+            best = entry;
+            bestLen = normalizedEntry.length;
+        }
+    }
+    return best;
+}

package/dist/sync-command.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `gnx sync` — push local working-tree state to the hub for re-indexing.
+ *
+ * Flow:
+ *   1. Resolve cwd → registered repo (from connect-registry.json)
+ *   2. If not registered, look up via hub API by GitHub remote, save to registry
+ *   3. If still not found, tell user to add via hub UI
+ *   4. Compute local HEAD and dirty state
+ *   5. Short-circuit if hub already has this commit AND tree is clean
+ *   6. Build tarball, upload, optionally poll for completion
+ */
+export interface SyncOptions {
+    wait?: boolean;
+    hub?: string;
+}
+export declare function runSync(opts: SyncOptions): Promise<void>;

package/dist/sync-command.js

@@ -0,0 +1,169 @@
+/**
+ * `gnx sync` — push local working-tree state to the hub for re-indexing.
+ *
+ * Flow:
+ *   1. Resolve cwd → registered repo (from connect-registry.json)
+ *   2. If not registered, look up via hub API by GitHub remote, save to registry
+ *   3. If still not found, tell user to add via hub UI
+ *   4. Compute local HEAD and dirty state
+ *   5. Short-circuit if hub already has this commit AND tree is clean
+ *   6. Build tarball, upload, optionally poll for completion
+ */
+import { execFileSync } from 'child_process';
+import pc from 'picocolors';
+import { loadConfig } from './config.js';
+import { HubAPI } from './api.js';
+import { resolveCwdToRepo, upsertRegistryEntry } from './registry.js';
+import { buildTarballStream } from './tarball.js';
+import { isGitRepo, getGitRemoteUrl, parseGitRemote } from './project.js';
+function getLocalHead(cwd) {
+    return execFileSync('git', ['rev-parse', 'HEAD'], { cwd }).toString('utf-8').trim();
+}
+function isDirty(cwd) {
+    const out = execFileSync('git', ['status', '--porcelain'], { cwd }).toString('utf-8').trim();
+    return out.length > 0;
+}
+function getCurrentBranch(cwd) {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd })
+        .toString('utf-8')
+        .trim();
+}
+/**
+ * Terse output helpers — NO internal-implementation leakage in user-visible strings.
+ */
+const ok = (msg) => console.log('  ' + pc.green('✓') + ' ' + msg);
+const fail = (msg) => console.error('  ' + pc.red('✗') + ' ' + msg);
+const info = (msg) => console.error('  ' + pc.yellow('⏱') + ' ' + msg);
+export async function runSync(opts) {
+    const cwd = process.cwd();
+    if (!isGitRepo()) {
+        fail('Not inside a git repository');
+        process.exit(1);
+    }
+    const config = await loadConfig();
+    const token = config.hubToken;
+    const hubUrl = opts.hub || config.hubUrl;
+    if (!token || !hubUrl) {
+        fail('Not connected. Run `gnx connect <token>` first.');
+        process.exit(1);
+    }
+    const api = new HubAPI(hubUrl, token);
+    // Step 1: Resolve cwd → registered repo
+    let entry = await resolveCwdToRepo(cwd);
+    // Step 2: If not registered locally, try to match by GitHub remote
+    if (!entry) {
+        const remoteUrl = getGitRemoteUrl();
+        const fullName = remoteUrl ? parseGitRemote(remoteUrl) : null;
+        if (!fullName) {
+            fail('Could not determine the GitHub remote for this directory');
+            process.exit(1);
+        }
+        const hubRepos = await api
+            .listRepos()
+            .catch(() => []);
+        const matched = hubRepos.find((r) => r.fullName === fullName);
+        if (!matched) {
+            fail(`${pc.bold(fullName)} is not indexed on the hub.`);
+            console.error('  Add it at: ' + pc.cyan(hubUrl));
+            process.exit(1);
+            return;
+        }
+        entry = {
+            localPath: cwd,
+            fullName: matched.fullName,
+            hubRepoId: matched.id,
+        };
+        await upsertRegistryEntry(entry);
+    }
+    // entry is guaranteed non-null at this point (process.exit above on the failure path)
+    const repo = entry;
+    // Step 3: Compute local state
+    const localHead = getLocalHead(cwd);
+    const dirty = isDirty(cwd);
+    // Step 4: Short-circuit via hub meta (saves an upload if clean and matching)
+    try {
+        const meta = await api.meta(repo.hubRepoId);
+        if (meta.last_commit === localHead && !dirty) {
+            ok('Up to date');
+            return;
+        }
+    }
+    catch {
+        // Meta fetch failed; proceed with upload anyway (network hiccup, etc.)
+    }
+    // Step 5: Build tarball and upload
+    process.stdout.write('  ' + pc.cyan('→') + ' Syncing...');
+    const tarStream = buildTarballStream(cwd, { includeDirty: true });
+    let result;
+    try {
+        result = await api.sync(repo.hubRepoId, {
+            metadata: {
+                local_head: localHead,
+                local_branch: getCurrentBranch(cwd),
+                dirty,
+            },
+            tarball: tarStream,
+        });
+    }
+    catch (err) {
+        process.stdout.write('\r' + ' '.repeat(60) + '\r');
+        // Differentiate retry-later states from real failures so an LLM
+        // (or human) reading the transcript can tell whether sync is
+        // broken or just deferred.
+        if (err?.statusCode === 503) {
+            info('Hub busy — retry in a few minutes.');
+            process.exit(1);
+            return;
+        }
+        if (err?.statusCode === 409) {
+            info('Indexing in progress — retry shortly.');
+            process.exit(1);
+            return;
+        }
+        fail('Sync failed: ' + (err.message || String(err)));
+        process.exit(1);
+        return;
+    }
+    // Clear the progress line
+    process.stdout.write('\r' + ' '.repeat(60) + '\r');
+    await upsertRegistryEntry({
+        ...repo,
+        lastSyncedSha: localHead,
+        lastSyncedAt: new Date().toISOString(),
+    });
+    if (result.status === 'already_fresh') {
+        ok('Up to date');
+        return;
+    }
+    if (!opts.wait || !result.job_id) {
+        ok('Synced');
+        return;
+    }
+    // Step 6: Poll for completion
+    const jobId = result.job_id;
+    const spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    let frame = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        await new Promise((r) => setTimeout(r, 2000));
+        try {
+            const status = await api.syncStatus(repo.hubRepoId, jobId);
+            if (status.status === 'done') {
+                process.stdout.write('\r' + ' '.repeat(60) + '\r');
+                ok('Synced');
+                return;
+            }
+            if (status.status === 'failed') {
+                process.stdout.write('\r' + ' '.repeat(60) + '\r');
+                fail('Indexing failed');
+                process.exit(1);
+                return;
+            }
+            process.stdout.write(`\r  ${pc.cyan(spinnerFrames[frame % spinnerFrames.length])} Syncing...`);
+            frame++;
+        }
+        catch {
+            // Network hiccup, keep polling
+        }
+    }
+}

package/dist/tarball.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tarball builder for gnx sync uploads.
+ *
+ * Uses `git ls-files` to pick files so .gitignore is respected automatically.
+ * Optionally includes untracked files via `git ls-files --others --exclude-standard`.
+ * Returns a tar-stream Readable so callers can pipe through gzip and HTTP upload
+ * without buffering the whole tarball in memory.
+ */
+import { Readable } from 'stream';
+export interface TarballOptions {
+    includeDirty: boolean;
+}
+/**
+ * Build a tar-stream Readable containing the repo's tracked files
+ * (and optionally untracked files).
+ */
+export declare function buildTarballStream(repoRoot: string, opts: TarballOptions): Readable;

package/dist/tarball.js

@@ -0,0 +1,75 @@
+/**
+ * Tarball builder for gnx sync uploads.
+ *
+ * Uses `git ls-files` to pick files so .gitignore is respected automatically.
+ * Optionally includes untracked files via `git ls-files --others --exclude-standard`.
+ * Returns a tar-stream Readable so callers can pipe through gzip and HTTP upload
+ * without buffering the whole tarball in memory.
+ */
+import fsp from 'fs/promises';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import tar from 'tar-stream';
+/**
+ * Hardcoded exclusions regardless of .gitignore (belt-and-suspenders).
+ * .git is already excluded by `git ls-files`. These cover edge cases where
+ * users might have tracked vendor/build directories they didn't mean to ship.
+ */
+const HARD_EXCLUDES = [
+    /(\/|^)node_modules\//,
+    /^target\//,
+    /^dist\//,
+    /^build\//,
+    /^\.venv\//,
+    /^\.git\//,
+];
+function listFiles(repoRoot, includeDirty) {
+    const tracked = execFileSync('git', ['ls-files', '-z'], { cwd: repoRoot })
+        .toString('utf-8')
+        .split('\0')
+        .filter((s) => s.length > 0);
+    let all = tracked;
+    if (includeDirty) {
+        const untracked = execFileSync('git', ['ls-files', '-z', '--others', '--exclude-standard'], {
+            cwd: repoRoot,
+        })
+            .toString('utf-8')
+            .split('\0')
+            .filter((s) => s.length > 0);
+        all = [...tracked, ...untracked];
+    }
+    return all.filter((f) => !HARD_EXCLUDES.some((re) => re.test(f)));
+}
+/**
+ * Build a tar-stream Readable containing the repo's tracked files
+ * (and optionally untracked files).
+ */
+export function buildTarballStream(repoRoot, opts) {
+    const pack = tar.pack();
+    const files = listFiles(repoRoot, opts.includeDirty);
+    void (async () => {
+        for (const rel of files) {
+            try {
+                const abs = path.join(repoRoot, rel);
+                const stat = await fsp.stat(abs);
+                if (!stat.isFile())
+                    continue;
+                const content = await fsp.readFile(abs);
+                pack.entry({ name: rel, size: content.length, mode: stat.mode & 0o777 }, content);
+            }
+            catch {
+                // Skip unreadable files silently — git may have listed files that
+                // vanished or lack read permission. A missing file is not a sync failure.
+            }
+        }
+        pack.finalize();
+    })().catch((err) => {
+        try {
+            pack.destroy(err);
+        }
+        catch {
+            /* ignore */
+        }
+    });
+    return pack;
+}