@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/FileClassifier.js

@@ -0,0 +1,377 @@
+/**
+ * FileClassifier — Routes files to appropriate merge strategies before LLM resolution.
+ *
+ * Not all files can be text-merged. Lockfiles need regeneration, binaries need
+ * ours/theirs selection, and generated artifacts should be excluded entirely.
+ * This classifier prevents wasting LLM tokens on files that have deterministic
+ * resolution strategies.
+ *
+ * From INTELLIGENT_SYNC_SPEC Section 12 — File Classification and Special Handling.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+// ── Default Patterns ─────────────────────────────────────────────────
+const DEFAULT_LOCKFILE_PATTERNS = [
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'Cargo.lock',
+    'poetry.lock',
+    'Gemfile.lock',
+    'composer.lock',
+    'go.sum',
+];
+/** Regen commands: first = strict/deterministic, second = fallback. */
+const DEFAULT_REGEN_COMMANDS = {
+    'package-lock.json': ['npm ci', 'npm install --package-lock-only'],
+    'pnpm-lock.yaml': ['pnpm install --frozen-lockfile', 'pnpm install'],
+    'yarn.lock': ['yarn install --frozen-lockfile', 'yarn install'],
+    'Cargo.lock': ['cargo generate-lockfile'],
+    'poetry.lock': ['poetry lock --no-update'],
+    'Gemfile.lock': ['bundle install'],
+    'composer.lock': ['composer install'],
+    'go.sum': ['go mod tidy'],
+};
+const DEFAULT_LOCKFILE_MANIFESTS = {
+    'package-lock.json': 'package.json',
+    'pnpm-lock.yaml': 'package.json',
+    'yarn.lock': 'package.json',
+    'Cargo.lock': 'Cargo.toml',
+    'poetry.lock': 'pyproject.toml',
+    'Gemfile.lock': 'Gemfile',
+    'composer.lock': 'composer.json',
+    'go.sum': 'go.mod',
+};
+const DEFAULT_BINARY_EXTENSIONS = new Set([
+    // Images
+    '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico', '.webp', '.svg', '.tiff',
+    // Fonts
+    '.woff', '.woff2', '.ttf', '.otf', '.eot',
+    // Audio/Video
+    '.mp3', '.mp4', '.wav', '.ogg', '.webm', '.avi', '.mov',
+    // Archives
+    '.zip', '.tar', '.gz', '.bz2', '.7z', '.rar',
+    // Documents
+    '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+    // Databases
+    '.sqlite', '.db', '.sqlite3',
+    // Design
+    '.psd', '.ai', '.sketch', '.fig',
+    // Compiled
+    '.wasm', '.dylib', '.so', '.dll', '.exe', '.o', '.a',
+    // Other
+    '.bin', '.dat',
+]);
+const DEFAULT_GENERATED_PATTERNS = [
+    'dist/', 'build/', '.next/', 'out/',
+    'node_modules/', '__pycache__/', '.pytest_cache/',
+    '*.min.js', '*.min.css', '*.map',
+    'coverage/', '.nyc_output/',
+    'target/', // Rust/Java
+];
+const DEFAULT_SECRET_PATTERNS = [
+    '.env', '.env.*',
+    '*.pem', '*.key', '*.p12', '*.pfx',
+    '*credentials*', '*secret*',
+    'id_rsa', 'id_ed25519', 'id_ecdsa',
+    '.npmrc', // may contain tokens
+];
+const SOURCE_CODE_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.py', '.pyw',
+    '.rs', '.go', '.java', '.kt', '.scala',
+    '.c', '.cpp', '.cc', '.h', '.hpp',
+    '.rb', '.php', '.swift', '.m',
+    '.sh', '.bash', '.zsh', '.fish',
+    '.sql', '.graphql', '.gql',
+    '.r', '.R', '.jl',
+    '.lua', '.zig', '.nim', '.v',
+    '.css', '.scss', '.sass', '.less', '.styl',
+    '.html', '.htm', '.xml', '.xsl',
+    '.vue', '.svelte', '.astro',
+    '.prisma', '.proto', '.thrift',
+    '.toml', '.yaml', '.yml', '.ini', '.cfg',
+]);
+const DOC_EXTENSIONS = new Set([
+    '.md', '.mdx', '.txt', '.rst', '.adoc', '.org',
+]);
+// ── Classifier ───────────────────────────────────────────────────────
+export class FileClassifier {
+    projectDir;
+    lockfilePatterns;
+    regenCommands;
+    binaryExtensions;
+    generatedPatterns;
+    secretPatterns;
+    constructor(config) {
+        this.projectDir = config.projectDir;
+        this.lockfilePatterns = [
+            ...DEFAULT_LOCKFILE_PATTERNS,
+            ...(config.extraLockfilePatterns ?? []),
+        ];
+        this.regenCommands = {
+            ...DEFAULT_REGEN_COMMANDS,
+            ...(config.extraRegenCommands ?? {}),
+        };
+        this.binaryExtensions = new Set([
+            ...DEFAULT_BINARY_EXTENSIONS,
+            ...(config.extraBinaryExtensions ?? []),
+        ]);
+        this.generatedPatterns = [
+            ...DEFAULT_GENERATED_PATTERNS,
+            ...(config.extraExcludePatterns ?? []),
+        ];
+        this.secretPatterns = [
+            ...DEFAULT_SECRET_PATTERNS,
+            ...(config.extraSecretPatterns ?? []),
+        ];
+    }
+    /**
+     * Classify a file and determine its merge strategy.
+     */
+    classify(filePath) {
+        const relPath = path.relative(this.projectDir, filePath);
+        const basename = path.basename(relPath);
+        const ext = path.extname(relPath).toLowerCase();
+        // Check in priority order (most specific → most general)
+        // 1. Secrets — never sync
+        if (this.isSecret(relPath, basename)) {
+            return {
+                fileClass: 'secret',
+                strategy: 'never-sync',
+                reason: `Secret file detected: ${basename}`,
+            };
+        }
+        // 2. Generated artifacts — exclude from sync
+        if (this.isGenerated(relPath)) {
+            return {
+                fileClass: 'generated',
+                strategy: 'exclude',
+                reason: `Generated artifact: ${relPath}`,
+            };
+        }
+        // 3. Lockfiles — regenerate, never text-merge
+        const lockfileMatch = this.isLockfile(basename);
+        if (lockfileMatch) {
+            return {
+                fileClass: 'lockfile',
+                strategy: 'regenerate',
+                regenCommands: this.regenCommands[lockfileMatch] ?? [],
+                manifestFile: DEFAULT_LOCKFILE_MANIFESTS[lockfileMatch],
+                reason: `Lockfile: ${basename} (regenerate via package manager)`,
+            };
+        }
+        // 4. Binary files — ours/theirs
+        if (this.binaryExtensions.has(ext)) {
+            return {
+                fileClass: 'binary',
+                strategy: 'ours-theirs',
+                reason: `Binary file: ${basename} (${ext})`,
+            };
+        }
+        // 5. Structured data (.instar/ JSON/YAML) — programmatic
+        if (this.isStructuredData(relPath, ext)) {
+            return {
+                fileClass: 'structured-data',
+                strategy: 'programmatic',
+                reason: `Structured data: ${relPath}`,
+            };
+        }
+        // 6. Documentation — LLM with section-aware context
+        if (DOC_EXTENSIONS.has(ext)) {
+            return {
+                fileClass: 'documentation',
+                strategy: 'llm',
+                reason: `Documentation: ${basename}`,
+            };
+        }
+        // 7. Source code — LLM escalation
+        if (SOURCE_CODE_EXTENSIONS.has(ext)) {
+            return {
+                fileClass: 'source-code',
+                strategy: 'llm',
+                reason: `Source code: ${basename} (${ext})`,
+            };
+        }
+        // 8. Unknown — treat as source code (safe default: LLM tries, then human)
+        return {
+            fileClass: 'source-code',
+            strategy: 'llm',
+            reason: `Unknown file type: ${basename} — defaulting to LLM resolution`,
+        };
+    }
+    /**
+     * Resolve a lockfile conflict by regenerating from manifest.
+     * Returns true if regeneration succeeded.
+     */
+    regenerateLockfile(filePath, classification) {
+        if (classification.strategy !== 'regenerate' || !classification.regenCommands?.length) {
+            return { success: false, error: 'No regeneration commands available' };
+        }
+        // Accept ours version of the manifest file first
+        if (classification.manifestFile) {
+            const manifestPath = path.join(this.projectDir, classification.manifestFile);
+            if (fs.existsSync(manifestPath)) {
+                try {
+                    execFileSync('git', ['checkout', '--ours', classification.manifestFile], {
+                        cwd: this.projectDir,
+                        stdio: 'pipe',
+                    });
+                    execFileSync('git', ['add', classification.manifestFile], {
+                        cwd: this.projectDir,
+                        stdio: 'pipe',
+                    });
+                }
+                catch {
+                    // @silent-fallback-ok — manifest checkout is pre-regen prep; regen will recreate it anyway
+                }
+            }
+        }
+        // Try regeneration commands in order (strict → fallback)
+        for (const cmd of classification.regenCommands) {
+            try {
+                const [bin, ...args] = cmd.split(' ');
+                execFileSync(bin, args, {
+                    cwd: this.projectDir,
+                    stdio: 'pipe',
+                    timeout: 120_000,
+                });
+                // Stage the regenerated lockfile
+                const relPath = path.relative(this.projectDir, filePath);
+                execFileSync('git', ['add', relPath], {
+                    cwd: this.projectDir,
+                    stdio: 'pipe',
+                });
+                return { success: true, command: cmd };
+            }
+            catch {
+                // Try next command
+                continue;
+            }
+        }
+        return {
+            success: false,
+            error: `All regeneration commands failed: ${classification.regenCommands.join(', ')}`,
+        };
+    }
+    /**
+     * Resolve a binary file conflict using hash divergence detection.
+     * Returns which side to pick, or 'conflict' if both sides changed.
+     */
+    resolveBinary(filePath) {
+        const relPath = path.relative(this.projectDir, filePath);
+        try {
+            // Get hashes from git stages
+            // Stage 1 = merge base, Stage 2 = ours, Stage 3 = theirs
+            const baseHash = this.getStageHash(relPath, 1);
+            const oursHash = this.getStageHash(relPath, 2);
+            const theirsHash = this.getStageHash(relPath, 3);
+            if (!baseHash || !oursHash || !theirsHash) {
+                return { resolution: 'conflict', reason: 'Could not read git stages for binary file' };
+            }
+            const oursChanged = oursHash !== baseHash;
+            const theirsChanged = theirsHash !== baseHash;
+            if (oursChanged && !theirsChanged) {
+                return { resolution: 'ours', reason: 'Only our side modified the binary file' };
+            }
+            if (!oursChanged && theirsChanged) {
+                return { resolution: 'theirs', reason: 'Only their side modified the binary file' };
+            }
+            if (!oursChanged && !theirsChanged) {
+                // Both sides identical to base — no real conflict
+                return { resolution: 'ours', reason: 'No actual change on either side' };
+            }
+            // Both sides changed — real conflict
+            return {
+                resolution: 'conflict',
+                reason: 'Both sides modified the binary file — needs human decision',
+            };
+        }
+        catch {
+            return { resolution: 'conflict', reason: 'Error reading git stages for binary file' };
+        }
+    }
+    // ── Private Helpers ────────────────────────────────────────────────
+    isSecret(relPath, basename) {
+        for (const pattern of this.secretPatterns) {
+            if (pattern.startsWith('*') && pattern.endsWith('*')) {
+                // *pattern* → contains
+                const inner = pattern.slice(1, -1);
+                if (basename.toLowerCase().includes(inner))
+                    return true;
+            }
+            else if (pattern.startsWith('*.')) {
+                // *.ext → extension match
+                const ext = pattern.slice(1);
+                if (basename.endsWith(ext))
+                    return true;
+            }
+            else if (pattern.includes('.*')) {
+                // .env.* → prefix match
+                const prefix = pattern.split('.*')[0];
+                if (basename.startsWith(prefix))
+                    return true;
+            }
+            else {
+                // Exact match
+                if (basename === pattern)
+                    return true;
+            }
+        }
+        return false;
+    }
+    isGenerated(relPath) {
+        const normalized = relPath.replace(/\\/g, '/');
+        for (const pattern of this.generatedPatterns) {
+            if (pattern.endsWith('/')) {
+                // Directory pattern
+                if (normalized.startsWith(pattern) || normalized.includes('/' + pattern))
+                    return true;
+            }
+            else if (pattern.startsWith('*.')) {
+                // Extension glob
+                const ext = pattern.slice(1);
+                if (normalized.endsWith(ext))
+                    return true;
+            }
+            else {
+                if (normalized === pattern || normalized.endsWith('/' + pattern))
+                    return true;
+            }
+        }
+        return false;
+    }
+    isLockfile(basename) {
+        for (const pattern of this.lockfilePatterns) {
+            if (basename === pattern)
+                return pattern;
+        }
+        return null;
+    }
+    isStructuredData(relPath, ext) {
+        // .instar/ state files
+        if (relPath.startsWith('.instar/') && (ext === '.json' || ext === '.yaml' || ext === '.yml')) {
+            return true;
+        }
+        return false;
+    }
+    getStageHash(relPath, stage) {
+        try {
+            const output = execFileSync('git', ['ls-files', '-s', '--', relPath], { cwd: this.projectDir, encoding: 'utf-8', stdio: 'pipe' });
+            // Output: "mode hash stage\tfilename" — one line per stage
+            for (const line of output.trim().split('\n')) {
+                const parts = line.trim().split(/\s+/);
+                if (parts.length >= 3 && parseInt(parts[2], 10) === stage) {
+                    return parts[1]; // SHA hash
+                }
+            }
+            return null;
+        }
+        catch {
+            // @silent-fallback-ok — git ls-files for blob hash lookup; null means stage not available
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=FileClassifier.js.map

package/dist/core/FileClassifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileClassifier.js","sourceRoot":"","sources":["../../src/core/FileClassifier.ts"],"names":[],"mappings":"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"}

package/dist/core/ForegroundRestartWatcher.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ForegroundRestartWatcher — Detects restart-requested signals in foreground mode.
+ *
+ * ROOT CAUSE (v0.9.71 investigation):
+ * The AutoUpdater writes `restart-requested.json` after installing an update.
+ * The ServerSupervisor (lifeline) polls this file and performs the restart.
+ * BUT: when the server runs in `--foreground` mode (which ALL agents currently do),
+ * there IS no supervisor — nobody picks up the restart signal, it expires after
+ * the TTL, and the process runs forever on old code.
+ *
+ * This module fills that gap for foreground mode:
+ * 1. Polls for `restart-requested.json` every 10 seconds (matching supervisor cadence)
+ * 2. When detected: sends IMMEDIATE notification, logs loudly, exits cleanly
+ * 3. The process exit allows the tmux session or wrapper to respawn
+ *
+ * This module is ONLY used in foreground mode. When a supervisor is running,
+ * it handles restarts and this watcher should not be started.
+ */
+import { EventEmitter } from 'node:events';
+export interface RestartRequest {
+    requestedAt: string;
+    requestedBy: string;
+    targetVersion: string;
+    previousVersion: string;
+    plannedRestart?: boolean;
+    expiresAt?: string;
+    pid?: number;
+}
+export interface ForegroundRestartWatcherConfig {
+    stateDir: string;
+    /** Callback to send a notification before exiting. */
+    onRestartDetected?: (request: RestartRequest) => void | Promise<void>;
+    /** Poll interval in ms. Default: 10_000 (10 seconds). */
+    pollIntervalMs?: number;
+    /** Graceful shutdown delay in ms after notification. Default: 3_000 (3 seconds). */
+    shutdownDelayMs?: number;
+    /** If true, exit the process after detecting restart. Default: true. */
+    exitOnRestart?: boolean;
+    /** Process exit code. Default: 0. */
+    exitCode?: number;
+}
+export declare class ForegroundRestartWatcher extends EventEmitter {
+    private config;
+    private interval;
+    private flagPath;
+    private isShuttingDown;
+    constructor(config: ForegroundRestartWatcherConfig);
+    start(): void;
+    stop(): void;
+    /**
+     * Check for a restart-requested signal. If found and valid, trigger shutdown.
+     */
+    private check;
+}
+//# sourceMappingURL=ForegroundRestartWatcher.d.ts.map

package/dist/core/ForegroundRestartWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForegroundRestartWatcher.d.ts","sourceRoot":"","sources":["../../src/core/ForegroundRestartWatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,wBAAyB,SAAQ,YAAY;IACxD,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,EAAE,8BAA8B;IAMlD,KAAK,IAAI,IAAI;IAUb,IAAI,IAAI,IAAI;IAOZ;;OAEG;YACW,KAAK;CAiEpB"}

package/dist/core/ForegroundRestartWatcher.js

@@ -0,0 +1,116 @@
+/**
+ * ForegroundRestartWatcher — Detects restart-requested signals in foreground mode.
+ *
+ * ROOT CAUSE (v0.9.71 investigation):
+ * The AutoUpdater writes `restart-requested.json` after installing an update.
+ * The ServerSupervisor (lifeline) polls this file and performs the restart.
+ * BUT: when the server runs in `--foreground` mode (which ALL agents currently do),
+ * there IS no supervisor — nobody picks up the restart signal, it expires after
+ * the TTL, and the process runs forever on old code.
+ *
+ * This module fills that gap for foreground mode:
+ * 1. Polls for `restart-requested.json` every 10 seconds (matching supervisor cadence)
+ * 2. When detected: sends IMMEDIATE notification, logs loudly, exits cleanly
+ * 3. The process exit allows the tmux session or wrapper to respawn
+ *
+ * This module is ONLY used in foreground mode. When a supervisor is running,
+ * it handles restarts and this watcher should not be started.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { EventEmitter } from 'node:events';
+export class ForegroundRestartWatcher extends EventEmitter {
+    config;
+    interval = null;
+    flagPath;
+    isShuttingDown = false;
+    constructor(config) {
+        super();
+        this.config = config;
+        this.flagPath = path.join(config.stateDir, 'state', 'restart-requested.json');
+    }
+    start() {
+        if (this.interval)
+            return;
+        const pollMs = this.config.pollIntervalMs ?? 10_000;
+        this.interval = setInterval(() => this.check(), pollMs);
+        this.interval.unref(); // Don't keep process alive just for polling
+        console.log(`[ForegroundRestartWatcher] Watching for restart signals (every ${pollMs / 1000}s)`);
+    }
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+    }
+    /**
+     * Check for a restart-requested signal. If found and valid, trigger shutdown.
+     */
+    async check() {
+        if (this.isShuttingDown)
+            return;
+        try {
+            if (!fs.existsSync(this.flagPath))
+                return;
+            const raw = fs.readFileSync(this.flagPath, 'utf-8');
+            const data = JSON.parse(raw);
+            // Check TTL — but DON'T silently ignore expired requests.
+            // In foreground mode, the restart is critical. If the flag expired,
+            // it means we've been stale for too long. Still restart.
+            const isExpired = data.expiresAt && new Date(data.expiresAt).getTime() < Date.now();
+            if (isExpired) {
+                console.warn(`[ForegroundRestartWatcher] Restart request EXPIRED but still acting on it — stale process is worse than late restart`);
+            }
+            console.log(`[ForegroundRestartWatcher] Restart requested by ${data.requestedBy} for v${data.targetVersion} (from v${data.previousVersion})`);
+            // Clear the flag to prevent re-triggering on next startup
+            try {
+                fs.unlinkSync(this.flagPath);
+            }
+            catch { /* ignore */ }
+            // Write a planned-exit marker so the supervisor (if running) knows this
+            // was a planned restart, not a crash. Solves the race condition where we
+            // consume restart-requested.json before the supervisor sees it.
+            if (data.plannedRestart) {
+                const markerPath = path.join(path.dirname(this.flagPath), 'planned-exit-marker.json');
+                try {
+                    fs.writeFileSync(markerPath, JSON.stringify({
+                        exitedAt: new Date().toISOString(),
+                        targetVersion: data.targetVersion,
+                        previousVersion: data.previousVersion,
+                        pid: process.pid,
+                    }));
+                }
+                catch { /* best effort */ }
+            }
+            this.isShuttingDown = true;
+            this.emit('restartDetected', data);
+            // Notify via callback (e.g., Telegram)
+            if (this.config.onRestartDetected) {
+                try {
+                    await this.config.onRestartDetected(data);
+                }
+                catch (err) {
+                    console.error(`[ForegroundRestartWatcher] Notification callback failed:`, err);
+                }
+            }
+            // Graceful shutdown delay — let notifications flush
+            const shouldExit = this.config.exitOnRestart ?? true;
+            if (shouldExit) {
+                const delayMs = this.config.shutdownDelayMs ?? 3_000;
+                console.log(`[ForegroundRestartWatcher] Exiting in ${delayMs / 1000}s for restart...`);
+                setTimeout(() => {
+                    console.log(`[ForegroundRestartWatcher] Goodbye. Restart to load v${data.targetVersion}.`);
+                    process.exit(this.config.exitCode ?? 0);
+                }, delayMs);
+            }
+        }
+        catch {
+            // Malformed flag — clean up
+            try {
+                fs.unlinkSync(this.flagPath);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+//# sourceMappingURL=ForegroundRestartWatcher.js.map

package/dist/core/ForegroundRestartWatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForegroundRestartWatcher.js","sourceRoot":"","sources":["../../src/core/ForegroundRestartWatcher.ts"],"names":[],"mappings":"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"}

package/dist/core/GitStateManager.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Git State Manager — optional git tracking of agent state files.
+ *
+ * Only supported for standalone agents. Project-bound agents already
+ * live inside a git repository — use the parent repo directly.
+ *
+ * Security:
+ *   - Remote URL validation: only https://, git@, ssh:// allowed
+ *   - Re-validates remote URL before every push/pull (defense against config poisoning)
+ *   - Auto-commit messages avoid PII
+ *   - config.json is always in .gitignore
+ *   - relationships/ is git-ignored by default (GDPR Article 6)
+ */
+import type { GitStateConfig, GitLogEntry, GitStatus } from './types.js';
+export declare class GitStateManager {
+    private readonly stateDir;
+    private readonly config;
+    private debounceTimer;
+    private lastCommitTime;
+    constructor(stateDir: string, config?: Partial<GitStateConfig>);
+    /**
+     * Validate a remote URL — only https://, git@, ssh:// allowed.
+     * Called at three points: CLI remote set, push(), pull().
+     */
+    static validateRemoteUrl(url: string): boolean;
+    /**
+     * Initialize git tracking in the .instar/ directory.
+     * Creates .gitignore and runs git init.
+     */
+    init(): void;
+    /**
+     * Check if git tracking is active.
+     */
+    isInitialized(): boolean;
+    /**
+     * Stage and commit specific files (or all tracked).
+     */
+    commit(message: string, files?: string[]): void;
+    /**
+     * Debounced auto-commit with structured message format.
+     */
+    autoCommit(category: string, brief: string): void;
+    /**
+     * Cancel any pending auto-commit timer.
+     */
+    cancelPendingCommit(): void;
+    /**
+     * Push to remote. Re-validates remote URL before every push.
+     */
+    push(): {
+        firstPush: boolean;
+    };
+    /**
+     * Pull from remote. Re-validates remote URL before every pull.
+     */
+    pull(): void;
+    /**
+     * Get recent commit history.
+     */
+    log(limit?: number): GitLogEntry[];
+    /**
+     * Get current git status.
+     */
+    status(): GitStatus;
+    /**
+     * Set the remote URL (validates scheme).
+     */
+    setRemote(url: string): void;
+    /**
+     * Get the current configuration.
+     */
+    getConfig(): GitStateConfig;
+    /**
+     * Execute a git command in the state directory.
+     */
+    private git;
+}
+//# sourceMappingURL=GitStateManager.d.ts.map

package/dist/core/GitStateManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitStateManager.d.ts","sourceRoot":"","sources":["../../src/core/GitStateManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA6CzE,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,cAAc,CAAa;gBAEvB,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAK9D;;;OAGG;IACH,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAgB9C;;;OAGG;IACH,IAAI,IAAI,IAAI;IAmBZ;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI;IA8B/C;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAwBjD;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAO3B;;OAEG;IACH,IAAI,IAAI;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE;IAoC9B;;OAEG;IACH,IAAI,IAAI,IAAI;IA6BZ;;OAEG;IACH,GAAG,CAAC,KAAK,GAAE,MAAW,GAAG,WAAW,EAAE;IAoBtC;;OAEG;IACH,MAAM,IAAI,SAAS;IAwEnB;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAmB5B;;OAEG;IACH,SAAS,IAAI,cAAc;IAI3B;;OAEG;IACH,OAAO,CAAC,GAAG;CAkBZ"}