gitnexus 1.6.11-rc.2 → 1.6.11-rc.21

package/dist/cli/watch.js

@@ -0,0 +1,372 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { watch } from 'chokidar';
+import { createWatchIgnorePredicate } from '../config/ignore-service.js';
+import { analyzeFailureMayHaveMutatedLiveIndex, runFullAnalysis, } from '../core/run-analyze.js';
+import { getGitRoot, hasGitDir } from '../storage/git.js';
+import { GITNEXUS_DIR } from '../storage/repo-meta.js';
+import { loadAnalyzeConfigStrict, mergeAnalyzeOptions, validateBranchName, } from './analyze-config.js';
+import { ensureHeap } from './analyze.js';
+import { cliError, cliInfo, cliWarn } from './cli-message.js';
+import { WATCH_FULL_REFRESH_PATH, WatchRefreshQueue, } from './watch-queue.js';
+const DEFAULT_DEBOUNCE_MS = 300;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const MAX_FILE_SIZE_KB = 32 * 1024;
+const TRANSIENT_WATCH_ERROR_CODES = new Set(['EACCES', 'ENOENT', 'ENOTDIR', 'EPERM']);
+function posixWatchPath(filePath) {
+    return filePath.replace(/\\/g, '/').replace(/^\.\/+/, '');
+}
+export function isRelevantWatchPath(filePath) {
+    const normalized = posixWatchPath(filePath);
+    return (normalized.length > 0 &&
+        normalized !== '.' &&
+        !normalized.startsWith('../') &&
+        !path.posix.isAbsolute(normalized) &&
+        !path.win32.isAbsolute(filePath));
+}
+function isIgnoreControlPath(filePath) {
+    const normalized = posixWatchPath(filePath);
+    return normalized === '.gitignore' || normalized === '.gitnexusignore';
+}
+function isConfigControlPath(filePath) {
+    return posixWatchPath(filePath) === '.gitnexusrc';
+}
+function isAnalyzerOwnedWatchPath(filePath) {
+    const normalized = posixWatchPath(filePath).replace(/\/+$/, '');
+    return normalized === GITNEXUS_DIR || normalized.startsWith(`${GITNEXUS_DIR}/`);
+}
+function repoRelativeWatchPath(repoPath, candidate) {
+    const relative = path.relative(repoPath, candidate).replace(/\\/g, '/');
+    if (!relative || relative.startsWith('../') || path.isAbsolute(relative))
+        return null;
+    return relative;
+}
+function setEnvironment(name, value) {
+    if (value === undefined)
+        delete process.env[name];
+    else
+        process.env[name] = value;
+}
+function positiveInteger(value, flag, maximum) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1)
+        throw new Error(`${flag} must be a positive integer`);
+    if (maximum !== undefined && parsed > maximum) {
+        throw new Error(`${flag} must not exceed ${maximum}`);
+    }
+    return parsed;
+}
+export async function resolveWatchOptions(repoPath, cli, baseline, reportIgnoredConfig = () => { }) {
+    const config = (await loadAnalyzeConfigStrict(repoPath)) ?? {};
+    const merged = mergeAnalyzeOptions(cli, config);
+    const unsupported = [
+        ['--force', cli.force],
+        ['--repair-fts', cli.repairFts],
+        ['--embeddings', cli.embeddings],
+        ['--drop-embeddings', cli.dropEmbeddings],
+        ['--skills', cli.skills],
+        ['--default-branch', cli.defaultBranch],
+        ['--skip-agents-md', cli.skipAgentsMd],
+        ['--skip-skills', cli.skipSkills],
+        ['--no-stats', cli.stats === false],
+        ['--self-commit', cli.selfCommit],
+        ['--index-only', cli.indexOnly],
+        ['--skip-git', cli.skipGit],
+        ['walCheckpointThreshold', cli.walCheckpointThreshold],
+        ['embeddingThreads', cli.embeddingThreads],
+        ['embeddingBatchSize', cli.embeddingBatchSize],
+        ['embeddingSubBatchSize', cli.embeddingSubBatchSize],
+        ['embeddingDevice', cli.embeddingDevice],
+        ['embeddingBaseUrl', cli.embeddingBaseUrl],
+        ['embeddingModel', cli.embeddingModel],
+        ['--embedding-auth-token', cli.embeddingAuthToken],
+        ['--embedding-dims', cli.embeddingDims],
+    ].filter(([, value]) => value !== undefined && value !== false);
+    if (unsupported.length > 0) {
+        throw new Error(`analyze --watch does not support ${unsupported.map(([name]) => name).join(', ')}`);
+    }
+    reportIgnoredConfig([
+        ['embeddings', config.embeddings],
+        ['dropEmbeddings', config.dropEmbeddings],
+        ['defaultBranch', config.defaultBranch],
+        ['skipAgentsMd', config.skipAgentsMd !== undefined],
+        ['skipSkills', config.skipSkills !== undefined],
+        ['stats', config.stats !== undefined],
+        ['walCheckpointThreshold', config.walCheckpointThreshold],
+        ['embeddingThreads', config.embeddingThreads],
+        ['embeddingBatchSize', config.embeddingBatchSize],
+        ['embeddingSubBatchSize', config.embeddingSubBatchSize],
+        ['embeddingDevice', config.embeddingDevice],
+        ['embeddingBaseUrl', config.embeddingBaseUrl],
+        ['embeddingModel', config.embeddingModel],
+    ]
+        .filter(([, value]) => value !== undefined && value !== false)
+        .map(([name]) => String(name)));
+    const branch = merged.branch === undefined ? undefined : validateBranchName(merged.branch, '--branch');
+    const workerPoolSize = positiveInteger(merged.workers, '--workers');
+    const workerTimeoutSeconds = positiveInteger(merged.workerTimeout, 'workerTimeout');
+    const maxFileSize = positiveInteger(merged.maxFileSize, 'maxFileSize', MAX_FILE_SIZE_KB);
+    setEnvironment('GITNEXUS_MAX_FILE_SIZE', maxFileSize === undefined ? baseline.maxFileSize : String(maxFileSize));
+    if (workerTimeoutSeconds !== undefined) {
+        process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(workerTimeoutSeconds * 1000);
+    }
+    else {
+        setEnvironment('GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS', baseline.workerTimeout);
+    }
+    setEnvironment('GITNEXUS_VERBOSE', merged.verbose ? '1' : baseline.verbose);
+    return {
+        pdg: merged.pdg,
+        branch,
+        registryName: merged.name,
+        allowDuplicateName: merged.allowDuplicateName,
+        workerPoolSize,
+        fetchWrappers: merged.fetchWrappers,
+        skipAgentsMd: true,
+        skipSkills: true,
+        noStats: true,
+        atomicIncremental: process.platform !== 'win32',
+    };
+}
+function refreshSummary(result, observedPaths, durationMs, lastSuccessfulRefreshAt) {
+    const measured = result.incrementalStats;
+    const changed = measured?.changedFiles ?? (result.alreadyUpToDate ? 0 : observedPaths.length);
+    const reparsed = measured?.reparsedFiles ??
+        (typeof result.pipelineResult?.reparsedFileCount === 'number'
+            ? result.pipelineResult.reparsedFileCount
+            : 0);
+    const dependents = measured?.affectedDependents ?? 0;
+    const mode = measured?.writeMode ?? (result.alreadyUpToDate ? 'no-op' : 'full');
+    return (`Refresh complete: ${changed} changed, ${reparsed} re-parsed, ` +
+        `${dependents} affected dependent(s), ${durationMs}ms, ${mode}; ` +
+        `last success ${lastSuccessfulRefreshAt}`);
+}
+async function waitUntilReady(watcher) {
+    await new Promise((resolve, reject) => {
+        const ready = () => {
+            watcher.off('error', failed);
+            resolve();
+        };
+        const failed = (error) => {
+            watcher.off('ready', ready);
+            reject(error);
+        };
+        watcher.once('ready', ready);
+        watcher.once('error', failed);
+    });
+}
+class WatchControlReloadError extends Error {
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.name = 'WatchControlReloadError';
+    }
+}
+export function shouldStopAfterWatchRefreshFailure(error, paths) {
+    return (paths.length > 0 &&
+        !(error instanceof WatchControlReloadError) &&
+        analyzeFailureMayHaveMutatedLiveIndex(error));
+}
+/** Start the real filesystem watcher with bounded, serialized refreshes. */
+export async function startWatchFileLoop(repoPath, debounceMs, refresh, onError, onWatcherError = (error) => onError(error, [])) {
+    let ignorePath = await createWatchIgnorePredicate(repoPath);
+    let ignoreControlValid = true;
+    const queue = new WatchRefreshQueue(async (paths) => {
+        if (paths.some(isIgnoreControlPath) || !ignoreControlValid) {
+            const retryingInvalidControls = !ignoreControlValid;
+            try {
+                ignorePath = await createWatchIgnorePredicate(repoPath);
+                ignoreControlValid = true;
+                watcher.add(repoPath);
+            }
+            catch (error) {
+                ignoreControlValid = false;
+                throw new WatchControlReloadError(retryingInvalidControls
+                    ? new Error('Ignore controls remain invalid; fix them before indexing more changes.', {
+                        cause: error,
+                    })
+                    : error);
+            }
+        }
+        await refresh(paths);
+    }, onError, debounceMs, {
+        maxWaitMs: Math.max(2_000, debounceMs * 10),
+        maxPendingPaths: 1_000,
+        holdEventsUntilInitialRefresh: true,
+        isPriorityPath: (filePath) => isIgnoreControlPath(filePath) || isConfigControlPath(filePath),
+    });
+    const watcher = watch(repoPath, {
+        ignoreInitial: true,
+        atomic: true,
+        followSymlinks: false,
+        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 20 },
+        ignored: (candidate, stats) => {
+            const relative = repoRelativeWatchPath(repoPath, candidate);
+            if (relative !== null && isAnalyzerOwnedWatchPath(relative))
+                return true;
+            if (relative !== null && (isIgnoreControlPath(relative) || isConfigControlPath(relative))) {
+                return false;
+            }
+            return ignorePath(candidate, stats?.isDirectory() ?? false);
+        },
+    });
+    watcher.on('all', (event, changedPath) => {
+        if (event !== 'add' && event !== 'change' && event !== 'unlink')
+            return;
+        const relative = repoRelativeWatchPath(repoPath, changedPath);
+        if (relative && isRelevantWatchPath(relative) && !isAnalyzerOwnedWatchPath(relative)) {
+            queue.enqueue(relative);
+        }
+    });
+    watcher.on('error', (error) => {
+        // Chokidar can surface a transient EPERM on Windows while an ignored
+        // analyzer-owned path is replaced. Re-arm the root and force one bounded
+        // catch-up refresh so a missed event cannot leave the graph stale. Other
+        // watcher errors may mean coverage was lost and remain fatal.
+        if (TRANSIENT_WATCH_ERROR_CODES.has(error.code ?? '')) {
+            watcher.add(repoPath);
+            queue.enqueue(WATCH_FULL_REFRESH_PATH);
+            return;
+        }
+        onWatcherError(error);
+    });
+    try {
+        await waitUntilReady(watcher);
+        await queue.runInitial();
+    }
+    catch (error) {
+        await watcher.close();
+        await queue.close();
+        throw error;
+    }
+    return {
+        waitForIdle: () => queue.waitForIdle(),
+        close: async () => {
+            await watcher.close();
+            await queue.close();
+        },
+    };
+}
+export async function watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap, inputPath, cliOptions = {}) {
+    if (await ensureHeap({ cleanForwardedTermination: true }))
+        return;
+    const requestedRepoPath = inputPath ? path.resolve(inputPath) : getGitRoot(process.cwd());
+    if (requestedRepoPath === null || !hasGitDir(requestedRepoPath)) {
+        cliError('  gitnexus analyze --watch requires a Git repository.');
+        process.exitCode = 1;
+        return;
+    }
+    const repoPath = await fs.realpath(requestedRepoPath);
+    const baselineEnvironment = {
+        maxFileSize: process.env.GITNEXUS_MAX_FILE_SIZE,
+        workerTimeout: process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS,
+        verbose: process.env.GITNEXUS_VERBOSE,
+    };
+    try {
+        let ignoredConfigSignature;
+        const reportIgnoredConfig = (names) => {
+            const signature = [...names].sort().join(',');
+            if (signature === ignoredConfigSignature)
+                return;
+            ignoredConfigSignature = signature;
+            if (names.length > 0) {
+                cliWarn(`Watch mode ignores unsupported .gitnexusrc settings: ${names.join(', ')}.`);
+            }
+        };
+        let debounceMs;
+        let analyzeOptions;
+        try {
+            debounceMs =
+                positiveInteger(cliOptions.debounce ?? String(DEFAULT_DEBOUNCE_MS), '--debounce', MAX_TIMER_DELAY_MS) ?? DEFAULT_DEBOUNCE_MS;
+            analyzeOptions = await resolveWatchOptions(repoPath, cliOptions, baselineEnvironment, reportIgnoredConfig);
+        }
+        catch (error) {
+            cliError(`  ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+            return;
+        }
+        let stopWatching;
+        const stopped = new Promise((resolve) => {
+            stopWatching = resolve;
+        });
+        const stop = () => stopWatching();
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        try {
+            let loop;
+            let fatalRefreshError;
+            let configControlValid = true;
+            let lastSuccessfulRefreshAt;
+            try {
+                loop = await startWatchFileLoop(repoPath, debounceMs, async (paths) => {
+                    if (paths.some(isConfigControlPath) || !configControlValid) {
+                        const retryingInvalidConfig = !configControlValid;
+                        try {
+                            analyzeOptions = await resolveWatchOptions(repoPath, cliOptions, baselineEnvironment, reportIgnoredConfig);
+                            configControlValid = true;
+                        }
+                        catch (error) {
+                            configControlValid = false;
+                            throw new WatchControlReloadError(retryingInvalidConfig
+                                ? new Error('Configuration remains invalid; fix it before indexing more changes.', {
+                                    cause: error,
+                                })
+                                : error);
+                        }
+                    }
+                    const startedAt = Date.now();
+                    const result = await runFullAnalysis(repoPath, analyzeOptions, {
+                        onProgress: () => { },
+                        onLog: process.env.GITNEXUS_VERBOSE === '1'
+                            ? (message) => cliInfo(`  ${message}`)
+                            : undefined,
+                    }, runnerIdentityAtBootstrap);
+                    lastSuccessfulRefreshAt = new Date().toISOString();
+                    if (paths.length === 0) {
+                        cliInfo(result.alreadyUpToDate
+                            ? `Watching ${repoPath}; index is up to date.`
+                            : `Watching ${repoPath}; initial index ready in ${Date.now() - startedAt}ms.`);
+                    }
+                    else {
+                        cliInfo(refreshSummary(result, paths, Date.now() - startedAt, lastSuccessfulRefreshAt));
+                    }
+                }, (error, paths) => {
+                    const detail = paths.length > 0 ? ` (${paths.length} queued path(s))` : '';
+                    if (shouldStopAfterWatchRefreshFailure(error, paths)) {
+                        fatalRefreshError = error;
+                        cliError(`Refresh failed${detail}: ${error instanceof Error ? error.message : String(error)}. ` +
+                            'Watch mode is stopping because the live index may have been updated in place.');
+                        stopWatching();
+                        return;
+                    }
+                    const lastSuccess = lastSuccessfulRefreshAt ?? 'none yet';
+                    cliWarn(`Refresh failed${detail}: ${error instanceof Error ? error.message : String(error)}. ` +
+                        `Retry scheduled; last success ${lastSuccess}.`);
+                }, (error) => {
+                    fatalRefreshError = error;
+                    cliError(`Watcher failed: ${error instanceof Error ? error.message : String(error)}. ` +
+                        'Watch mode is stopping.');
+                    stopWatching();
+                });
+            }
+            catch (error) {
+                cliError(`  Unable to start watcher: ${error instanceof Error ? error.message : String(error)}`);
+                process.exitCode = 1;
+                return;
+            }
+            await stopped;
+            await loop.close();
+            if (fatalRefreshError !== undefined)
+                process.exitCode = 1;
+        }
+        finally {
+            process.removeListener('SIGINT', stop);
+            process.removeListener('SIGTERM', stop);
+        }
+    }
+    finally {
+        setEnvironment('GITNEXUS_MAX_FILE_SIZE', baselineEnvironment.maxFileSize);
+        setEnvironment('GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS', baselineEnvironment.workerTimeout);
+        setEnvironment('GITNEXUS_VERBOSE', baselineEnvironment.verbose);
+    }
+}

package/dist/cli/wiki.js

@@ -13,6 +13,7 @@ import { getStoragePaths, loadMeta, loadCLIConfig, saveCLIConfig, } from '../sto
 import { WikiGenerator } from '../core/wiki/generator.js';
 import { MINIMAX_MODEL_IDS, MINIMAX_OPENAI_BASE_URLS, parseLLMAllowedInsecureHttpHosts, resolveLLMConfig, } from '../core/wiki/llm-client.js';
 import { detectCursorCLI } from '../core/wiki/cursor-client.js';
+import { detectGrokCLI } from '../core/wiki/grok-client.js';
 import { detectLocalCLI } from '../core/wiki/local-cli-client.js';
 import { logger } from '../core/logger.js';
 function parsePositiveIntegerOption(value, flag, multiplier = 1) {
@@ -32,7 +33,8 @@ function isLocalProvider(provider) {
     return (provider === 'cursor' ||
         provider === 'claude' ||
         provider === 'codex' ||
-        provider === 'opencode');
+        provider === 'opencode' ||
+        provider === 'grok');
 }
 function localModelConfigKey(provider) {
     if (provider === 'cursor')
@@ -43,6 +45,8 @@ function localModelConfigKey(provider) {
         return 'codexModel';
     if (provider === 'opencode')
         return 'opencodeModel';
+    if (provider === 'grok')
+        return 'grokModel';
     throw new Error(`Unsupported local provider: ${provider}`);
 }
 /**
@@ -244,7 +248,7 @@ const wikiCommandImpl = async (inputPath, options) => {
             if (!llmConfig.apiKey && !isLocalProvider(llmConfig.provider)) {
                 console.log('  Error: No LLM API key found.');
                 console.log('  Set MINIMAX_API_KEY, GITNEXUS_API_KEY, or OPENAI_API_KEY,');
-                console.log('  or pass --api-key <key>, or use --provider cursor|claude|codex|opencode.\n');
+                console.log('  or pass --api-key <key>, or use --provider cursor|claude|codex|opencode|grok.\n');
                 process.exitCode = 1;
                 return;
             }
@@ -258,6 +262,7 @@ const wikiCommandImpl = async (inputPath, options) => {
             const hasClaude = detectLocalCLI('claude');
             const hasCodex = detectLocalCLI('codex');
             const hasOpenCode = detectLocalCLI('opencode');
+            const hasGrok = detectGrokCLI();
             const localChoices = [];
             // Provider selection
             console.log('  [1] OpenAI (api.openai.com)');
@@ -299,6 +304,14 @@ const wikiCommandImpl = async (inputPath, options) => {
                 });
                 console.log(`  [${choice}] OpenCode CLI (local, uses your OpenCode login/config)`);
             }
+            if (hasGrok) {
+                const choice = String(nextChoice++);
+                localChoices.push({
+                    choice,
+                    provider: 'grok',
+                });
+                console.log(`  [${choice}] Grok CLI (local, uses your Grok Build login)`);
+            }
             console.log('');
             const maxChoice = String(nextChoice - 1);
             const choice = await prompt(`  Select provider (1/${maxChoice}): `);

package/dist/config/ignore-service.d.ts

@@ -14,8 +14,19 @@ export interface IgnoreOptions {
     noGitignore?: boolean;
     /** Skip core.excludesFile and $GIT_COMMON_DIR/info/exclude. Defaults to GITNEXUS_NO_GLOBAL_IGNORE env var. */
     noGlobalIgnore?: boolean;
+    /** Fail repository-control reloads closed so long-lived watchers keep their prior predicate. */
+    strictRepoControlFiles?: boolean;
 }
 export declare const loadIgnoreRules: (repoPath: string, options?: IgnoreOptions) => Promise<Ignore | null>;
+/**
+ * Build a synchronous predicate for long-lived filesystem watchers.
+ *
+ * Unlike {@link createIgnoreFilter}, callers pass ordinary absolute or
+ * repository-relative paths instead of path-scurry `Path` objects. The rule
+ * precedence deliberately mirrors the scanner: explicit negations win over
+ * hardcoded defaults unless a more-specific rule re-ignores the path.
+ */
+export declare const createWatchIgnorePredicate: (repoPath: string, options?: IgnoreOptions) => Promise<(candidatePath: string, isDirectory?: boolean) => boolean>;
 /**
  * Create a glob-compatible ignore filter combining:
  * - .gitignore / .gitnexusignore patterns (via `ignore` package)

package/dist/config/ignore-service.js

@@ -2,6 +2,7 @@ import ignore from 'ignore';
 import { existsSync } from 'fs';
 import fs from 'fs/promises';
 import nodePath from 'path';
+import { readRepoControlFile } from './repo-control-file.js';
 import { logger } from '../core/logger.js';
 import { getCoreExcludesFilePath, getGitInfoExcludePath } from '../storage/git.js';
 const DEFAULT_IGNORE_LIST = new Set([
@@ -384,19 +385,55 @@ export const loadIgnoreRules = async (repoPath, options) => {
     const filenames = skipGitignore ? ['.gitnexusignore'] : ['.gitignore', '.gitnexusignore'];
     for (const filename of filenames) {
         try {
-            const content = await fs.readFile(nodePath.join(repoPath, filename), 'utf-8');
+            const content = options?.strictRepoControlFiles
+                ? await readRepoControlFile(repoPath, filename)
+                : await fs.readFile(nodePath.join(repoPath, filename), 'utf-8');
+            if (content === null)
+                continue;
             ig.add(content);
             hasRules = true;
         }
         catch (err) {
             const code = err.code;
-            if (code !== 'ENOENT') {
-                logger.warn(`  Warning: could not read ${filename}: ${err.message}`);
-            }
+            if (!options?.strictRepoControlFiles && code === 'ENOENT')
+                continue;
+            if (options?.strictRepoControlFiles)
+                throw err;
+            logger.warn(`  Warning: could not read ${filename}: ${err.message}`);
         }
     }
     return hasRules ? ig : null;
 };
+/**
+ * Build a synchronous predicate for long-lived filesystem watchers.
+ *
+ * Unlike {@link createIgnoreFilter}, callers pass ordinary absolute or
+ * repository-relative paths instead of path-scurry `Path` objects. The rule
+ * precedence deliberately mirrors the scanner: explicit negations win over
+ * hardcoded defaults unless a more-specific rule re-ignores the path.
+ */
+export const createWatchIgnorePredicate = async (repoPath, options) => {
+    const ig = await loadIgnoreRules(repoPath, { ...options, strictRepoControlFiles: true });
+    const repoRoot = nodePath.resolve(repoPath);
+    return (candidatePath, isDirectory = false) => {
+        const absolute = nodePath.isAbsolute(candidatePath)
+            ? nodePath.resolve(candidatePath)
+            : nodePath.resolve(repoRoot, candidatePath);
+        const rel = nodePath.relative(repoRoot, absolute).replace(/\\/g, '/');
+        if (!rel)
+            return false;
+        if (rel === '..' || rel.startsWith('../') || nodePath.isAbsolute(rel))
+            return true;
+        if (ig && hasExplicitUnignore(ig, rel) && !ig.ignores(isDirectory ? `${rel}/` : rel)) {
+            return false;
+        }
+        if (ig && ig.ignores(isDirectory ? `${rel}/` : rel))
+            return true;
+        if (isDirectory && isHardcodedIgnoredDirectoryAtPath(repoRoot, absolute))
+            return true;
+        return shouldIgnorePath(rel);
+    };
+};
 /**
  * Walk ancestor segments of `rel` and check whether `.gitnexusignore`
  * (or `.gitignore`) contains an explicit `!pattern` negation that

package/dist/config/repo-control-file.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_REPO_CONTROL_FILE_BYTES: number;
+/** Read a bounded, regular control file owned by the repository root. */
+export declare function readRepoControlFile(repoRoot: string, filename: string): Promise<string | null>;

package/dist/config/repo-control-file.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import * as path from 'node:path';
+export const MAX_REPO_CONTROL_FILE_BYTES = 1024 * 1024;
+/** Read a bounded, regular control file owned by the repository root. */
+export async function readRepoControlFile(repoRoot, filename) {
+    const requestedRoot = path.resolve(repoRoot);
+    const requested = path.resolve(requestedRoot, filename);
+    const relative = path.relative(requestedRoot, requested);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`${filename} resolves outside the repository root`);
+    }
+    try {
+        const canonicalRoot = fs.realpathSync(requestedRoot);
+        const beforeOpen = fs.lstatSync(requested);
+        if (beforeOpen.isSymbolicLink())
+            throw new Error(`${filename} must not be a symbolic link`);
+        if (!beforeOpen.isFile())
+            throw new Error(`${filename} must be a regular file`);
+        if (beforeOpen.nlink !== 1)
+            throw new Error(`${filename} must not be a hard link`);
+        if (beforeOpen.size > MAX_REPO_CONTROL_FILE_BYTES) {
+            throw new Error(`${filename} exceeds ${MAX_REPO_CONTROL_FILE_BYTES} bytes`);
+        }
+        return await new Promise((resolve, reject) => {
+            const stream = fs.createReadStream(requested, {
+                flags: 'r',
+                start: 0,
+                end: MAX_REPO_CONTROL_FILE_BYTES,
+                autoClose: true,
+            });
+            const chunks = [];
+            let totalBytes = 0;
+            let validated = false;
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(error);
+            };
+            stream.pause();
+            stream.once('open', (fd) => {
+                try {
+                    const opened = fs.fstatSync(fd);
+                    if (!opened.isFile())
+                        throw new Error(`${filename} must be a regular file`);
+                    if (opened.nlink !== 1)
+                        throw new Error(`${filename} must not be a hard link`);
+                    if (opened.size > MAX_REPO_CONTROL_FILE_BYTES) {
+                        throw new Error(`${filename} exceeds ${MAX_REPO_CONTROL_FILE_BYTES} bytes`);
+                    }
+                    const entry = fs.lstatSync(requested);
+                    if (entry.isSymbolicLink())
+                        throw new Error(`${filename} must not be a symbolic link`);
+                    if (!entry.isFile() ||
+                        entry.nlink !== 1 ||
+                        entry.dev !== opened.dev ||
+                        entry.ino !== opened.ino) {
+                        throw new Error(`${filename} moved or was replaced while being opened`);
+                    }
+                    const canonicalFile = fs.realpathSync(requested);
+                    const canonicalRelative = path.relative(canonicalRoot, canonicalFile);
+                    if (canonicalRelative.startsWith('..') || path.isAbsolute(canonicalRelative)) {
+                        throw new Error(`${filename} resolves outside the repository root`);
+                    }
+                    const canonical = fs.statSync(canonicalFile);
+                    if (canonical.nlink !== 1 ||
+                        canonical.dev !== opened.dev ||
+                        canonical.ino !== opened.ino) {
+                        throw new Error(`${filename} moved or was replaced while being opened`);
+                    }
+                    validated = true;
+                    stream.resume();
+                }
+                catch (error) {
+                    fail(error);
+                    stream.destroy();
+                }
+            });
+            stream.on('data', (chunk) => {
+                const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                totalBytes += bytes.length;
+                if (totalBytes > MAX_REPO_CONTROL_FILE_BYTES) {
+                    fail(new Error(`${filename} exceeds ${MAX_REPO_CONTROL_FILE_BYTES} bytes`));
+                    stream.destroy();
+                    return;
+                }
+                chunks.push(bytes);
+            });
+            stream.once('end', () => {
+                if (!validated) {
+                    fail(new Error(`${filename} could not be validated`));
+                    return;
+                }
+                finish(Buffer.concat(chunks, totalBytes).toString('utf8'));
+            });
+            stream.once('error', fail);
+            stream.once('close', () => {
+                if (!settled)
+                    fail(new Error(`${filename} closed before it could be read`));
+            });
+        });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}