@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/GitStateManager.js

@@ -0,0 +1,366 @@
+/**
+ * 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 { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+const ALLOWED_REMOTE_SCHEMES = [
+    /^https:\/\//,
+    /^git@/,
+    /^ssh:\/\//,
+];
+const BLOCKED_REMOTE_SCHEMES = [
+    /^git:\/\//,
+    /^file:\/\//,
+    /^ftp:\/\//,
+];
+const DEFAULT_GITIGNORE = `# Runtime state -- NOT tracked
+state/
+logs/
+*.tmp
+*.pid
+
+# Secrets -- NEVER tracked
+config.json
+
+# Derived data -- reconstructable
+memory.db
+memory.db-wal
+memory.db-shm
+backups/
+
+# Tracked state:
+# AGENT.md, USER.md, MEMORY.md
+# jobs.json
+# users.json
+# hooks/ (generated but version-trackable)
+# evolution/ (proposals, learnings, gaps)
+`;
+const DEFAULT_CONFIG = {
+    enabled: false,
+    branch: 'main',
+    autoCommit: true,
+    autoPush: false,
+    commitDebounceSeconds: 60,
+};
+export class GitStateManager {
+    stateDir;
+    config;
+    debounceTimer = null;
+    lastCommitTime = 0;
+    constructor(stateDir, config) {
+        this.stateDir = path.resolve(stateDir);
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Validate a remote URL — only https://, git@, ssh:// allowed.
+     * Called at three points: CLI remote set, push(), pull().
+     */
+    static validateRemoteUrl(url) {
+        if (!url || typeof url !== 'string')
+            return false;
+        // Check for blocked schemes first
+        for (const pattern of BLOCKED_REMOTE_SCHEMES) {
+            if (pattern.test(url))
+                return false;
+        }
+        // Must match an allowed scheme
+        for (const pattern of ALLOWED_REMOTE_SCHEMES) {
+            if (pattern.test(url))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Initialize git tracking in the .instar/ directory.
+     * Creates .gitignore and runs git init.
+     */
+    init() {
+        if (this.isInitialized()) {
+            throw new Error('Git tracking is already initialized in this directory.');
+        }
+        // Write .gitignore before git init
+        const gitignorePath = path.join(this.stateDir, '.gitignore');
+        if (!fs.existsSync(gitignorePath)) {
+            fs.writeFileSync(gitignorePath, DEFAULT_GITIGNORE);
+        }
+        // git init
+        this.git('init', '-b', this.config.branch);
+        // Initial commit
+        this.git('add', '-A');
+        this.git('commit', '-m', '[instar] init: initialized git state tracking');
+    }
+    /**
+     * Check if git tracking is active.
+     */
+    isInitialized() {
+        return fs.existsSync(path.join(this.stateDir, '.git'));
+    }
+    /**
+     * Stage and commit specific files (or all tracked).
+     */
+    commit(message, files) {
+        if (!this.isInitialized()) {
+            throw new Error('Git tracking is not initialized. Run `instar git init` first.');
+        }
+        if (files && files.length > 0) {
+            for (const file of files) {
+                // Validate path containment
+                const resolved = path.resolve(this.stateDir, file);
+                if (!resolved.startsWith(this.stateDir + path.sep) && resolved !== this.stateDir) {
+                    throw new Error(`File outside state directory: ${file}`);
+                }
+                if (fs.existsSync(resolved)) {
+                    this.git('add', file);
+                }
+            }
+        }
+        else {
+            this.git('add', '-A');
+        }
+        // Check if there's anything to commit
+        const status = this.git('status', '--porcelain');
+        if (!status.trim()) {
+            return; // Nothing to commit
+        }
+        this.git('commit', '-m', message);
+        this.lastCommitTime = Date.now();
+    }
+    /**
+     * Debounced auto-commit with structured message format.
+     */
+    autoCommit(category, brief) {
+        if (!this.config.autoCommit || !this.isInitialized())
+            return;
+        // Clear any pending debounce
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        const debounceMs = this.config.commitDebounceSeconds * 1000;
+        this.debounceTimer = setTimeout(() => {
+            try {
+                this.commit(`[instar] ${category}: ${brief}`);
+                if (this.config.autoPush && this.config.remote) {
+                    this.push();
+                }
+            }
+            catch {
+                // @silent-fallback-ok — auto-commit non-fatal
+            }
+            this.debounceTimer = null;
+        }, debounceMs);
+    }
+    /**
+     * Cancel any pending auto-commit timer.
+     */
+    cancelPendingCommit() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+    }
+    /**
+     * Push to remote. Re-validates remote URL before every push.
+     */
+    push() {
+        if (!this.isInitialized()) {
+            throw new Error('Git tracking is not initialized.');
+        }
+        const remote = this.config.remote;
+        if (!remote) {
+            throw new Error('No remote configured. Use `instar git remote <url>` to set one.');
+        }
+        // Re-validate remote at execution time (defense against config poisoning)
+        if (!GitStateManager.validateRemoteUrl(remote)) {
+            throw new Error(`Invalid remote URL: only https://, git@, and ssh:// schemes are allowed. Got: ${remote}`);
+        }
+        const isFirstPush = this.config.lastPushedRemote !== remote;
+        // Ensure remote is configured in git
+        try {
+            this.git('remote', 'get-url', 'origin');
+            this.git('remote', 'set-url', 'origin', remote);
+        }
+        catch {
+            // @silent-fallback-ok — remote URL set, try add instead
+            this.git('remote', 'add', 'origin', remote);
+        }
+        this.git('push', '-u', 'origin', this.config.branch);
+        // Track that we've pushed to this remote
+        this.config.lastPushedRemote = remote;
+        return { firstPush: isFirstPush };
+    }
+    /**
+     * Pull from remote. Re-validates remote URL before every pull.
+     */
+    pull() {
+        if (!this.isInitialized()) {
+            throw new Error('Git tracking is not initialized.');
+        }
+        const remote = this.config.remote;
+        if (!remote) {
+            throw new Error('No remote configured. Use `instar git remote <url>` to set one.');
+        }
+        // Re-validate remote at execution time
+        if (!GitStateManager.validateRemoteUrl(remote)) {
+            throw new Error(`Invalid remote URL: only https://, git@, and ssh:// schemes are allowed. Got: ${remote}`);
+        }
+        // Ensure remote is configured in git
+        try {
+            this.git('remote', 'get-url', 'origin');
+            this.git('remote', 'set-url', 'origin', remote);
+        }
+        catch {
+            // @silent-fallback-ok — remote URL set, try add instead
+            this.git('remote', 'add', 'origin', remote);
+        }
+        this.git('pull', 'origin', this.config.branch);
+    }
+    /**
+     * Get recent commit history.
+     */
+    log(limit = 20) {
+        if (!this.isInitialized())
+            return [];
+        try {
+            const output = this.git('log', `--max-count=${limit}`, '--format=%h|%s|%an|%aI');
+            return output.trim().split('\n').filter(Boolean).map(line => {
+                const [hash, message, author, date] = line.split('|');
+                return { hash, message, author, date };
+            });
+        }
+        catch {
+            // @silent-fallback-ok — async pane fallback
+            return [];
+        }
+    }
+    /**
+     * Get current git status.
+     */
+    status() {
+        if (!this.isInitialized()) {
+            return {
+                initialized: false,
+                branch: this.config.branch,
+                staged: 0,
+                modified: 0,
+                untracked: 0,
+                ahead: 0,
+                behind: 0,
+                remote: this.config.remote,
+            };
+        }
+        // Force git to re-stat all files (without this, git may miss
+        // modifications that happen in the same second as the last commit)
+        try {
+            this.git('update-index', '--refresh', '-q');
+        }
+        catch { /* ignore */ }
+        const porcelain = this.git('status', '--porcelain');
+        // Split into lines but preserve the 2-char status prefix (leading spaces are significant)
+        const lines = porcelain.split('\n').filter(line => line.length >= 2);
+        let staged = 0;
+        let modified = 0;
+        let untracked = 0;
+        for (const line of lines) {
+            const indexStatus = line[0];
+            const workStatus = line[1];
+            if (indexStatus === '?' && workStatus === '?') {
+                untracked++;
+            }
+            else {
+                if (indexStatus !== ' ' && indexStatus !== '?')
+                    staged++;
+                if (workStatus !== ' ' && workStatus !== '?')
+                    modified++;
+            }
+        }
+        // Get ahead/behind counts
+        let ahead = 0;
+        let behind = 0;
+        try {
+            const trackingBranch = this.git('rev-parse', '--abbrev-ref', '@{u}').trim();
+            if (trackingBranch) {
+                const aheadBehind = this.git('rev-list', '--left-right', '--count', `@{u}...HEAD`).trim();
+                const [behindStr, aheadStr] = aheadBehind.split(/\s+/);
+                behind = parseInt(behindStr, 10) || 0;
+                ahead = parseInt(aheadStr, 10) || 0;
+            }
+        }
+        catch {
+            // @silent-fallback-ok — no upstream configured
+        }
+        // Get current branch
+        let branch = this.config.branch;
+        try {
+            branch = this.git('rev-parse', '--abbrev-ref', 'HEAD').trim();
+        }
+        catch {
+            // @silent-fallback-ok — head detection fallback to config
+        }
+        return {
+            initialized: true,
+            branch,
+            staged,
+            modified,
+            untracked,
+            ahead,
+            behind,
+            remote: this.config.remote,
+        };
+    }
+    /**
+     * Set the remote URL (validates scheme).
+     */
+    setRemote(url) {
+        if (!GitStateManager.validateRemoteUrl(url)) {
+            throw new Error(`Invalid remote URL: only https://, git@, and ssh:// schemes are allowed. Got: ${url}`);
+        }
+        this.config.remote = url;
+        // If git is initialized, also update the git remote
+        if (this.isInitialized()) {
+            try {
+                this.git('remote', 'get-url', 'origin');
+                this.git('remote', 'set-url', 'origin', url);
+            }
+            catch {
+                this.git('remote', 'add', 'origin', url);
+            }
+        }
+    }
+    /**
+     * Get the current configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Execute a git command in the state directory.
+     */
+    git(...args) {
+        const opts = {
+            cwd: this.stateDir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        };
+        // Escape arguments for shell
+        const escaped = args.map(arg => {
+            // If argument contains spaces or special chars, quote it
+            if (/[^a-zA-Z0-9_\-=./:%@+]/.test(arg)) {
+                return `'${arg.replace(/'/g, "'\\''")}'`;
+            }
+            return arg;
+        });
+        return execSync(`git ${escaped.join(' ')}`, opts);
+    }
+}
+//# sourceMappingURL=GitStateManager.js.map

