gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/core/auto-sync/starter.js

@@ -0,0 +1,497 @@
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { acquireFileLock, FileLockBusyError } from '../../storage/file-lock.js';
+import { getGlobalDir } from '../../storage/repo-manager.js';
+import { isProcessAlive, readProcessStartTime } from '../../utils/process-identity.js';
+import { loadAutoSyncConfig } from './config.js';
+import { runAutoSyncOnce } from './runner.js';
+import { getAutoSyncMutexPath, getAutoSyncWatchDir } from './state.js';
+const WATCH_STOP_POLL_MS = 250;
+export function getAutoSyncWatchPaths(gitnexusDir = getGlobalDir()) {
+    const watchDir = getAutoSyncWatchDir(gitnexusDir);
+    return {
+        pidPath: path.join(watchDir, 'watch.pid'),
+        mutexPath: getAutoSyncMutexPath(gitnexusDir),
+        ownerPath: path.join(watchDir, 'watch.owner.json'),
+        statusPath: path.join(watchDir, 'watch.status.json'),
+    };
+}
+export async function startAutoSyncWatch(options = {}) {
+    const stderr = options.stderr ?? process.stderr;
+    const paths = options.paths ?? getAutoSyncWatchPaths();
+    const deps = resolveWatchDeps(options.deps);
+    const ownerId = crypto.randomUUID();
+    const processStartTime = deps.readProcessStartTime(process.pid);
+    if (!processStartTime) {
+        stderr.write('[auto-sync] Unable to verify the watch process start time.\n');
+        return null;
+    }
+    await fs.mkdir(path.dirname(paths.pidPath), { recursive: true });
+    const releaseLock = await acquireWatchLock(paths, deps, stderr, processStartTime);
+    if (!releaseLock)
+        return null;
+    try {
+        await writeWatchOwner(paths, {
+            pid: process.pid,
+            ownerId,
+            processStartTime,
+            createdAt: new Date().toISOString(),
+        });
+        await writeAtomicText(paths.pidPath, `${process.pid}\n`);
+        const loaded = await loadAutoSyncConfig();
+        if (loaded.ok === false) {
+            stderr.write(`${loaded.message}\n`);
+            await writeWatchStatus(paths, {
+                state: 'error',
+                pid: process.pid,
+                ownerId,
+                message: loaded.message,
+                updatedAt: new Date().toISOString(),
+            });
+            await cleanupWatchFiles(paths, ownerId, releaseLock);
+            return null;
+        }
+        await writeWatchStatus(paths, {
+            state: 'running',
+            pid: process.pid,
+            ownerId,
+            configPath: loaded.config.configPath,
+            updatedAt: new Date().toISOString(),
+        });
+        const runOnce = options.runOnce ?? runAutoSyncOnce;
+        const setIntervalFn = options.setIntervalFn ?? setInterval;
+        const clearIntervalFn = options.clearIntervalFn ?? clearInterval;
+        let activeRun;
+        let activeAbortController;
+        let stopping = false;
+        let statusWrite = Promise.resolve();
+        const updateStatus = (state, message) => {
+            const write = statusWrite.then(() => writeWatchStatus(paths, {
+                state,
+                pid: process.pid,
+                ownerId,
+                configPath: loaded.config.configPath,
+                message,
+                updatedAt: new Date().toISOString(),
+            }));
+            statusWrite = write.catch(() => { });
+            return write;
+        };
+        const reportStatusWriteFailure = (error) => {
+            stderr.write(`[auto-sync] Failed to publish watch status: ${error.message}\n`);
+        };
+        const runSafely = () => {
+            if (stopping)
+                return;
+            if (activeRun) {
+                stderr.write('[auto-sync] Previous run is still active; skipping overlapping run.\n');
+                return;
+            }
+            const startedAt = new Date();
+            stderr.write(`[auto-sync] Watch loop started at ${startedAt.toISOString()}.\n`);
+            const abortController = new AbortController();
+            const run = runOnce(loaded.config, {
+                signal: abortController.signal,
+                onAnalysisCancellationRequested: () => {
+                    if (!stopping) {
+                        void updateStatus('cancelling', 'Analysis cancellation requested; waiting for the worker to reach a safe shutdown point.').catch(reportStatusWriteFailure);
+                    }
+                },
+            })
+                .then((result) => {
+                stderr.write(`[auto-sync] Watch loop finished: synced=${result.synced} analyzed=${result.analyzed} skipped=${result.skippedAnalysis} failed=${result.failed}.\n`);
+            })
+                .catch((err) => {
+                stderr.write(`[auto-sync] Scheduled run failed: ${err.message}\n`);
+                stderr.write('[auto-sync] Watch loop finished: failed.\n');
+            })
+                .finally(async () => {
+                if (activeRun === run) {
+                    activeRun = undefined;
+                    activeAbortController = undefined;
+                }
+                if (!stopping) {
+                    await updateStatus('running').catch(reportStatusWriteFailure);
+                }
+            });
+            activeRun = run;
+            activeAbortController = abortController;
+        };
+        let stopPromise;
+        const stop = () => (stopPromise ??= (async () => {
+            stopping = true;
+            clearIntervalFn(timer);
+            clearIntervalFn(controlTimer);
+            activeAbortController?.abort();
+            try {
+                await updateStatus('stopping');
+                await activeRun?.catch(() => { });
+                await updateStatus('stopped');
+            }
+            finally {
+                await cleanupWatchFiles(paths, ownerId, releaseLock);
+            }
+        })());
+        const checkStopRequest = async () => {
+            const request = await readStopRequest(stopRequestPath(paths, ownerId));
+            if (request?.pid === process.pid &&
+                request.ownerId === ownerId &&
+                request.processStartTime === processStartTime) {
+                void stop().catch((error) => {
+                    stderr.write(`[auto-sync] Failed to stop watch: ${error.message}\n`);
+                });
+            }
+        };
+        runSafely();
+        const controlTimer = setIntervalFn(() => void checkStopRequest(), WATCH_STOP_POLL_MS);
+        const timer = setIntervalFn(runSafely, loaded.config.syncIntervalMinutes * 60_000);
+        if (options.keepAlive === false) {
+            controlTimer.unref?.();
+            timer.unref?.();
+        }
+        return { stop };
+    }
+    catch (error) {
+        await cleanupWatchFiles(paths, ownerId, releaseLock).catch(() => { });
+        throw error;
+    }
+}
+async function acquireWatchLock(paths, deps, stderr, processStartTime) {
+    try {
+        return await acquireFileLock(paths.mutexPath, {
+            pid: process.pid,
+            processStartTime,
+            isProcessAlive: deps.isProcessAlive,
+            readProcessStartTime: deps.readProcessStartTime,
+        });
+    }
+    catch (err) {
+        if (!(err instanceof FileLockBusyError))
+            throw err;
+    }
+    const owner = await readOwnerFile(paths.ownerPath);
+    if (!owner) {
+        stderr.write(`[auto-sync] Watch mutex is held but owner metadata is not ready or invalid. Confirm no watch process is running, then remove ${paths.mutexPath}.\n`);
+        return null;
+    }
+    if (!deps.isProcessAlive(owner.pid)) {
+        stderr.write(`[auto-sync] Watch mutex remains after owner pid ${owner.pid} exited. Confirm no watch process is running, then remove ${paths.mutexPath}.\n`);
+        return null;
+    }
+    const reason = getWatchProcessIdentityError(owner, deps);
+    if (reason) {
+        stderr.write(`[auto-sync] Refusing to trust existing watch pid ${owner.pid}; ${reason}.\n`);
+        return null;
+    }
+    stderr.write(`[auto-sync] Watch is already running with pid ${owner.pid}.\n`);
+    return null;
+}
+export async function stopAutoSyncWatch(options = {}) {
+    const stderr = options.stderr ?? process.stderr;
+    const paths = options.paths ?? getAutoSyncWatchPaths();
+    const deps = resolveWatchDeps(options.deps);
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const pollMs = options.pollMs ?? 100;
+    const pid = await readPid(paths.pidPath);
+    if (!pid) {
+        const owner = await readOwnerFile(paths.ownerPath);
+        if (owner && deps.isProcessAlive(owner.pid)) {
+            stderr.write(`[auto-sync] Watch appears to be starting with pid ${owner.pid}; pid file is not ready.\n`);
+            return 'refused';
+        }
+        if (owner || (await fileExists(paths.mutexPath))) {
+            stderr.write(`[auto-sync] Watch ownership is stale or incomplete. Confirm no watch process is running, then remove ${paths.mutexPath}.\n`);
+            return 'refused';
+        }
+        stderr.write('[auto-sync] Watch is not running.\n');
+        return 'not_running';
+    }
+    if (!deps.isProcessAlive(pid)) {
+        stderr.write(`[auto-sync] Watch pid ${pid} is stale. Confirm no watch process is running, then remove ${paths.mutexPath}.\n`);
+        return 'refused';
+    }
+    const owner = await readVerifiedWatchOwner(paths, pid, deps);
+    if (owner.ok === false) {
+        stderr.write(`[auto-sync] Refusing to stop pid ${pid}; ${owner.reason}.\n`);
+        return 'refused';
+    }
+    const currentPid = await readPid(paths.pidPath);
+    const currentOwner = await readVerifiedWatchOwner(paths, pid, deps);
+    if (currentPid !== pid ||
+        currentOwner.ok === false ||
+        currentOwner.owner.ownerId !== owner.owner.ownerId) {
+        stderr.write(`[auto-sync] Refusing to stop pid ${pid}; watch ownership changed.\n`);
+        return 'refused';
+    }
+    await writeAtomicText(stopRequestPath(paths, owner.owner.ownerId), `${JSON.stringify({
+        pid,
+        ownerId: owner.owner.ownerId,
+        processStartTime: owner.owner.processStartTime,
+        requestedAt: new Date().toISOString(),
+    })}\n`);
+    stderr.write(`[auto-sync] Stop requested for watch pid ${pid}.\n`);
+    const stopped = await waitForProcessExit(pid, {
+        deps,
+        timeoutMs,
+        pollMs,
+        processStartTime: owner.owner.processStartTime,
+    });
+    if (!stopped) {
+        stderr.write(`[auto-sync] Watch pid ${pid} did not exit within ${timeoutMs}ms.\n`);
+        return 'timeout';
+    }
+    return 'stopped';
+}
+export async function readAutoSyncWatchStatus(paths = getAutoSyncWatchPaths(), deps = {}) {
+    const resolvedDeps = resolveWatchDeps(deps);
+    const pid = await readPid(paths.pidPath);
+    const stored = await readStatusFile(paths.statusPath);
+    const updatedAt = stored?.updatedAt ?? new Date().toISOString();
+    if (pid && !resolvedDeps.isProcessAlive(pid)) {
+        return {
+            ...stored,
+            state: 'stale',
+            pid,
+            message: 'pid file exists but process is not running',
+            updatedAt,
+        };
+    }
+    if (pid) {
+        const owner = await readVerifiedWatchOwner(paths, pid, resolvedDeps);
+        if (owner.ok === false) {
+            return {
+                ...stored,
+                state: 'error',
+                pid,
+                message: owner.reason,
+                updatedAt,
+            };
+        }
+        if (stored?.state === 'error') {
+            return {
+                ...stored,
+                pid,
+                ownerId: owner.owner.ownerId,
+                updatedAt,
+            };
+        }
+        return {
+            ...stored,
+            state: stored?.state === 'cancelling' || stored?.state === 'stopping' ? stored.state : 'running',
+            pid,
+            ownerId: owner.owner.ownerId,
+            updatedAt,
+        };
+    }
+    return stored ?? { state: 'stopped', updatedAt };
+}
+function isSafeWatchOwnerId(ownerId) {
+    return (ownerId === path.basename(ownerId) &&
+        !ownerId.includes('..') &&
+        !ownerId.includes('/') &&
+        !ownerId.includes('\\'));
+}
+async function readOwnerFile(ownerPath) {
+    try {
+        const raw = await fs.readFile(ownerPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === 'object' &&
+            Number.isInteger(parsed.pid) &&
+            parsed.pid > 0 &&
+            typeof parsed.ownerId === 'string' &&
+            parsed.ownerId &&
+            isSafeWatchOwnerId(parsed.ownerId) &&
+            typeof parsed.processStartTime === 'string' &&
+            parsed.processStartTime) {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        return undefined;
+    }
+}
+async function readVerifiedWatchOwner(paths, pid, deps) {
+    const [status, owner] = await Promise.all([
+        readStatusFile(paths.statusPath),
+        readOwnerFile(paths.ownerPath),
+    ]);
+    if (!owner)
+        return { ok: false, reason: 'watch owner is missing or invalid' };
+    if (!status)
+        return { ok: false, reason: 'watch status is missing or invalid' };
+    if (owner.pid !== pid)
+        return { ok: false, reason: 'watch owner pid does not match pid file' };
+    if (status.pid !== pid)
+        return { ok: false, reason: 'watch status pid does not match pid file' };
+    if (!status.ownerId || status.ownerId !== owner.ownerId) {
+        return { ok: false, reason: 'watch status owner does not match watch owner' };
+    }
+    const identityError = getWatchProcessIdentityError(owner, deps);
+    if (identityError)
+        return { ok: false, reason: identityError };
+    return { ok: true, owner };
+}
+function getWatchProcessIdentityError(owner, deps) {
+    const processStartTime = deps.readProcessStartTime(owner.pid);
+    if (!processStartTime)
+        return 'unable to verify process start time';
+    if (processStartTime !== owner.processStartTime)
+        return 'pid belongs to a different process';
+    const command = deps.readProcessCommand(owner.pid);
+    if (!command)
+        return 'unable to verify process command';
+    if (!/(?:^|\s)(?:watch|auto-sync)(?:\s|$)/.test(command) ||
+        !/(?:gitnexus|[\\/]cli[\\/]index\.(?:ts|[cm]?js))/.test(command)) {
+        return 'pid command is not a GitNexus auto-sync process';
+    }
+    return undefined;
+}
+async function waitForProcessExit(pid, options) {
+    // A bare liveness poll cannot tell "still running" from "exited, and the OS
+    // handed the pid to something else" — so a reused pid would keep us waiting
+    // on an unrelated process and then report the watch stopped once THAT exits.
+    // The start time identifies the process behind the number.
+    const isOriginalProcessAlive = () => {
+        if (!options.deps.isProcessAlive(pid))
+            return false;
+        if (!options.processStartTime)
+            return true;
+        const startTime = options.deps.readProcessStartTime(pid);
+        return startTime === undefined || startTime === options.processStartTime;
+    };
+    const deadline = Date.now() + options.timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isOriginalProcessAlive())
+            return true;
+        await options.deps.sleep(options.pollMs);
+    }
+    return !isOriginalProcessAlive();
+}
+async function readPid(pidPath) {
+    try {
+        const raw = await fs.readFile(pidPath, 'utf-8');
+        const pid = Number(raw.trim());
+        return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+}
+async function readStatusFile(statusPath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(statusPath, 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : undefined;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        return {
+            state: 'error',
+            message: `unable to read status file: ${err.message}`,
+            updatedAt: new Date().toISOString(),
+        };
+    }
+}
+function stopRequestPath(paths, ownerId) {
+    if (!isSafeWatchOwnerId(ownerId)) {
+        throw new Error('watch ownerId is not a safe filename component');
+    }
+    return path.join(path.dirname(paths.pidPath), `watch.stop.${ownerId}.json`);
+}
+async function readStopRequest(filePath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(filePath, 'utf-8'));
+        if (parsed &&
+            typeof parsed === 'object' &&
+            Number.isInteger(parsed.pid) &&
+            parsed.pid > 0 &&
+            typeof parsed.ownerId === 'string' &&
+            parsed.ownerId &&
+            typeof parsed.processStartTime === 'string' &&
+            parsed.processStartTime &&
+            typeof parsed.requestedAt === 'string' &&
+            parsed.requestedAt) {
+            return parsed;
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            return undefined;
+    }
+    return undefined;
+}
+async function writeWatchStatus(paths, record) {
+    await fs.mkdir(path.dirname(paths.statusPath), { recursive: true });
+    const tmpPath = `${paths.statusPath}.tmp.${process.pid}.${Date.now()}`;
+    await fs.writeFile(tmpPath, `${JSON.stringify(record, null, 2)}\n`, 'utf-8');
+    await fs.rename(tmpPath, paths.statusPath);
+}
+async function writeWatchOwner(paths, record) {
+    await writeAtomicText(paths.ownerPath, `${JSON.stringify(record, null, 2)}\n`);
+}
+async function cleanupWatchFiles(paths, ownerId, releaseLock) {
+    try {
+        const owner = await readOwnerFile(paths.ownerPath);
+        if (owner?.ownerId === ownerId) {
+            if ((await readPid(paths.pidPath)) === owner.pid)
+                await removeIfExists(paths.pidPath);
+            if ((await readOwnerFile(paths.ownerPath))?.ownerId === ownerId) {
+                await removeIfExists(paths.ownerPath);
+            }
+            await removeIfExists(stopRequestPath(paths, ownerId));
+        }
+    }
+    finally {
+        await releaseLock();
+    }
+}
+async function writeAtomicText(filePath, content) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.tmp.${process.pid}.${Date.now()}`;
+    await fs.writeFile(tmpPath, content, 'utf-8');
+    await fs.rename(tmpPath, filePath);
+}
+async function removeIfExists(filePath) {
+    await fs.rm(filePath, { force: true });
+}
+async function fileExists(filePath) {
+    return fs.access(filePath).then(() => true, () => false);
+}
+function resolveWatchDeps(deps = {}) {
+    return {
+        isProcessAlive: deps.isProcessAlive ?? isProcessAlive,
+        readProcessCommand: deps.readProcessCommand ??
+            ((pid) => {
+                try {
+                    const command = process.platform === 'win32'
+                        ? execFileSync('powershell.exe', [
+                            '-NoProfile',
+                            '-NonInteractive',
+                            '-Command',
+                            `(Get-CimInstance Win32_Process -Filter \"ProcessId = ${pid}\").CommandLine`,
+                        ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+                        : execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
+                            encoding: 'utf-8',
+                            stdio: ['ignore', 'pipe', 'ignore'],
+                        }).trim();
+                    return command || undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            }),
+        readProcessStartTime: deps.readProcessStartTime ?? readProcessStartTime,
+        sleep: deps.sleep ??
+            ((ms) => new Promise((resolve) => {
+                setTimeout(resolve, ms);
+            })),
+    };
+}

