@eddacraft/anvil-runtime 0.1.0

package/dist/concurrency/atomic.js

@@ -0,0 +1,281 @@
+/**
+ * Atomic File Operations
+ *
+ * Provides atomic read/write operations for JSON files to prevent
+ * corruption in multi-agent/multi-process scenarios.
+ *
+ * Uses the atomic write pattern: write to temp file, then rename.
+ * This ensures that either the old or new content is visible, never partial.
+ */
+import { promises as fs } from 'node:fs';
+import { dirname, join, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { createDebugger } from '@eddacraft/anvil-core';
+const debug = createDebugger('atomic');
+/**
+ * Write JSON atomically
+ *
+ * 1. Write content to a temp file in the same directory
+ * 2. Rename temp file to target (atomic on most filesystems)
+ * 3. Clean up temp file on error
+ */
+export async function atomicWriteJson(filePath, data, options = {}) {
+    const { mode = 0o644, retries = 3, createDirs = true } = options;
+    const dir = dirname(filePath);
+    const tempPath = join(dir, `.${basename(filePath)}.${randomUUID().slice(0, 8)}.tmp`);
+    // Ensure directory exists
+    if (createDirs) {
+        await fs.mkdir(dir, { recursive: true });
+    }
+    const content = JSON.stringify(data, null, 2);
+    let lastError = null;
+    for (let attempt = 0; attempt < retries; attempt++) {
+        try {
+            // Write to temp file
+            await fs.writeFile(tempPath, content, { encoding: 'utf-8', mode });
+            // Atomic rename
+            await fs.rename(tempPath, filePath);
+            debug(`Atomic write successful: ${filePath}`);
+            return;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            debug(`Atomic write attempt ${attempt + 1} failed:`, error);
+            // Clean up temp file if it exists
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            // Small delay before retry
+            if (attempt < retries - 1) {
+                await sleep(10 * (attempt + 1));
+            }
+        }
+    }
+    throw new Error(`Atomic write failed after ${retries} attempts: ${lastError?.message}`);
+}
+/**
+ * Write text atomically
+ */
+export async function atomicWriteText(filePath, content, options = {}) {
+    const { mode = 0o644, retries = 3, createDirs = true } = options;
+    const dir = dirname(filePath);
+    const tempPath = join(dir, `.${basename(filePath)}.${randomUUID().slice(0, 8)}.tmp`);
+    if (createDirs) {
+        await fs.mkdir(dir, { recursive: true });
+    }
+    let lastError = null;
+    for (let attempt = 0; attempt < retries; attempt++) {
+        try {
+            await fs.writeFile(tempPath, content, { encoding: 'utf-8', mode });
+            await fs.rename(tempPath, filePath);
+            debug(`Atomic write successful: ${filePath}`);
+            return;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            debug(`Atomic write attempt ${attempt + 1} failed:`, error);
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Ignore
+            }
+            if (attempt < retries - 1) {
+                await sleep(10 * (attempt + 1));
+            }
+        }
+    }
+    throw new Error(`Atomic write failed after ${retries} attempts: ${lastError?.message}`);
+}
+/**
+ * Read JSON safely (returns null if file doesn't exist or is invalid)
+ */
+export async function readJsonSafe(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        debug(`Failed to read JSON from ${filePath}:`, error);
+        return null;
+    }
+}
+/**
+ * Read JSON with retries (for handling transient lock conflicts)
+ */
+export async function readJsonWithRetry(filePath, retries = 3, delayMs = 10) {
+    let lastError = null;
+    for (let attempt = 0; attempt < retries; attempt++) {
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            debug(`Read attempt ${attempt + 1} failed for ${filePath}:`, error);
+            if (attempt < retries - 1) {
+                await sleep(delayMs * (attempt + 1));
+            }
+        }
+    }
+    debug(`Read failed after ${retries} attempts: ${lastError?.message}`);
+    return null;
+}
+/**
+ * Acquire a file lock (blocks until acquired or timeout)
+ */
+export async function acquireFileLock(lockPath, options = {}) {
+    const { timeout = 5000, retryInterval = 50, content = '' } = options;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        try {
+            // O_EXCL: fail if file exists
+            const fd = await fs.open(lockPath, 'wx');
+            await fd.writeFile(content);
+            await fd.close();
+            debug(`Lock acquired: ${lockPath}`);
+            return {
+                path: lockPath,
+                release: async () => {
+                    try {
+                        await fs.unlink(lockPath);
+                        debug(`Lock released: ${lockPath}`);
+                    }
+                    catch (error) {
+                        debug(`Lock release failed: ${lockPath}`, error);
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                // Unexpected error
+                throw error;
+            }
+            // Lock exists, wait and retry
+            await sleep(retryInterval);
+        }
+    }
+    debug(`Lock acquisition timed out: ${lockPath}`);
+    return null;
+}
+/**
+ * Try to acquire a file lock (non-blocking)
+ */
+export async function tryAcquireFileLock(lockPath, content = '') {
+    try {
+        const dir = dirname(lockPath);
+        await fs.mkdir(dir, { recursive: true });
+        const fd = await fs.open(lockPath, 'wx');
+        await fd.writeFile(content);
+        await fd.close();
+        debug(`Lock acquired: ${lockPath}`);
+        return {
+            path: lockPath,
+            release: async () => {
+                try {
+                    await fs.unlink(lockPath);
+                    debug(`Lock released: ${lockPath}`);
+                }
+                catch (error) {
+                    debug(`Lock release failed: ${lockPath}`, error);
+                }
+            },
+        };
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Check if a lock file exists
+ */
+export async function isLocked(lockPath) {
+    try {
+        await fs.access(lockPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Force release a lock (use with caution)
+ */
+export async function forceReleaseLock(lockPath) {
+    try {
+        await fs.unlink(lockPath);
+        debug(`Lock force-released: ${lockPath}`);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Delete file if it exists (no error if missing)
+ */
+export async function unlinkSafe(filePath) {
+    try {
+        await fs.unlink(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Check if file exists
+ */
+export async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get file modification time
+ */
+export async function getFileMtime(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        return stats.mtime;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Simple sleep utility
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Sleep with jitter (to prevent thundering herd)
+ */
+export function sleepWithJitter(baseMs, jitterPercent = 0.2) {
+    const jitter = baseMs * jitterPercent * (Math.random() * 2 - 1);
+    return sleep(Math.max(0, baseMs + jitter));
+}

package/dist/concurrency/git-agent.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Git Agent Identification
+ *
+ * Utilities for identifying agents via git commit metadata.
+ * Supports reading and writing agent identification through commit trailers.
+ */
+import type { AgentType, AgentInfo } from './types.js';
+/**
+ * Git trailer keys used for agent identification
+ */
+export declare const GIT_TRAILERS: {
+    /** Agent ID trailer */
+    readonly AGENT_ID: "Anvil-Agent-ID";
+    /** Agent type trailer */
+    readonly AGENT_TYPE: "Anvil-Agent-Type";
+    /** Session ID trailer */
+    readonly SESSION_ID: "Anvil-Session-ID";
+    /** Agent name trailer */
+    readonly AGENT_NAME: "Anvil-Agent-Name";
+    /** Co-authored-by for agent attribution */
+    readonly CO_AUTHORED_BY: "Co-authored-by";
+};
+/**
+ * Agent info extracted from a commit
+ */
+export interface CommitAgentInfo {
+    /** Agent ID from trailer */
+    agentId?: string;
+    /** Agent type from trailer */
+    agentType?: AgentType;
+    /** Session ID from trailer */
+    sessionId?: string;
+    /** Agent name from trailer */
+    agentName?: string;
+    /** Whether commit was made by an AI agent */
+    isAiGenerated: boolean;
+    /** Co-authors (may include AI attribution) */
+    coAuthors: string[];
+    /** Raw trailers from commit */
+    trailers: Record<string, string>;
+}
+/**
+ * Parse trailers from commit message
+ */
+export declare function parseCommitTrailers(commitMessage: string): Record<string, string>;
+/**
+ * Extract agent info from commit trailers
+ */
+export declare function extractAgentInfo(trailers: Record<string, string>): CommitAgentInfo;
+/**
+ * Get agent info from a specific commit
+ */
+export declare function getCommitAgentInfo(commitRef: string, cwd?: string): CommitAgentInfo | null;
+/**
+ * Get agent info from recent commits
+ */
+export declare function getRecentCommitsAgentInfo(count?: number, cwd?: string): Array<{
+    hash: string;
+    info: CommitAgentInfo;
+}>;
+/**
+ * Options for formatting a commit message with agent info
+ */
+export interface FormatCommitOptions {
+    /** Original commit message */
+    message: string;
+    /** Agent info (auto-detected if not provided) */
+    agent?: AgentInfo;
+    /** Include co-authored-by trailer */
+    includeCoAuthor?: boolean;
+    /** Additional trailers to include */
+    additionalTrailers?: Record<string, string>;
+}
+/**
+ * Format a commit message with agent identification trailers
+ */
+export declare function formatCommitWithAgent(options: FormatCommitOptions): string;
+/**
+ * Prepare commit message hook helper
+ *
+ * Automatically adds agent trailers to commit messages.
+ * Can be used in a prepare-commit-msg hook.
+ */
+export declare function prepareCommitMsgHook(commitMsgFile: string, commitSource?: string, _sha1?: string): void;
+/**
+ * Generate a git config command to set up the prepare-commit-msg hook
+ */
+export declare function getHookSetupCommand(): string;
+/**
+ * Summary of agent contributions
+ */
+export interface AgentContributionSummary {
+    /** Agent ID */
+    agentId: string;
+    /** Agent type */
+    agentType: AgentType;
+    /** Number of commits */
+    commitCount: number;
+    /** First commit timestamp */
+    firstCommit: string;
+    /** Last commit timestamp */
+    lastCommit: string;
+    /** Files touched (if available) */
+    filesTouched?: number;
+}
+/**
+ * Get contribution summary by agent
+ */
+export declare function getAgentContributions(sinceRef?: string, cwd?: string): Map<string, AgentContributionSummary>;
+/**
+ * Get percentage of AI-generated commits in a range
+ */
+export declare function getAiCommitPercentage(sinceRef?: string, cwd?: string): number;
+//# sourceMappingURL=git-agent.d.ts.map

package/dist/concurrency/git-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-agent.d.ts","sourceRoot":"","sources":["../../src/concurrency/git-agent.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AASvD;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB,uBAAuB;;IAGvB,yBAAyB;;IAGzB,yBAAyB;;IAGzB,yBAAyB;;IAGzB,2CAA2C;;CAEnC,CAAC;AAMX;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,6CAA6C;IAC7C,aAAa,EAAE,OAAO,CAAC;IAEvB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyBjF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,eAAe,CAmClF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAc1F;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,GAAE,MAAW,EAClB,GAAG,CAAC,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,CAuBhD;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAEhB,iDAAiD;IACjD,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB,qCAAqC;IACrC,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,qCAAqC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAgD1E;AA4BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,MAAM,EACrB,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CA6BN;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAiB5C;AAMD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAEhB,iBAAiB;IACjB,SAAS,EAAE,SAAS,CAAC;IAErB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IAEpB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IAEpB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IAEnB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,CAAC,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,MAAM,GACX,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAiDvC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAwB7E"}