gitnexus 1.6.11-rc.8 → 1.6.11

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

@@ -0,0 +1,33 @@
+export declare const AUTO_SYNC_CONFIG_FILE = "watch_config.yml";
+export declare const DEFAULT_ANALYZE_FAILURE_THRESHOLD = 3;
+export interface AutoSyncProjectConfig {
+    localPath: string;
+    groupName?: string;
+    overwriteLocalChanges: boolean;
+    branches: string[];
+    remoteUrls: string[];
+}
+export interface AutoSyncConfig {
+    configPath: string;
+    syncIntervalMinutes: number;
+    repoGitTimeoutMs: number;
+    analyzeTimeoutMs: number;
+    maxConcurrency: number;
+    analyzeFailureThreshold: number;
+    projects: AutoSyncProjectConfig[];
+}
+export type AutoSyncConfigLoadResult = {
+    ok: true;
+    config: AutoSyncConfig;
+} | {
+    ok: false;
+    reason: 'missing' | 'unreadable' | 'invalid';
+    message: string;
+};
+export declare function getAutoSyncConfigPath(gitnexusDir?: string): string;
+export declare function parseBranchCandidates(branchValue: unknown): string[];
+export declare function loadAutoSyncConfig(configPath?: string): Promise<AutoSyncConfigLoadResult>;
+export declare function parseAutoSyncConfig(content: string, configPath: string): AutoSyncConfig;
+export declare function validateAutoSyncRemoteUrl(remoteUrl: string): void;
+export declare function validateAutoSyncBranchName(branch: string): void;
+export declare function parseDurationMs(value: unknown): number;

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