package/dist/core/GitStateManager.js.map

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

package/dist/core/GitSync.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Git-based state synchronization for multi-machine coordination.
+ *
+ * Handles:
+ * - Configuring git commit signing with machine Ed25519 keys
+ * - Commit signing verification on pull
+ * - Debounced auto-commit + push
+ * - Relationship merge with field-level resolution
+ * - Conflict resolution strategies
+ *
+ * Part of Phase 3 (state sync via git).
+ */
+import type { MachineIdentityManager } from './MachineIdentity.js';
+import type { SecurityLog } from './SecurityLog.js';
+import type { IntelligenceProvider } from './types.js';
+export interface GitSyncConfig {
+    /** Project directory (repo root). */
+    projectDir: string;
+    /** State directory (.instar). */
+    stateDir: string;
+    /** Machine identity manager. */
+    identityManager: MachineIdentityManager;
+    /** Security log. */
+    securityLog: SecurityLog;
+    /** This machine's ID. */
+    machineId: string;
+    /** Auto-push after commits (default: true). */
+    autoPush?: boolean;
+    /** Debounce interval in ms for auto-commit (default: 30000). */
+    debounceMs?: number;
+    /** Intelligence provider for LLM-based conflict resolution. */
+    intelligence?: IntelligenceProvider;
+}
+export interface SyncResult {
+    /** Whether changes were pulled. */
+    pulled: boolean;
+    /** Whether changes were pushed. */
+    pushed: boolean;
+    /** Number of commits pulled. */
+    commitsPulled: number;
+    /** Number of commits pushed. */
+    commitsPushed: number;
+    /** Rejected commits (unsigned or from revoked machines). */
+    rejectedCommits: string[];
+    /** Merge conflicts that need manual review. */
+    conflicts: string[];
+}
+export interface RelationshipRecord {
+    id: string;
+    name: string;
+    channels: Array<{
+        type: string;
+        identifier: string;
+    }>;
+    firstInteraction: string;
+    lastInteraction: string;
+    interactionCount: number;
+    themes: string[];
+    notes: string;
+    significance: number;
+    arcSummary: string;
+    recentInteractions: Array<{
+        timestamp: string;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+}
+export declare class GitSyncManager {
+    private projectDir;
+    private stateDir;
+    private identityManager;
+    private securityLog;
+    private machineId;
+    private autoPush;
+    private debounceMs;
+    private debounceTimer;
+    private pendingPaths;
+    private llmResolver;
+    private fileClassifier;
+    constructor(config: GitSyncConfig);
+    /**
+     * Check if the project directory is a git repository with at least one commit.
+     * Returns false if .git/ doesn't exist or if git rev-parse HEAD fails
+     * (e.g., empty repo with no commits) — prevents crashes when git sync
+     * is called on a standalone agent that hasn't opted into git backup.
+     */
+    isGitRepo(): boolean;
+    /**
+     * Set the intelligence provider for LLM-based conflict resolution.
+     * Can be called after construction when the provider becomes available.
+     */
+    setIntelligence(intelligence: IntelligenceProvider): void;
+    /**
+     * Configure git commit signing with this machine's Ed25519 key.
+     * Requires git >= 2.34 for SSH signing support.
+     */
+    configureCommitSigning(): void;
+    /**
+     * Check if commit signing is configured for this repo.
+     */
+    isSigningConfigured(): boolean;
+    /**
+     * Full sync: pull → verify → resolve → push.
+     */
+    sync(): Promise<SyncResult>;
+    /**
+     * Stage files and commit with machine signing.
+     */
+    commitAndPush(message: string, paths?: string[]): boolean;
+    /**
+     * Queue a file path for debounced auto-commit.
+     * After debounceMs, all pending paths are committed in one batch.
+     */
+    queueAutoCommit(filePath: string): void;
+    /**
+     * Immediately commit all pending paths.
+     */
+    flushAutoCommit(): void;
+    /**
+     * Stop debounce timer and flush pending commits.
+     */
+    stop(): void;
+    /**
+     * Verify pulled commits: check signatures against the machine registry.
+     * Returns commit hashes that should be rejected.
+     */
+    verifyPulledCommits(): string[];
+    /**
+     * Install git hooks for commit verification.
+     */
+    installVerificationHooks(): void;
+    /**
+     * Update the allowed-signers file from the machine registry.
+     * This maps machine IDs to their SSH public keys for git verification.
+     */
+    updateAllowedSigners(): void;
+    /**
+     * Detect files in conflict state.
+     */
+    private detectConflicts;
+    /**
+     * Attempt auto-resolution for known file types, then escalate to LLM.
+     *
+     * Resolution flow:
+     *   1. Try programmatic strategies (Tier 0) for each file
+     *   2. For remaining conflicts, try LLM resolution (Tier 1 → 2)
+     *   3. If LLM resolves: validate (build/test), rollback on failure
+     *   4. Any still-unresolved files: report as Tier 3 (human escalation)
+     */
+    private resolveConflicts;
+    /**
+     * Use LLM intelligence to resolve conflicts that programmatic strategies couldn't handle.
+     */
+    private resolveLLMConflicts;
+    /**
+     * Build a ConflictFile from a file path in conflict state.
+     */
+    private buildConflictFile;
+    /**
+     * Build escalation context for Tier 2 (commit messages, related files).
+     */
+    private buildEscalationContext;
+    /**
+     * Run post-merge validation (syntax check, build, tests).
+     * Returns true if validation passes.
+     */
+    private validatePostMerge;
+    /**
+     * Clean up old sync snapshot tags, keeping the most recent N.
+     */
+    private cleanupSnapshotTags;
+    /**
+     * Try to auto-resolve a specific file conflict.
+     */
+    private tryAutoResolve;
+    /**
+     * Resolve relationship file conflict using field-level merge.
+     */
+    private resolveRelationshipConflict;
+    /**
+     * Resolve conflict by taking the newer version (by embedded timestamp).
+     */
+    private resolveNewerWins;
+    /**
+     * Resolve conflict by taking the union of arrays by ID field.
+     */
+    private resolveUnionById;
+    private gitExec;
+    private gitConfig;
+    private gitConfigGet;
+    private gitHead;
+}
+/**
+ * Merge two relationship records using field-level resolution.
+ * From the spec: channels union, themes union, timestamps min/max,
+ * text fields from whichever has newer lastInteraction.
+ */
+export declare function mergeRelationship(ours: RelationshipRecord, theirs: RelationshipRecord): RelationshipRecord;
+//# sourceMappingURL=GitSync.d.ts.map

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

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