package/dist/core/auto-sync/state.d.ts

@@ -0,0 +1,37 @@
+export type AutoSyncAnalyzeStatus = 'success' | 'failed' | 'skipped' | 'threshold_skipped';
+export interface AutoSyncCommitStateEntry {
+    codeCommitId: string;
+    analyzedCommitId?: string;
+    lastAnalyzeStatus?: AutoSyncAnalyzeStatus;
+    analyzeConsecutiveFailures?: number;
+    lastAnalyzeError?: string;
+    groupSyncPending?: boolean;
+    lastSyncTime: string;
+}
+export type AutoSyncCommitState = Record<string, AutoSyncCommitStateEntry>;
+export declare function getAutoSyncWatchDir(gitnexusDir?: string): string;
+export declare function getAutoSyncMutexPath(gitnexusDir?: string): string;
+export declare function getAutoSyncStatePath(gitnexusDir?: string): string;
+export declare function getProjectCommitInfoPath(gitnexusDir?: string): string;
+export declare function resetAutoSyncState(gitnexusDir?: string): Promise<boolean>;
+export declare function buildStateKey(repoPath: string, branch: string): string;
+export declare function shouldAnalyzeCommit(input: {
+    currentCommit: string;
+    previousAnalyzedCommit?: string;
+    previousStatus?: AutoSyncAnalyzeStatus;
+}): boolean;
+export declare function loadAutoSyncState(statePath?: string): Promise<AutoSyncCommitState>;
+export declare function saveAutoSyncState(state: AutoSyncCommitState, statePath?: string): Promise<void>;
+export declare function writeProjectCommitInfo(entries: ProjectCommitInfoEntry[], infoPath?: string): Promise<void>;
+export interface ProjectCommitInfoEntry {
+    remoteUrl: string;
+    localPath: string;
+    branch?: string;
+    codeCommitId?: string;
+    analyzedCommitId?: string;
+    status: AutoSyncAnalyzeStatus | 'sync_failed' | 'branch_skipped' | 'branch_unavailable' | 'sync_timeout';
+    analyzeConsecutiveFailures?: number;
+    analyzeFailureThreshold?: number;
+    lastAnalyzeError?: string;
+    lastSyncTime: string;
+}