@@ -0,0 +1,320 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { getGlobalDir } from '../../storage/repo-manager.js';
+import { normalizeConfiguredCloneRoot } from './path-security.js';
+const _require = createRequire(import.meta.url);
+const yaml = _require('js-yaml');
+export const AUTO_SYNC_CONFIG_FILE = 'watch_config.yml';
+const GROUP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const MIN_SYNC_INTERVAL_MINUTES = 5;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const MAX_SYNC_INTERVAL_MINUTES = Math.floor(MAX_TIMER_DELAY_MS / 60_000);
+const DEFAULT_REPO_GIT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_CONCURRENCY = 1;
+export const DEFAULT_ANALYZE_FAILURE_THRESHOLD = 3;
+const MIN_ANALYZE_FAILURE_THRESHOLD = 2;
+const ALLOWED_REMOTE_HOSTS = new Set(['github.com', 'gitlab.com', 'gitee.com']);
+/**
+ * A single clone/pull must fit inside one sync interval and inside an hour.
+ * This is also the guard for the unit slip the bare-number rule invites:
+ * `repo_git_timeout: 600000` means 600000 SECONDS (~7 days), which clears the
+ * Node timer ceiling and would silently disable the timeout.
+ */
+const MAX_REPO_GIT_TIMEOUT_MS = 3_600_000;
+// Mirrors REPO_NAME_PATTERN in server/git-clone.ts. Deliberately duplicated
+// rather than imported: git-clone.ts already imports from this module, so the
+// reverse edge would be a cycle.
+const REMOTE_REPO_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
+// Same charset for a namespace segment: GitLab subgroups allow exactly these,
+// and excluding separators is what stops a segment smuggling in traversal.
+const REMOTE_PATH_SEGMENT_PATTERN = REMOTE_REPO_NAME_PATTERN;
+export function getAutoSyncConfigPath(gitnexusDir = getGlobalDir()) {
+    return path.join(gitnexusDir, AUTO_SYNC_CONFIG_FILE);
+}
+export function parseBranchCandidates(branchValue) {
+    const rawItems = Array.isArray(branchValue)
+        ? branchValue.flatMap((item) => String(item).split(','))
+        : String(branchValue ?? '').split(',');
+    const branches = [];
+    const seen = new Set();
+    for (const item of rawItems) {
+        const branch = item.trim();
+        if (!branch || seen.has(branch))
+            continue;
+        seen.add(branch);
+        branches.push(branch);
+    }
+    return branches;
+}
+export async function loadAutoSyncConfig(configPath = getAutoSyncConfigPath()) {
+    let content;
+    try {
+        content = await fs.readFile(configPath, 'utf-8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            return {
+                ok: false,
+                reason: 'missing',
+                message: `[auto-sync] Missing config file: ${configPath}. Auto sync is skipped.`,
+            };
+        }
+        return {
+            ok: false,
+            reason: 'unreadable',
+            message: `[auto-sync] Unable to read config file: ${configPath}. Auto sync is skipped.`,
+        };
+    }
+    try {
+        return { ok: true, config: parseAutoSyncConfig(content, configPath) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: 'invalid',
+            message: `[auto-sync] Invalid watch_config.yml: ${err.message}. Auto sync is skipped.`,
+        };
+    }
+}
+export function parseAutoSyncConfig(content, configPath) {
+    const raw = yaml.load(content, { schema: yaml.JSON_SCHEMA });
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('expected a YAML object');
+    }
+    const errors = [];
+    const interval = Number(raw.sync_interval_minutes);
+    if (!Number.isInteger(interval) || interval <= 0) {
+        errors.push('sync_interval_minutes must be a positive integer');
+    }
+    else if (interval < MIN_SYNC_INTERVAL_MINUTES) {
+        errors.push(`sync_interval_minutes must be at least ${MIN_SYNC_INTERVAL_MINUTES}`);
+    }
+    else if (interval > MAX_SYNC_INTERVAL_MINUTES) {
+        errors.push(`sync_interval_minutes must not exceed ${MAX_SYNC_INTERVAL_MINUTES}`);
+    }
+    // YAML booleans survive JSON_SCHEMA (`true`/`false`). `Number(true) === 1`
+    // would otherwise pass the integer check and silently mean concurrency 1.
+    let maxConcurrency = DEFAULT_MAX_CONCURRENCY;
+    if (raw.max_concurrency !== undefined) {
+        if (typeof raw.max_concurrency !== 'number' || !Number.isInteger(raw.max_concurrency)) {
+            errors.push('max_concurrency must be a positive integer');
+        }
+        else if (raw.max_concurrency <= 0) {
+            errors.push('max_concurrency must be a positive integer');
+        }
+        else {
+            maxConcurrency = raw.max_concurrency;
+        }
+    }
+    const repoGitTimeoutMs = raw.repo_git_timeout === undefined
+        ? DEFAULT_REPO_GIT_TIMEOUT_MS
+        : parseDurationMs(raw.repo_git_timeout);
+    const maxRepoGitTimeoutMs = Number.isInteger(interval) &&
+        interval >= MIN_SYNC_INTERVAL_MINUTES &&
+        interval <= MAX_SYNC_INTERVAL_MINUTES
+        ? Math.min(interval * 60_000, MAX_REPO_GIT_TIMEOUT_MS)
+        : undefined;
+    if (!Number.isInteger(repoGitTimeoutMs) || repoGitTimeoutMs <= 0) {
+        errors.push('repo_git_timeout must be a positive duration such as 10s');
+    }
+    else if (repoGitTimeoutMs > MAX_TIMER_DELAY_MS) {
+        errors.push(`repo_git_timeout must not exceed ${MAX_TIMER_DELAY_MS}ms`);
+    }
+    else if (maxRepoGitTimeoutMs !== undefined && repoGitTimeoutMs > maxRepoGitTimeoutMs) {
+        errors.push(`repo_git_timeout must not exceed ${maxRepoGitTimeoutMs}ms (the lesser of 1h and ` +
+            `sync_interval_minutes); a bare number is interpreted as seconds, so use an explicit ` +
+            `unit such as 600000ms or 10m`);
+    }
+    const maxAnalyzeTimeoutMs = Number.isInteger(interval) &&
+        interval >= MIN_SYNC_INTERVAL_MINUTES &&
+        interval <= MAX_SYNC_INTERVAL_MINUTES
+        ? interval * 30_000
+        : undefined;
+    const analyzeTimeoutMs = raw.analyze_timeout === undefined
+        ? (maxAnalyzeTimeoutMs ?? 0)
+        : parseDurationMs(raw.analyze_timeout);
+    if (!Number.isInteger(analyzeTimeoutMs) || analyzeTimeoutMs <= 0) {
+        errors.push('analyze_timeout must be a positive duration such as 30m');
+    }
+    else if (maxAnalyzeTimeoutMs !== undefined && analyzeTimeoutMs > maxAnalyzeTimeoutMs) {
+        errors.push(`analyze_timeout must not exceed half of sync_interval_minutes (${maxAnalyzeTimeoutMs / 60_000}m)`);
+    }
+    const analyzeFailureThreshold = raw.analyze_failure_threshold === undefined
+        ? DEFAULT_ANALYZE_FAILURE_THRESHOLD
+        : Number(raw.analyze_failure_threshold);
+    if (!Number.isInteger(analyzeFailureThreshold) ||
+        analyzeFailureThreshold < MIN_ANALYZE_FAILURE_THRESHOLD) {
+        errors.push(`analyze_failure_threshold must be an integer >= ${MIN_ANALYZE_FAILURE_THRESHOLD}`);
+    }
+    const rawProjects = raw.projects;
+    if (!Array.isArray(rawProjects) || rawProjects.length === 0) {
+        errors.push('projects must contain at least one project');
+    }
+    const projects = [];
+    if (Array.isArray(rawProjects)) {
+        rawProjects.forEach((projectValue, index) => {
+            const project = projectValue;
+            if (!project || typeof project !== 'object' || Array.isArray(project)) {
+                errors.push(`projects[${index}] must be an object`);
+                return;
+            }
+            const localPath = typeof project.local_path === 'string' ? project.local_path.trim() : '';
+            if (!localPath) {
+                errors.push(`projects[${index}].local_path is required`);
+            }
+            else {
+                try {
+                    normalizeConfiguredCloneRoot(localPath);
+                }
+                catch (err) {
+                    errors.push(`projects[${index}].local_path ${err.message}`);
+                }
+            }
+            const remoteUrls = Array.isArray(project.remote_urls)
+                ? project.remote_urls.map((url) => String(url).trim()).filter(Boolean)
+                : [];
+            if (remoteUrls.length === 0) {
+                errors.push(`projects[${index}].remote_urls must contain at least one URL`);
+            }
+            for (let urlIndex = 0; urlIndex < remoteUrls.length; urlIndex += 1) {
+                try {
+                    validateAutoSyncRemoteUrl(remoteUrls[urlIndex]);
+                }
+                catch (err) {
+                    errors.push(`projects[${index}].remote_urls[${urlIndex}] ${err.message}`);
+                }
+            }
+            if (project.branch !== undefined && project.branches !== undefined) {
+                errors.push(`projects[${index}] must not set both branch and branches`);
+            }
+            const branches = parseBranchCandidates(project.branches !== undefined ? project.branches : project.branch);
+            if (branches.length === 0)
+                errors.push(`projects[${index}].branches is required`);
+            for (let branchIndex = 0; branchIndex < branches.length; branchIndex += 1) {
+                try {
+                    validateAutoSyncBranchName(branches[branchIndex]);
+                }
+                catch (err) {
+                    errors.push(`projects[${index}].branches[${branchIndex}] ${err.message}`);
+                }
+            }
+            const groupName = typeof project.group_name === 'string' && project.group_name.trim()
+                ? project.group_name.trim()
+                : undefined;
+            if (groupName && !GROUP_NAME_PATTERN.test(groupName)) {
+                errors.push(`projects[${index}].group_name is invalid`);
+            }
+            const overwriteLocalChanges = project.overwrite_local_changes === undefined ? false : project.overwrite_local_changes;
+            if (typeof overwriteLocalChanges !== 'boolean') {
+                errors.push(`projects[${index}].overwrite_local_changes must be a boolean`);
+            }
+            if (localPath && remoteUrls.length > 0 && branches.length > 0) {
+                projects.push({
+                    localPath,
+                    groupName,
+                    overwriteLocalChanges: overwriteLocalChanges === true,
+                    branches,
+                    remoteUrls,
+                });
+            }
+        });
+    }
+    if (errors.length > 0)
+        throw new Error(errors.join('; '));
+    return {
+        configPath,
+        syncIntervalMinutes: interval,
+        repoGitTimeoutMs,
+        analyzeTimeoutMs,
+        maxConcurrency,
+        analyzeFailureThreshold,
+        projects,
+    };
+}
+export function validateAutoSyncRemoteUrl(remoteUrl) {
+    const trimmed = remoteUrl.trim();
+    if (trimmed.includes('?') || trimmed.includes('#')) {
+        throw new Error('must not include query strings or fragments');
+    }
+    const match = /^git@([^:\s/]+):([^\s]+)$/.exec(trimmed);
+    if (!match) {
+        throw new Error('must use an SSH URL on github.com, gitlab.com, or gitee.com');
+    }
+    const host = match[1].toLowerCase();
+    const repoPath = match[2];
+    if (!ALLOWED_REMOTE_HOSTS.has(host)) {
+        throw new Error('host must be one of github.com, gitlab.com, or gitee.com');
+    }
+    const pathParts = repoPath.split('/');
+    // Every segment becomes a directory component: the namespace segments build
+    // the clone path and the last one names the repo. So each is held to the same
+    // charset, which is what keeps a separator out of a segment — on Windows
+    // `..\..\outside` is traversal even though the segment is not literally `..`,
+    // and testing the raw string for `..` instead would reject an ordinary
+    // `foo..bar`. Traversal is a whole segment; a separator is a character.
+    const namespaceParts = pathParts.slice(0, -1);
+    if (repoPath.startsWith('/') ||
+        pathParts.length < 2 ||
+        pathParts.some((part) => !part || part === '.' || part === '..') ||
+        namespaceParts.some((part) => !REMOTE_PATH_SEGMENT_PATTERN.test(part))) {
+        throw new Error('path must include owner/repo without traversal');
+    }
+    // The final segment becomes the on-disk clone directory via `extractRepoName`,
+    // whose name rules are stricter than the path check above: a backslash — or
+    // anything outside `[A-Za-z0-9._-]` — passes here and then throws once per
+    // tick inside the sync loop instead of at config load. These rules are a
+    // strict superset, so anything accepted here is accepted there.
+    const lastSegment = pathParts[pathParts.length - 1];
+    const repoName = /\.git$/i.test(lastSegment) ? lastSegment.slice(0, -4) : lastSegment;
+    if (!repoName ||
+        repoName === '.' ||
+        repoName === '..' ||
+        repoName === 'unknown' ||
+        repoName.startsWith('-') ||
+        !REMOTE_REPO_NAME_PATTERN.test(repoName)) {
+        throw new Error('repository name must use only letters, digits, ".", "_", or "-" and must not be "unknown"');
+    }
+}
+export function validateAutoSyncBranchName(branch) {
+    if (!branch.trim())
+        throw new Error('must not be empty');
+    if (/[\s\0-\x1f\x7f]/.test(branch))
+        throw new Error('must not contain whitespace or control characters');
+    if (/[~^:?*[\\]/.test(branch))
+        throw new Error('contains characters not allowed in a git ref');
+    if (branch.startsWith('-'))
+        throw new Error('must not start with "-"');
+    if (branch.startsWith('/'))
+        throw new Error('must not start with "/"');
+    if (branch.includes('..'))
+        throw new Error('must not contain ".."');
+    if (branch.includes('`'))
+        throw new Error('must not contain backticks');
+    if (branch.endsWith('/') || branch.endsWith('.'))
+        throw new Error('must not end with "/" or "."');
+    if (branch.includes('//'))
+        throw new Error('must not contain consecutive slashes');
+    if (branch.includes('@{'))
+        throw new Error('must not contain "@{"');
+    if (branch
+        .split('/')
+        .some((component) => component.startsWith('.') || component.endsWith('.') || component.endsWith('.lock')))
+        throw new Error('must not contain hidden, trailing-dot, or .lock path components');
+}
+export function parseDurationMs(value) {
+    if (typeof value === 'number')
+        return value * 1_000;
+    const raw = String(value ?? '').trim();
+    const match = /^(\d+)(ms|s|m)?$/.exec(raw);
+    if (!match)
+        return Number.NaN;
+    const amount = Number(match[1]);
+    const unit = match[2] ?? 's';
+    if (unit === 'ms')
+        return amount;
+    if (unit === 's')
+        return amount * 1_000;
+    return amount * 60_000;
+}

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

@@ -0,0 +1,6 @@
+export { AUTO_SYNC_CONFIG_FILE, getAutoSyncConfigPath, loadAutoSyncConfig, parseAutoSyncConfig, parseBranchCandidates, parseDurationMs, validateAutoSyncBranchName, validateAutoSyncRemoteUrl, type AutoSyncConfig, type AutoSyncConfigLoadResult, type AutoSyncProjectConfig, } from './config.js';
+export { buildStateKey, getAutoSyncMutexPath, getAutoSyncWatchDir, getAutoSyncStatePath, getProjectCommitInfoPath, loadAutoSyncState, resetAutoSyncState, saveAutoSyncState, shouldAnalyzeCommit, writeProjectCommitInfo, type AutoSyncAnalyzeStatus, type AutoSyncCommitState, type AutoSyncCommitStateEntry, type ProjectCommitInfoEntry, } from './state.js';
+export { extractRepoNameFromRemoteUrl } from './repo.js';
+export { normalizeConfiguredCloneRoot, quarantineAutoSyncPartial, resolveConfiguredCloneRoot, type AutoSyncCloneRoot, } from './path-security.js';
+export { addRepoToGroup, getAutoSyncRepoIdentity, getConfiguredRepoPath, resolveActualConcurrency, runAutoSyncOnce, syncGroupByName, type AutoSyncLogger, type AutoSyncRunDeps, type AutoSyncRunResult, } from './runner.js';
+export { getAutoSyncWatchPaths, readAutoSyncWatchStatus, startAutoSyncWatch, stopAutoSyncWatch, type AutoSyncStartHandle, type AutoSyncWatchStopResult, type AutoSyncWatchPaths, type WatchStatusRecord, } from './starter.js';

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

@@ -0,0 +1,6 @@
+export { AUTO_SYNC_CONFIG_FILE, getAutoSyncConfigPath, loadAutoSyncConfig, parseAutoSyncConfig, parseBranchCandidates, parseDurationMs, validateAutoSyncBranchName, validateAutoSyncRemoteUrl, } from './config.js';
+export { buildStateKey, getAutoSyncMutexPath, getAutoSyncWatchDir, getAutoSyncStatePath, getProjectCommitInfoPath, loadAutoSyncState, resetAutoSyncState, saveAutoSyncState, shouldAnalyzeCommit, writeProjectCommitInfo, } from './state.js';
+export { extractRepoNameFromRemoteUrl } from './repo.js';
+export { normalizeConfiguredCloneRoot, quarantineAutoSyncPartial, resolveConfiguredCloneRoot, } from './path-security.js';
+export { addRepoToGroup, getAutoSyncRepoIdentity, getConfiguredRepoPath, resolveActualConcurrency, runAutoSyncOnce, syncGroupByName, } from './runner.js';
+export { getAutoSyncWatchPaths, readAutoSyncWatchStatus, startAutoSyncWatch, stopAutoSyncWatch, } from './starter.js';

package/dist/core/auto-sync/path-security.d.ts

@@ -0,0 +1,9 @@
+export interface AutoSyncCloneRoot {
+    root: string;
+    quarantineRoot: string;
+    quarantineRetentionDays: number;
+}
+export declare function resolveConfiguredCloneRoot(localPath: string): Promise<AutoSyncCloneRoot>;
+export declare function normalizeConfiguredCloneRoot(localPath: string): string;
+export declare function quarantineAutoSyncPartial(targetDir: string, quarantineRoot: string): Promise<string>;
+export declare function assertDirectoryOwnerAndPermissions(root: string): Promise<void>;

package/dist/core/auto-sync/path-security.js

@@ -0,0 +1,251 @@
+import fs from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { getGlobalDir } from '../../storage/repo-manager.js';
+import { getAutoSyncWatchDir } from './state.js';
+const WINDOWS_DANGEROUS_ROOTS = process.platform === 'win32'
+    ? [
+        process.env.SystemRoot,
+        process.env.ProgramData,
+        process.env.ProgramFiles,
+        process.env['ProgramFiles(x86)'],
+    ].filter((entry) => Boolean(entry))
+    : [];
+const DANGEROUS_ROOTS = new Set([
+    '/',
+    os.homedir(),
+    os.tmpdir(),
+    '/bin',
+    '/boot',
+    '/dev',
+    '/etc',
+    '/lib',
+    '/lib64',
+    '/opt',
+    '/proc',
+    '/private/tmp',
+    '/private/var',
+    '/root',
+    '/sbin',
+    '/sys',
+    '/tmp',
+    '/usr',
+    '/var',
+    ...WINDOWS_DANGEROUS_ROOTS,
+].map((entry) => path.resolve(entry)));
+const DANGEROUS_PARENT_ROOTS = new Set([
+    os.tmpdir(),
+    '/bin',
+    '/boot',
+    '/dev',
+    '/etc',
+    '/lib',
+    '/lib64',
+    '/opt',
+    '/proc',
+    '/private/tmp',
+    '/private/var',
+    '/root',
+    '/sbin',
+    '/sys',
+    '/tmp',
+    '/usr',
+    '/var',
+    ...WINDOWS_DANGEROUS_ROOTS,
+].map((entry) => path.resolve(entry)));
+const QUARANTINE_RETENTION_DAYS = 14;
+const QUARANTINE_MAX_ENTRIES_PER_REPO = 5;
+// `auto-sync-<stamp>-<pid>-<uuid>-<repo basename>` — see quarantineAutoSyncPartial.
+// The UUID is the only fixed-shape field, so it anchors the grouping key, and
+// everything after it is the basename (`[A-Za-z0-9._-]` by construction).
+const QUARANTINE_ENTRY_PATTERN = /^auto-sync-.+-\d+-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}-(.+)$/i;
+export async function resolveConfiguredCloneRoot(localPath) {
+    const root = normalizeConfiguredCloneRoot(localPath);
+    assertNotDangerousRoot(root);
+    await assertNoSymlinkPath(root);
+    await fs.mkdir(root, { recursive: true });
+    await assertDirectoryOwnerAndPermissions(root);
+    const realRoot = await fs.realpath(root);
+    assertContainedOrSame(root, realRoot, 'Configured clone root realpath escaped its normalized path');
+    assertNotDangerousRoot(realRoot);
+    assertNotGitNexusInternalRoot(realRoot);
+    const quarantineRoot = path.join(getAutoSyncWatchDir(), 'quarantine');
+    await pruneQuarantineEntries(quarantineRoot);
+    return {
+        root: realRoot,
+        quarantineRoot,
+        quarantineRetentionDays: QUARANTINE_RETENTION_DAYS,
+    };
+}
+export function normalizeConfiguredCloneRoot(localPath) {
+    const value = localPath.trim();
+    if (!value)
+        throw new Error('local_path is required');
+    if (!path.isAbsolute(value))
+        throw new Error('local_path must be an absolute path');
+    if (value.split(path.sep).includes('..')) {
+        throw new Error('local_path must be normalized and must not contain traversal segments');
+    }
+    const resolved = path.resolve(value);
+    if (resolved !== path.normalize(value)) {
+        throw new Error('local_path must be normalized and must not contain traversal segments');
+    }
+    return resolved;
+}
+export async function quarantineAutoSyncPartial(targetDir, quarantineRoot) {
+    await fs.mkdir(quarantineRoot, { recursive: true, mode: 0o700 });
+    const base = path.basename(targetDir);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const destination = path.join(quarantineRoot, `auto-sync-${stamp}-${process.pid}-${randomUUID()}-${base}`);
+    try {
+        await fs.rename(targetDir, destination);
+    }
+    catch (err) {
+        if (err.code !== 'EXDEV')
+            throw err;
+        await fs.cp(targetDir, destination, { recursive: true });
+        await fs.rm(targetDir, { recursive: true, force: true });
+    }
+    await fs.writeFile(`${destination}.README.txt`, [
+        'GitNexus auto-sync isolated a partial or unsafe clone result.',
+        `Created at: ${new Date().toISOString()}`,
+        `Original path: ${targetDir}`,
+        `Retention: keep for ${QUARANTINE_RETENTION_DAYS} days unless an operator reviews and removes it earlier.`,
+        'Cleanup: verify the original path and remote before manual deletion.',
+        '',
+    ].join('\n'), 'utf-8');
+    return destination;
+}
+async function pruneQuarantineEntries(quarantineRoot) {
+    const cutoff = Date.now() - QUARANTINE_RETENTION_DAYS * 24 * 60 * 60 * 1_000;
+    // readdir and stat both resolve through a link, so a symlinked quarantine
+    // root would age-sweep and delete entries somewhere else entirely.
+    const rootStat = await fs.lstat(quarantineRoot).catch(() => undefined);
+    if (rootStat?.isSymbolicLink()) {
+        throw new Error(`Refusing symlinked auto-sync quarantine root: ${quarantineRoot}`);
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(quarantineRoot);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    const survivors = (await Promise.all(entries
+        .filter((entry) => entry.startsWith('auto-sync-'))
+        .map(async (entry) => {
+        const entryPath = path.join(quarantineRoot, entry);
+        const stat = await fs.stat(entryPath).catch(() => undefined);
+        if (stat && stat.mtimeMs < cutoff) {
+            await fs.rm(entryPath, { recursive: true, force: true });
+            return undefined;
+        }
+        return entry;
+    }))).filter((entry) => entry !== undefined);
+    // Age alone never bounds a repo that fails on every tick: one partial clone
+    // per tick stays inside the retention window forever. Keep the newest few per
+    // repo. Entries that do not match the generated naming scheme (operator
+    // notes, names from another version) are left to the age sweep alone.
+    const byRepo = new Map();
+    for (const entry of survivors) {
+        if (entry.endsWith('.README.txt'))
+            continue;
+        const repo = QUARANTINE_ENTRY_PATTERN.exec(entry)?.[1];
+        if (!repo)
+            continue;
+        const group = byRepo.get(repo) ?? [];
+        group.push(entry);
+        byRepo.set(repo, group);
+    }
+    await Promise.all([...byRepo.values()].flatMap((group) => group
+        // The timestamp is the leading fixed-width field, so a descending
+        // string sort is newest-first.
+        .sort((a, b) => (a < b ? 1 : a > b ? -1 : 0))
+        .slice(QUARANTINE_MAX_ENTRIES_PER_REPO)
+        .map(async (entry) => {
+        await fs.rm(path.join(quarantineRoot, entry), { recursive: true, force: true });
+        await fs.rm(path.join(quarantineRoot, `${entry}.README.txt`), { force: true });
+    })));
+}
+function assertNotDangerousRoot(root) {
+    if (root === path.resolve(getGlobalDir(), 'repos'))
+        return;
+    if (DANGEROUS_ROOTS.has(root))
+        throw new Error(`Refusing unsafe auto-sync clone root: ${root}`);
+    for (const dangerousRoot of DANGEROUS_PARENT_ROOTS) {
+        const rel = path.relative(dangerousRoot, root);
+        if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+            throw new Error(`Refusing unsafe auto-sync clone root under ${dangerousRoot}: ${root}`);
+        }
+    }
+    if (path.parse(root).root === root)
+        throw new Error(`Refusing filesystem root as clone root: ${root}`);
+}
+function assertNotGitNexusInternalRoot(root) {
+    const gitnexusDir = path.resolve(getGlobalDir());
+    const blocked = [
+        path.join(gitnexusDir, 'groups'),
+        path.join(gitnexusDir, 'indexes'),
+        path.join(gitnexusDir, 'quarantine'),
+        path.join(getAutoSyncWatchDir(gitnexusDir), 'quarantine'),
+    ];
+    for (const blockedRoot of blocked) {
+        const rel = path.relative(blockedRoot, root);
+        if (!rel || (!rel.startsWith('..') && !path.isAbsolute(rel))) {
+            throw new Error(`Refusing GitNexus internal directory as auto-sync clone root: ${root}`);
+        }
+    }
+}
+async function assertNoSymlinkPath(root) {
+    const parsed = path.parse(root);
+    let current = parsed.root;
+    const parts = root.slice(parsed.root.length).split(path.sep).filter(Boolean);
+    for (const part of parts) {
+        current = path.join(current, part);
+        let stat;
+        try {
+            stat = await fs.lstat(current);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                break;
+            throw err;
+        }
+        if (stat.isSymbolicLink())
+            throw new Error(`Refusing symlink in auto-sync clone root path: ${current}`);
+    }
+}
+export async function assertDirectoryOwnerAndPermissions(root) {
+    const stat = await fs.stat(root);
+    if (!stat.isDirectory())
+        throw new Error(`auto-sync clone root is not a directory: ${root}`);
+    // POSIX uid/mode have no meaning on Windows, and this runs on every tick for
+    // every project, so throwing here failed 100% of repos forever while `watch
+    // status` still read `running`. Skip the ownership assertions rather than the
+    // whole feature: the caller's other guards — dangerous-root rejection
+    // (including the Windows system roots), symlink refusal, realpath containment
+    // and the GitNexus-internal-root check — all still apply, and managed git runs
+    // with `core.hooksPath` pinned to the null device.
+    if (process.platform === 'win32')
+        return;
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+        throw new Error(`auto-sync clone root is owned by uid ${stat.uid}, not current process uid`);
+    }
+    const mode = stat.mode & 0o777;
+    const groupWritable = (mode & 0o020) !== 0;
+    const worldWritable = (mode & 0o002) !== 0;
+    if (worldWritable) {
+        throw new Error(`Refusing world-writable auto-sync clone root: ${root}`);
+    }
+    if (groupWritable) {
+        throw new Error(`Refusing group-writable auto-sync clone root: ${root}`);
+    }
+}
+function assertContainedOrSame(root, child, message) {
+    const rel = path.relative(root, child);
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        throw new Error(message);
+}

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

@@ -0,0 +1 @@
+export declare function extractRepoNameFromRemoteUrl(remoteUrl: string): string;

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

@@ -0,0 +1,6 @@
+import { extractRepoName } from '../../server/git-clone.js';
+import { validateAutoSyncRemoteUrl } from './config.js';
+export function extractRepoNameFromRemoteUrl(remoteUrl) {
+    validateAutoSyncRemoteUrl(remoteUrl);
+    return extractRepoName(remoteUrl);
+}