@ttfw/envoi 1.0.0

package/dist/lib/judge.js

@@ -0,0 +1,501 @@
+/**
+ * Judge phase: Compute touched files from git diff.
+ *
+ * Provides functions to analyze git changes and categorize files
+ * for scope guardrail enforcement.
+ */
+import { execSync } from 'node:child_process';
+import micromatch from 'micromatch';
+/**
+ * Parses git diff --name-status output into categorized file lists.
+ *
+ * Git diff --name-status format:
+ * - M <path> - Modified
+ * - A <path> - Added
+ * - D <path> - Deleted
+ * - R<score> <old> <new> - Renamed (tab-separated, e.g., R100\told\tnew)
+ *
+ * This is a pure function that can be easily tested.
+ *
+ * @param output - Raw output from `git diff --name-status <base>...HEAD`
+ * @returns Object with categorized file lists
+ *
+ * @example
+ * ```typescript
+ * const diffOutput = 'M\tfile1.ts\nA\tfile2.ts\nR100\told.ts\tnew.ts\n';
+ * const result = parseGitDiffNameStatus(diffOutput);
+ * // result.modified = ['file1.ts']
+ * // result.added = ['file2.ts']
+ * // result.renamed = [{ from: 'old.ts', to: 'new.ts' }]
+ * ```
+ */
+export function parseGitDiffNameStatus(output) {
+    const modified = [];
+    const added = [];
+    const deleted = [];
+    const renamed = [];
+    const trimmed = output.trim();
+    if (trimmed === '') {
+        return { modified, added, deleted, renamed };
+    }
+    const lines = trimmed.split('\n').filter((line) => line.length > 0);
+    for (const line of lines) {
+        // Handle renamed files: R<score>\t<old>\t<new>
+        // The similarity score can be 0-100, so we check if line starts with R
+        if (line.startsWith('R')) {
+            // Split by tab to get: [R<score>, old, new]
+            const parts = line.split('\t');
+            if (parts.length >= 3) {
+                const from = parts[1];
+                const to = parts[2];
+                renamed.push({ from, to });
+            }
+            continue;
+        }
+        // For other status codes, format is: <code>\t<path>
+        const parts = line.split('\t');
+        if (parts.length < 2) {
+            continue;
+        }
+        const status = parts[0];
+        const path = parts[1];
+        switch (status) {
+            case 'M':
+                modified.push(path);
+                break;
+            case 'A':
+                added.push(path);
+                break;
+            case 'D':
+                deleted.push(path);
+                break;
+            // Ignore other status codes (C for copy, etc.)
+        }
+    }
+    return { modified, added, deleted, renamed };
+}
+/**
+ * Gets all files touched since a base commit using git diff --name-status
+ * and git status --porcelain.
+ *
+ * Combines:
+ * - Tracked file changes (modified, added, deleted, renamed) from git diff
+ * - Untracked files from git status
+ *
+ * @param baseCommit - The base commit SHA to diff against (e.g., 'main' or commit hash)
+ * @returns TouchedFiles object with categorized file lists
+ * @throws {Error} If git commands fail
+ *
+ * @example
+ * ```typescript
+ * const touched = getTouchedFiles('main');
+ * console.log(`Modified: ${touched.modified.length}`);
+ * console.log(`All files: ${touched.all.join(', ')}`);
+ * ```
+ */
+export function getTouchedFiles(baseCommit) {
+    // Get tracked file changes from git diff
+    let diffStatus;
+    try {
+        const diffOutput = execSync(`git diff --name-status ${baseCommit}...HEAD`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        diffStatus = parseGitDiffNameStatus(diffOutput);
+    }
+    catch (error) {
+        throw new Error(`Failed to get git diff from ${baseCommit}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Get untracked files from git status
+    let untracked = [];
+    try {
+        const statusOutput = execSync('git status --porcelain', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Untracked files have ?? prefix
+        untracked = statusOutput
+            .trim()
+            .split('\n')
+            .filter((line) => line.startsWith('??'))
+            .map((line) => line.substring(3).trim()); // Remove "?? " prefix
+    }
+    catch (error) {
+        // If git status fails, continue without untracked files
+        // (this is less critical than diff failure)
+    }
+    // Compute union of all file paths (excluding deleted files)
+    const all = [
+        ...diffStatus.modified,
+        ...diffStatus.added,
+        ...diffStatus.renamed.map((r) => r.to),
+        ...untracked,
+    ];
+    return {
+        modified: diffStatus.modified,
+        added: diffStatus.added,
+        deleted: diffStatus.deleted,
+        renamed: diffStatus.renamed,
+        untracked,
+        all,
+    };
+}
+/**
+ * Checks if a path matches any of the given glob patterns.
+ *
+ * @param path - The file path to check
+ * @param patterns - Array of glob patterns to match against
+ * @returns True if path matches any pattern, false otherwise
+ */
+function matchesGlob(path, patterns) {
+    if (patterns.length === 0) {
+        return false;
+    }
+    return micromatch.isMatch(path, patterns);
+}
+/**
+ * Checks if a path is a lockfile based on scopeConfig.lockfiles list.
+ *
+ * @param path - The file path to check
+ * @param lockfiles - Array of lockfile names/patterns
+ * @returns True if path matches any lockfile pattern
+ */
+function isLockfile(path, lockfiles) {
+    if (lockfiles.length === 0) {
+        return false;
+    }
+    // Check if path ends with any lockfile name, or matches lockfile globs
+    return lockfiles.some((lockfile) => {
+        // If lockfile is a simple name (e.g., "package-lock.json"), check if path ends with it
+        if (!lockfile.includes('/') && !lockfile.includes('*')) {
+            return path.endsWith(lockfile);
+        }
+        // Otherwise, treat as glob pattern
+        return micromatch.isMatch(path, [lockfile]);
+    });
+}
+/**
+ * Checks touched files against scope rules and returns first violation or success.
+ *
+ * Checks are performed in priority order:
+ * 1. Runner-owned mutation (highest priority)
+ * 2. Forbidden globs
+ * 3. Outside allowed globs
+ * 4. New file when not allowed
+ * 5. Lockfile change when not allowed
+ *
+ * Returns the first violation found, or success if no violations.
+ *
+ * @param touched - TouchedFiles object with categorized file lists
+ * @param taskScope - Task scope configuration with allowed/forbidden globs and permissions
+ * @param scopeConfig - Scope configuration with lockfiles list
+ * @param runnerOwnedGlobs - Glob patterns for files owned by the runner
+ * @returns ScopeCheckResult with stopCode and violatingFiles
+ *
+ * @example
+ * ```typescript
+ * const result = checkScopeViolations(
+ *   { modified: ['src/utils.ts'], added: ['src/new.ts'], deleted: [], renamed: [], untracked: ['src/new.ts'], all: ['src/utils.ts', 'src/new.ts'] },
+ *   { allowed_globs: ['src/**'], forbidden_globs: ['*.key'], allow_new_files: false, allow_lockfile_changes: true },
+ *   { lockfiles: ['package-lock.json'], default_allowed_globs: [], default_forbidden_globs: [], default_allow_new_files: true, default_allow_lockfile_changes: false },
+ *   ['pilot/**']
+ * );
+ * if (!result.ok) {
+ *   console.error(`Violation: ${result.stopCode}`, result.violatingFiles);
+ * }
+ * ```
+ */
+export function checkScopeViolations(touched, taskScope, scopeConfig, runnerOwnedGlobs) {
+    // Get all touched paths (excluding deleted files)
+    const allPaths = touched.all;
+    const untrackedSet = new Set(touched.untracked);
+    const newFilesSet = new Set([...touched.added, ...touched.untracked, ...touched.renamed.map((r) => r.to)]);
+    // Check 1: Runner-owned mutation (highest priority)
+    const runnerOwnedViolations = [];
+    for (const path of allPaths) {
+        if (matchesGlob(path, runnerOwnedGlobs)) {
+            runnerOwnedViolations.push(path);
+        }
+    }
+    if (runnerOwnedViolations.length > 0) {
+        return {
+            ok: false,
+            stopCode: 'STOP_RUNNER_OWNED_MUTATION',
+            violatingFiles: runnerOwnedViolations,
+            reason: `Files match runner-owned globs: ${runnerOwnedViolations.join(', ')}`,
+        };
+    }
+    // Check 2: Forbidden globs
+    const forbiddenViolations = [];
+    for (const path of allPaths) {
+        if (matchesGlob(path, taskScope.forbidden_globs)) {
+            forbiddenViolations.push(path);
+        }
+    }
+    if (forbiddenViolations.length > 0) {
+        return {
+            ok: false,
+            stopCode: 'STOP_SCOPE_VIOLATION_FORBIDDEN',
+            violatingFiles: forbiddenViolations,
+            reason: `Files match forbidden glob patterns: ${forbiddenViolations.join(', ')}`,
+        };
+    }
+    // Check 3: Outside allowed globs
+    if (taskScope.allowed_globs.length > 0) {
+        const outsideAllowedViolations = [];
+        for (const path of allPaths) {
+            if (!matchesGlob(path, taskScope.allowed_globs)) {
+                outsideAllowedViolations.push(path);
+            }
+        }
+        if (outsideAllowedViolations.length > 0) {
+            return {
+                ok: false,
+                stopCode: 'STOP_SCOPE_VIOLATION_OUTSIDE_ALLOWED',
+                violatingFiles: outsideAllowedViolations,
+                reason: `Files do not match any allowed glob pattern: ${outsideAllowedViolations.join(', ')}`,
+            };
+        }
+    }
+    // Check 4: New file when not allowed
+    if (!taskScope.allow_new_files) {
+        const newFileViolations = [];
+        for (const path of allPaths) {
+            if (newFilesSet.has(path)) {
+                newFileViolations.push(path);
+            }
+        }
+        if (newFileViolations.length > 0) {
+            return {
+                ok: false,
+                stopCode: 'STOP_SCOPE_VIOLATION_NEW_FILE',
+                violatingFiles: newFileViolations,
+                reason: `New files created but allow_new_files is false: ${newFileViolations.join(', ')}`,
+            };
+        }
+    }
+    // Check 5: Lockfile change when not allowed
+    if (!taskScope.allow_lockfile_changes) {
+        const lockfileViolations = [];
+        for (const path of allPaths) {
+            if (isLockfile(path, scopeConfig.lockfiles)) {
+                lockfileViolations.push(path);
+            }
+        }
+        if (lockfileViolations.length > 0) {
+            return {
+                ok: false,
+                stopCode: 'STOP_LOCKFILE_CHANGE_FORBIDDEN',
+                violatingFiles: lockfileViolations,
+                reason: `Lockfiles modified but allow_lockfile_changes is false: ${lockfileViolations.join(', ')}`,
+            };
+        }
+    }
+    // No violations found
+    return {
+        ok: true,
+        stopCode: null,
+        violatingFiles: [],
+        reason: null,
+    };
+}
+/**
+ * Parses git diff --stat output to extract line counts.
+ *
+ * Git diff --stat format:
+ * - Individual file lines: " file.ts | N +++++" or " file.ts | N +++---"
+ * - Summary line: "N files changed, M insertions(+), K deletions(-)"
+ *
+ * This function extracts the summary line totals.
+ *
+ * @param output - Raw output from `git diff --stat <base>...HEAD`
+ * @returns Object with linesAdded and linesDeleted totals
+ *
+ * @example
+ * ```typescript
+ * const diffStat = ' file1.ts | 5 +++++\n file2.ts | 3 ---\n 2 files changed, 5 insertions(+), 3 deletions(-)';
+ * const result = parseGitDiffStat(diffStat);
+ * // result.linesAdded = 5
+ * // result.linesDeleted = 3
+ * ```
+ */
+export function parseGitDiffStat(output) {
+    const trimmed = output.trim();
+    if (trimmed === '') {
+        return { linesAdded: 0, linesDeleted: 0 };
+    }
+    const lines = trimmed.split('\n');
+    // The summary line is typically the last line
+    // Format: "N files changed, M insertions(+), K deletions(-)"
+    const summaryLine = lines[lines.length - 1];
+    // Match pattern: "N files changed, M insertions(+), K deletions(-)"
+    // Or: "N files changed, M insertions(+)" (no deletions)
+    // Or: "N files changed, K deletions(-)" (no insertions)
+    const filesChangedMatch = summaryLine.match(/(\d+)\s+files?\s+changed/);
+    if (!filesChangedMatch) {
+        // If no summary line found, return zeros
+        return { linesAdded: 0, linesDeleted: 0 };
+    }
+    // Extract insertions
+    const insertionsMatch = summaryLine.match(/(\d+)\s+insertions?\(\+\)/);
+    const linesAdded = insertionsMatch ? parseInt(insertionsMatch[1], 10) : 0;
+    // Extract deletions
+    const deletionsMatch = summaryLine.match(/(\d+)\s+deletions?\(-\)/);
+    const linesDeleted = deletionsMatch ? parseInt(deletionsMatch[1], 10) : 0;
+    return { linesAdded, linesDeleted };
+}
+/**
+ * Computes blast radius metrics from git diff.
+ *
+ * Uses git diff --stat to get line counts and TouchedFiles to get file counts.
+ *
+ * @param baseCommit - The base commit SHA to diff against (e.g., 'main' or commit hash)
+ * @param touched - TouchedFiles object with categorized file lists
+ * @returns BlastRadius object with file and line counts
+ * @throws {Error} If git diff --stat command fails
+ *
+ * @example
+ * ```typescript
+ * const touched = getTouchedFiles('main');
+ * const blastRadius = computeBlastRadius('main', touched);
+ * console.log(`Files touched: ${blastRadius.files_touched}`);
+ * console.log(`Lines added: ${blastRadius.lines_added}`);
+ * ```
+ */
+export function computeBlastRadius(baseCommit, touched) {
+    // Get line counts from git diff --stat
+    let linesAdded = 0;
+    let linesDeleted = 0;
+    try {
+        const diffStatOutput = execSync(`git diff --stat ${baseCommit}...HEAD`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const parsed = parseGitDiffStat(diffStatOutput);
+        linesAdded = parsed.linesAdded;
+        linesDeleted = parsed.linesDeleted;
+    }
+    catch (error) {
+        throw new Error(`Failed to get git diff --stat from ${baseCommit}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Compute file counts from TouchedFiles
+    // files_touched = all unique files (modified + added + renamed.to + untracked)
+    const filesTouched = touched.all.length;
+    // new_files_count = added + untracked + renamed.to
+    const newFilesSet = new Set([
+        ...touched.added,
+        ...touched.untracked,
+        ...touched.renamed.map((r) => r.to),
+    ]);
+    const newFilesCount = newFilesSet.size;
+    return {
+        files_touched: filesTouched,
+        lines_added: linesAdded,
+        lines_deleted: linesDeleted,
+        new_files: newFilesCount,
+    };
+}
+/**
+ * Checks blast radius against configured diff limits.
+ *
+ * Returns STOP_DIFF_TOO_LARGE if either limit is exceeded:
+ * - files_touched > max_files_touched
+ * - lines_changed (added + deleted) > max_lines_changed
+ *
+ * @param blastRadius - Blast radius metrics from computeBlastRadius
+ * @param limits - Diff limits configuration
+ * @returns DiffCheckResult with ok status and stopCode
+ *
+ * @example
+ * ```typescript
+ * const blastRadius = computeBlastRadius('main', touched);
+ * const result = checkDiffLimits(blastRadius, { max_files_touched: 10, max_lines_changed: 100 });
+ * if (!result.ok) {
+ *   console.error(`Violation: ${result.stopCode}`, result.reason);
+ * }
+ * ```
+ */
+export function checkDiffLimits(blastRadius, limits) {
+    const linesChanged = blastRadius.lines_added + blastRadius.lines_deleted;
+    const violations = [];
+    if (blastRadius.files_touched > limits.max_files_touched) {
+        violations.push(`files_touched (${blastRadius.files_touched}) exceeds max_files_touched (${limits.max_files_touched})`);
+    }
+    if (linesChanged > limits.max_lines_changed) {
+        violations.push(`lines_changed (${linesChanged}) exceeds max_lines_changed (${limits.max_lines_changed})`);
+    }
+    if (violations.length > 0) {
+        return {
+            ok: false,
+            stopCode: 'STOP_DIFF_TOO_LARGE',
+            blastRadius,
+            reason: violations.join('; '),
+        };
+    }
+    return {
+        ok: true,
+        stopCode: null,
+        blastRadius,
+        reason: null,
+    };
+}
+/**
+ * Checks if HEAD is still at the expected commit (or a descendant of it).
+ *
+ * - If HEAD === expectedBaseCommit → ok (no changes yet).
+ * - If expectedBaseCommit is ancestor of HEAD → ok (builder made commits).
+ * - Otherwise → HEAD was moved externally (force push, external commit, branch switch) → STOP_HEAD_MOVED.
+ *
+ * @param expectedBaseCommit - The base commit SHA stored at tick start
+ * @returns HeadCheckResult with ok, stopCode, expectedHead, actualHead, reason
+ */
+export function checkHeadMoved(expectedBaseCommit) {
+    let actualHead;
+    try {
+        actualHead = execSync('git rev-parse HEAD', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stopCode: 'STOP_HEAD_MOVED',
+            expectedHead: expectedBaseCommit,
+            actualHead: '',
+            reason: `Failed to get current HEAD: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (actualHead === expectedBaseCommit) {
+        return {
+            ok: true,
+            stopCode: null,
+            expectedHead: expectedBaseCommit,
+            actualHead,
+            reason: null,
+        };
+    }
+    try {
+        execSync(`git merge-base --is-ancestor ${expectedBaseCommit} HEAD`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return {
+            ok: true,
+            stopCode: null,
+            expectedHead: expectedBaseCommit,
+            actualHead,
+            reason: null,
+        };
+    }
+    catch {
+        return {
+            ok: false,
+            stopCode: 'STOP_HEAD_MOVED',
+            expectedHead: expectedBaseCommit,
+            actualHead,
+            reason: `HEAD moved externally: expected ${expectedBaseCommit}, got ${actualHead}`,
+        };
+    }
+}
+//# sourceMappingURL=judge.js.map

package/dist/lib/judge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge.js","sourceRoot":"","sources":["../../src/lib/judge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,UAAU,MAAM,YAAY,CAAC;AAkCpC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACnD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAwC,EAAE,CAAC;IAExD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAEpE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,+CAA+C;QAC/C,uEAAuE;QACvE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,4CAA4C;YAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACtB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACpB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;YAC7B,CAAC;YACD,SAAS;QACX,CAAC;QAED,oDAAoD;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAEtB,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,GAAG;gBACN,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACpB,MAAM;YACR,KAAK,GAAG;gBACN,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACjB,MAAM;YACR,KAAK,GAAG;gBACN,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACnB,MAAM;YACR,+CAA+C;QACjD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,yCAAyC;IACzC,IAAI,UAA4B,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,QAAQ,CAAC,0BAA0B,UAAU,SAAS,EAAE;YACzE,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC;QACH,UAAU,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,+BAA+B,UAAU,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACvG,CAAC;IACJ,CAAC;IAED,sCAAsC;IACtC,IAAI,SAAS,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,QAAQ,CAAC,wBAAwB,EAAE;YACtD,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC;QACH,iCAAiC;QACjC,SAAS,GAAG,YAAY;aACrB,IAAI,EAAE;aACN,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;aACvC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,sBAAsB;IACpE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,wDAAwD;QACxD,4CAA4C;IAC9C,CAAC;IAED,4DAA4D;IAC5D,MAAM,GAAG,GAAa;QACpB,GAAG,UAAU,CAAC,QAAQ;QACtB,GAAG,UAAU,CAAC,KAAK;QACnB,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,GAAG,SAAS;KACb,CAAC;IAEF,OAAO;QACL,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,SAAS;QACT,GAAG;KACJ,CAAC;AACJ,CAAC;AAgBD;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,IAAY,EAAE,QAAkB;IACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,SAAS,UAAU,CAAC,IAAY,EAAE,SAAmB;IACnD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,uEAAuE;IACvE,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE;QACjC,uFAAuF;QACvF,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACvD,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;QACD,mCAAmC;QACnC,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAqB,EACrB,SAAoB,EACpB,WAAwB,EACxB,gBAA0B;IAE1B,kDAAkD;IAClD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAC7B,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAE3G,oDAAoD;IACpD,MAAM,qBAAqB,GAAa,EAAE,CAAC;IAC3C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,WAAW,CAAC,IAAI,EAAE,gBAAgB,CAAC,EAAE,CAAC;YACxC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IACD,IAAI,qBAAqB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE,4BAA4B;YACtC,cAAc,EAAE,qBAAqB;YACrC,MAAM,EAAE,mCAAmC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;SAC9E,CAAC;IACJ,CAAC;IAED,2BAA2B;IAC3B,MAAM,mBAAmB,GAAa,EAAE,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,CAAC;YACjD,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IACD,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE,gCAAgC;YAC1C,cAAc,EAAE,mBAAmB;YACnC,MAAM,EAAE,wCAAwC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;SACjF,CAAC;IACJ,CAAC;IAED,iCAAiC;IACjC,IAAI,SAAS,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvC,MAAM,wBAAwB,GAAa,EAAE,CAAC;QAC9C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC5B,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,aAAa,CAAC,EAAE,CAAC;gBAChD,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;QACD,IAAI,wBAAwB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,QAAQ,EAAE,sCAAsC;gBAChD,cAAc,EAAE,wBAAwB;gBACxC,MAAM,EAAE,gDAAgD,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;aAC9F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,qCAAqC;IACrC,IAAI,CAAC,SAAS,CAAC,eAAe,EAAE,CAAC;QAC/B,MAAM,iBAAiB,GAAa,EAAE,CAAC;QACvC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC5B,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1B,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,QAAQ,EAAE,+BAA+B;gBACzC,cAAc,EAAE,iBAAiB;gBACjC,MAAM,EAAE,mDAAmD,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;aAC1F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,4CAA4C;IAC5C,IAAI,CAAC,SAAS,CAAC,sBAAsB,EAAE,CAAC;QACtC,MAAM,kBAAkB,GAAa,EAAE,CAAC;QACxC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC5B,IAAI,UAAU,CAAC,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC5C,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;QACD,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,QAAQ,EAAE,gCAAgC;gBAC1C,cAAc,EAAE,kBAAkB;gBAClC,MAAM,EAAE,2DAA2D,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;aACnG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,OAAO;QACL,EAAE,EAAE,IAAI;QACR,QAAQ,EAAE,IAAI;QACd,cAAc,EAAE,EAAE;QAClB,MAAM,EAAE,IAAI;KACb,CAAC;AACJ,CAAC;AAgBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,8CAA8C;IAC9C,6DAA6D;IAC7D,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE5C,oEAAoE;IACpE,wDAAwD;IACxD,wDAAwD;IACxD,MAAM,iBAAiB,GAAG,WAAW,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IACxE,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,yCAAyC;QACzC,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAC5C,CAAC;IAED,qBAAqB;IACrB,MAAM,eAAe,GAAG,WAAW,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACvE,MAAM,UAAU,GAAG,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1E,oBAAoB;IACpB,MAAM,cAAc,GAAG,WAAW,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACpE,MAAM,YAAY,GAAG,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAkB,EAAE,OAAqB;IAC1E,uCAAuC;IACvC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,QAAQ,CAAC,mBAAmB,UAAU,SAAS,EAAE;YACtE,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,gBAAgB,CAAC,cAAc,CAAC,CAAC;QAChD,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QAC/B,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,sCAAsC,UAAU,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC9G,CAAC;IACJ,CAAC;IAED,wCAAwC;IACxC,+EAA+E;IAC/E,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;IAExC,mDAAmD;IACnD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;QAC1B,GAAG,OAAO,CAAC,KAAK;QAChB,GAAG,OAAO,CAAC,SAAS;QACpB,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpC,CAAC,CAAC;IACH,MAAM,aAAa,GAAG,WAAW,CAAC,IAAI,CAAC;IAEvC,OAAO;QACL,aAAa,EAAE,YAAY;QAC3B,WAAW,EAAE,UAAU;QACvB,aAAa,EAAE,YAAY;QAC3B,SAAS,EAAE,aAAa;KACzB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,eAAe,CAAC,WAAwB,EAAE,MAAkB;IAC1E,MAAM,YAAY,GAAG,WAAW,CAAC,WAAW,GAAG,WAAW,CAAC,aAAa,CAAC;IACzE,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,IAAI,WAAW,CAAC,aAAa,GAAG,MAAM,CAAC,iBAAiB,EAAE,CAAC;QACzD,UAAU,CAAC,IAAI,CACb,kBAAkB,WAAW,CAAC,aAAa,gCAAgC,MAAM,CAAC,iBAAiB,GAAG,CACvG,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,GAAG,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAC5C,UAAU,CAAC,IAAI,CACb,kBAAkB,YAAY,gCAAgC,MAAM,CAAC,iBAAiB,GAAG,CAC1F,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE,qBAAqB;YAC/B,WAAW;YACX,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;SAC9B,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,QAAQ,EAAE,IAAI;QACd,WAAW;QACX,MAAM,EAAE,IAAI;KACb,CAAC;AACJ,CAAC;AAmBD;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,kBAA0B;IACvD,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,QAAQ,CAAC,oBAAoB,EAAE;YAC1C,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE,iBAAiB;YAC3B,YAAY,EAAE,kBAAkB;YAChC,UAAU,EAAE,EAAE;YACd,MAAM,EAAE,+BAA+B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;SAChG,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,KAAK,kBAAkB,EAAE,CAAC;QACtC,OAAO;YACL,EAAE,EAAE,IAAI;YACR,QAAQ,EAAE,IAAI;YACd,YAAY,EAAE,kBAAkB;YAChC,UAAU;YACV,MAAM,EAAE,IAAI;SACb,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,QAAQ,CAAC,gCAAgC,kBAAkB,OAAO,EAAE;YAClE,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC;QACH,OAAO;YACL,EAAE,EAAE,IAAI;YACR,QAAQ,EAAE,IAAI;YACd,YAAY,EAAE,kBAAkB;YAChC,UAAU;YACV,MAAM,EAAE,IAAI;SACb,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE,iBAAiB;YAC3B,YAAY,EAAE,kBAAkB;YAChC,UAAU;YACV,MAAM,EAAE,mCAAmC,kBAAkB,SAAS,UAAU,EAAE;SACnF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/lib/lock.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Lock mechanism for preventing concurrent envoi runs.
+ *
+ * Implements crash-safe lock acquisition with boot_id tracking to enable
+ * safe reclaim of stale locks after crashes or reboots.
+ */
+import type { LockInfo } from '../types/lock.js';
+/**
+ * Error thrown when a lock is already held by another process.
+ */
+export declare class LockHeldError extends Error {
+    readonly lockPath: string;
+    readonly holder: LockInfo;
+    constructor(message: string, lockPath: string, holder: LockInfo);
+}
+/**
+ * Error thrown when a lock file is corrupt or malformed.
+ */
+export declare class LockCorruptError extends Error {
+    readonly lockPath: string;
+    constructor(message: string, lockPath: string);
+}
+/**
+ * Gets a unique identifier for the current boot session.
+ *
+ * On Linux, reads /proc/sys/kernel/random/boot_id.
+ * On macOS, uses system uptime + hostname as a fingerprint since macOS
+ * doesn't have boot_id but uptime.boot_time is stable per boot.
+ *
+ * The result is cached for the lifetime of the process.
+ *
+ * @returns A string uniquely identifying the current boot session
+ */
+export declare function getBootId(): string;
+/**
+ * Checks if a process with the given PID is currently running.
+ *
+ * Uses process.kill(pid, 0) which checks for process existence
+ * without actually sending a signal.
+ *
+ * @param pid - The process ID to check
+ * @returns true if the process is running, false otherwise
+ */
+export declare function isPidRunning(pid: number): boolean;
+/**
+ * Determines if a lock is stale and can be reclaimed.
+ *
+ * A lock is considered stale if:
+ * - The holding process is no longer running, OR
+ * - The boot_id differs from the current boot (system has rebooted)
+ *
+ * @param lock - The lock information to check
+ * @returns true if the lock is stale and can be reclaimed
+ */
+export declare function isLockStale(lock: LockInfo): boolean;
+/**
+ * Acquires a lock by creating a lock file atomically.
+ *
+ * If a lock already exists:
+ * - If stale (process dead or different boot), reclaims it with a warning
+ * - If held by an active process, throws LockHeldError
+ *
+ * @param lockPath - Path to the lock file
+ * @returns The lock information that was written
+ * @throws {LockHeldError} If the lock is held by another active process
+ * @throws {LockCorruptError} If the lock file is corrupt or malformed
+ * @throws {AtomicFsError} If the lock file cannot be written
+ */
+export declare function acquireLock(lockPath: string): Promise<LockInfo>;
+/**
+ * Releases a lock by deleting the lock file.
+ *
+ * Only releases the lock if it belongs to the current process.
+ * Silently succeeds if the lock doesn't exist or belongs to another process.
+ *
+ * @param lockPath - Path to the lock file
+ */
+export declare function releaseLock(lockPath: string): Promise<void>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/lib/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/lib/lock.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGjD;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAGpB,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,QAAQ;gBAFhC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,QAAQ;CAKnC;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;aAGvB,QAAQ,EAAE,MAAM;gBADhC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM;CAKnC;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAwClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAgBjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAQnD;AA+CD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CA4DrE;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBjE"}