package/dist/core/auto-sync/state.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { acquireFileLock, FileLockBusyError } from '../../storage/file-lock.js';
+import { getGlobalDir } from '../../storage/repo-manager.js';
+export function getAutoSyncWatchDir(gitnexusDir = getGlobalDir()) {
+    return path.join(gitnexusDir, 'watch');
+}
+export function getAutoSyncMutexPath(gitnexusDir = getGlobalDir()) {
+    return path.join(getAutoSyncWatchDir(gitnexusDir), 'watch.mutex');
+}
+export function getAutoSyncStatePath(gitnexusDir = getGlobalDir()) {
+    return path.join(getAutoSyncWatchDir(gitnexusDir), 'auto-sync-state.json');
+}
+export function getProjectCommitInfoPath(gitnexusDir = getGlobalDir()) {
+    return path.join(getAutoSyncWatchDir(gitnexusDir), 'project_commit_info.txt');
+}
+export async function resetAutoSyncState(gitnexusDir = getGlobalDir()) {
+    let releaseLock;
+    try {
+        releaseLock = await acquireFileLock(getAutoSyncMutexPath(gitnexusDir));
+    }
+    catch (error) {
+        if (error instanceof FileLockBusyError)
+            return false;
+        throw error;
+    }
+    try {
+        await Promise.all([
+            fs.rm(getAutoSyncStatePath(gitnexusDir), { force: true }),
+            fs.rm(getProjectCommitInfoPath(gitnexusDir), { force: true }),
+        ]);
+        return true;
+    }
+    finally {
+        await releaseLock();
+    }
+}
+export function buildStateKey(repoPath, branch) {
+    return `${path.resolve(repoPath)}|${branch}`;
+}
+export function shouldAnalyzeCommit(input) {
+    if (!input.currentCommit)
+        return false;
+    if (input.previousStatus === 'failed')
+        return true;
+    return input.currentCommit !== input.previousAnalyzedCommit;
+}
+export async function loadAutoSyncState(statePath = getAutoSyncStatePath()) {
+    try {
+        const raw = await fs.readFile(statePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return Object.fromEntries(Object.entries(parsed).filter((entry) => isAutoSyncCommitStateEntry(entry[1])));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return {};
+        // Corrupt JSON is genuinely unrecoverable, so rebuilding is the only move.
+        // An unreadable file (EACCES, EIO, EISDIR) is different: the state is
+        // probably intact, and returning {} here would make the tick overwrite it,
+        // losing every repo's analyzed commit and failure count.
+        if (!(err instanceof SyntaxError))
+            throw err;
+        process.stderr.write(`[auto-sync] Ignoring corrupt state file: ${statePath}. State will be rebuilt.\n`);
+        return {};
+    }
+}
+function isAutoSyncCommitStateEntry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const entry = value;
+    return (typeof entry.codeCommitId === 'string' &&
+        typeof entry.lastSyncTime === 'string' &&
+        (entry.analyzedCommitId === undefined || typeof entry.analyzedCommitId === 'string') &&
+        (entry.lastAnalyzeStatus === undefined ||
+            entry.lastAnalyzeStatus === 'success' ||
+            entry.lastAnalyzeStatus === 'failed' ||
+            entry.lastAnalyzeStatus === 'skipped' ||
+            entry.lastAnalyzeStatus === 'threshold_skipped') &&
+        (entry.analyzeConsecutiveFailures === undefined ||
+            (typeof entry.analyzeConsecutiveFailures === 'number' &&
+                Number.isInteger(entry.analyzeConsecutiveFailures) &&
+                entry.analyzeConsecutiveFailures >= 0)) &&
+        (entry.lastAnalyzeError === undefined || typeof entry.lastAnalyzeError === 'string') &&
+        (entry.groupSyncPending === undefined || typeof entry.groupSyncPending === 'boolean'));
+}
+export async function saveAutoSyncState(state, statePath = getAutoSyncStatePath()) {
+    await fs.mkdir(path.dirname(statePath), { recursive: true });
+    const tmpPath = `${statePath}.tmp.${process.pid}.${Date.now()}`;
+    await fs.writeFile(tmpPath, `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
+    await fs.rename(tmpPath, statePath);
+}
+export async function writeProjectCommitInfo(entries, infoPath = getProjectCommitInfoPath()) {
+    await fs.mkdir(path.dirname(infoPath), { recursive: true });
+    const lines = [
+        '# GitNexus auto-sync project commit info',
+        `updated_at: ${new Date().toISOString()}`,
+        '',
+        ...entries.flatMap((entry) => [
+            `remote: ${entry.remoteUrl}`,
+            `local_path: ${entry.localPath}`,
+            `branch: ${entry.branch ?? ''}`,
+            `code_commit: ${entry.codeCommitId ?? ''}`,
+            `analyzed_commit: ${entry.analyzedCommitId ?? ''}`,
+            `status: ${entry.status}`,
+            `analyze_consecutive_failures: ${entry.analyzeConsecutiveFailures ?? 0}`,
+            ...(entry.analyzeFailureThreshold === undefined
+                ? []
+                : [`analyze_failure_threshold: ${entry.analyzeFailureThreshold}`]),
+            ...(entry.lastAnalyzeError ? [`last_analyze_error: ${entry.lastAnalyzeError}`] : []),
+            `last_sync_time: ${entry.lastSyncTime}`,
+            '',
+        ]),
+    ];
+    const tmpPath = `${infoPath}.tmp.${process.pid}.${Date.now()}`;
+    await fs.writeFile(tmpPath, `${lines.join('\n')}\n`, 'utf-8');
+    await fs.rename(tmpPath, infoPath);
+}

package/dist/core/group/config-parser.js

@@ -48,7 +48,14 @@ export function parseGroupConfig(yamlContent) {
     if (!raw.repos || typeof raw.repos !== 'object' || Array.isArray(raw.repos)) {
         throw new Error('repos is required in group.yaml (must be a mapping)');
     }
-    const repos = raw.repos;
+    const reposRaw = raw.repos;
+    const repos = {};
+    for (const [memberPath, registryName] of Object.entries(reposRaw)) {
+        if (typeof registryName !== 'string' || registryName.trim() === '') {
+            throw new Error(`repos["${memberPath}"] must be a non-empty registry name string, not ${typeof registryName}`);
+        }
+        repos[memberPath] = registryName.trim();
+    }
     const repoPaths = new Set(Object.keys(repos));
     const rawLinks = raw.links || [];
     const links = rawLinks.map((l, i) => {

package/dist/core/group/cross-impact.d.ts

@@ -62,6 +62,9 @@ export declare function validateGroupImpactParams(params: Record<string, unknown
     name: string;
     repoPath: string;
     target: string;
+    target_uid?: string;
+    file_path?: string;
+    kind?: string;
     direction: 'upstream' | 'downstream';
     maxDepth: number;
     crossDepth: number;