@ttfw/envoi 1.0.0

package/dist/lib/fingerprint.js

@@ -0,0 +1,116 @@
+/**
+ * Task fingerprinting utilities.
+ *
+ * Task fingerprint is used to detect identical re-dispatch loops.
+ * If orchestrator 'retries' without changing the plan, fingerprint stays same and runner stops.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Top-level fields to include in the fingerprint computation.
+ */
+const TOP_LEVEL_FIELDS = [
+    'goal',
+    'subtasks',
+    'acceptance',
+    'verify',
+    'implementation',
+    'risk',
+    'notes',
+];
+/**
+ * Scope fields to include in the fingerprint computation.
+ */
+const SCOPE_FIELDS = [
+    'write',
+    'create_under',
+    'forbidden',
+    'read_forbidden',
+];
+/**
+ * Fields to exclude from fingerprint computation.
+ */
+const EXCLUDED_FIELDS = new Set(['task_id', 'id', 'v', 'milestone', 'context']);
+/**
+ * Recursively processes an object to trim strings and ensure canonical form.
+ */
+function processValue(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        return value.trim();
+    }
+    if (Array.isArray(value)) {
+        return value.map(processValue);
+    }
+    if (typeof value === 'object') {
+        const processed = {};
+        const sortedKeys = Object.keys(value).sort();
+        for (const key of sortedKeys) {
+            processed[key] = processValue(value[key]);
+        }
+        return processed;
+    }
+    return value;
+}
+/**
+ * Extracts fingerprint-relevant fields from a task object.
+ */
+function extractFingerprintFields(task) {
+    const result = {};
+    // Extract top-level fields
+    for (const field of TOP_LEVEL_FIELDS) {
+        if (field in task && !EXCLUDED_FIELDS.has(field)) {
+            result[field] = task[field];
+        }
+    }
+    // Extract scope fields if scope exists
+    if (task.scope && typeof task.scope === 'object') {
+        const scope = task.scope;
+        const scopeResult = {};
+        for (const field of SCOPE_FIELDS) {
+            if (field in scope) {
+                scopeResult[field] = scope[field];
+            }
+        }
+        // Only add scope if it has at least one field
+        if (Object.keys(scopeResult).length > 0) {
+            result.scope = scopeResult;
+        }
+    }
+    return result;
+}
+/**
+ * Canonicalizes a task object to a stable JSON string.
+ *
+ * The canonical form:
+ * - Has sorted keys (alphabetical order)
+ * - Has trimmed strings
+ * - Excludes task_id, id, v, milestone, and context fields
+ * - Only includes fingerprint-relevant fields
+ *
+ * @param task - The task object to canonicalize
+ * @returns A canonical JSON string representation
+ */
+export function canonicalizeTask(task) {
+    // Extract only fingerprint-relevant fields
+    const fingerprintData = extractFingerprintFields(task);
+    // Process the data (trim strings, sort keys recursively)
+    const processed = processValue(fingerprintData);
+    // Convert to JSON with stable key ordering
+    // JSON.stringify already produces stable output for objects with sorted keys
+    return JSON.stringify(processed);
+}
+/**
+ * Computes a SHA-256 fingerprint of a task.
+ *
+ * @param task - The task object to fingerprint
+ * @returns A 64-character hexadecimal SHA-256 hash string
+ */
+export function computeFingerprint(task) {
+    const canonical = canonicalizeTask(task);
+    const hash = createHash('sha256');
+    hash.update(canonical, 'utf8');
+    return hash.digest('hex');
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/lib/fingerprint.js.map

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

package/dist/lib/fs.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Atomic file system utilities for crash-safe JSON operations.
+ *
+ * These utilities implement the write-tmp-fsync-rename pattern to ensure
+ * atomic file writes that survive crashes and power failures on POSIX systems.
+ */
+/**
+ * Result of glob pattern safety check.
+ */
+export type GlobSafetyResult = {
+    safe: true;
+} | {
+    safe: false;
+    reason: string;
+};
+/**
+ * Checks if a glob pattern is safe for file deletion operations.
+ *
+ * Safe patterns:
+ * - Relative paths like `envoi/*.tmp`, `envoi/**\/*.tmp`, `*.tmp`
+ *
+ * Unsafe patterns:
+ * - Empty or whitespace-only patterns
+ * - Patterns containing path traversal (`..`)
+ * - Unix absolute paths (starting with `/`)
+ * - Windows absolute paths (e.g., `C:\`)
+ * - UNC paths (`\\server\share` or `//server/share`)
+ *
+ * @param pattern - The glob pattern to check
+ * @returns Result indicating if the pattern is safe
+ */
+export declare function isGlobPatternSafe(pattern: string): GlobSafetyResult;
+/**
+ * Error thrown when atomic file operations fail.
+ */
+export declare class AtomicFsError extends Error {
+    readonly filePath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, filePath: string, cause?: Error | undefined);
+}
+/**
+ * Atomically writes JSON data to a file using the write-tmp-fsync-rename pattern.
+ *
+ * This ensures that the file is never in a partially-written state, even if the
+ * process crashes or the system loses power during the write operation.
+ *
+ * @param filePath - The path to write the JSON file to
+ * @param data - The data to serialize and write
+ * @throws {AtomicFsError} If the write operation fails
+ *
+ * @example
+ * ```typescript
+ * await atomicWriteJson('/path/to/config.json', { version: 1, enabled: true });
+ * ```
+ */
+export declare function atomicWriteJson<T>(filePath: string, data: T): Promise<void>;
+/**
+ * Reads and parses a JSON file with proper typing.
+ *
+ * @param filePath - The path to the JSON file to read
+ * @returns The parsed JSON data
+ * @throws {AtomicFsError} If the file cannot be read or parsed
+ *
+ * @example
+ * ```typescript
+ * interface Config {
+ *   version: number;
+ *   enabled: boolean;
+ * }
+ * const config = await atomicReadJson<Config>('/path/to/config.json');
+ * ```
+ */
+export declare function atomicReadJson<T>(filePath: string): Promise<T>;
+/**
+ * Cleans up stale .tmp files in a directory.
+ *
+ * This should be called during startup preflight to remove any .tmp files
+ * left behind by interrupted write operations.
+ *
+ * @param dir - The directory to scan for .tmp files
+ * @param pattern - Optional pattern to match (defaults to '*.tmp')
+ * @returns List of deleted file paths
+ * @throws {AtomicFsError} If the cleanup operation fails
+ *
+ * @example
+ * ```typescript
+ * // Clean up all .tmp files in /envoi directory
+ * const deleted = await cleanupTmpFiles('/envoi');
+ * console.log(`Cleaned up ${deleted.length} stale tmp files`);
+ * ```
+ */
+export declare function cleanupTmpFiles(dir: string, pattern?: string): Promise<string[]>;
+//# sourceMappingURL=fs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/lib/fs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CA2BnE;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAGpB,QAAQ,EAAE,MAAM;aAChB,KAAK,CAAC,EAAE,KAAK;gBAF7B,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,KAAK,YAAA;CAKhC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CjF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAWpE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA2BtF"}

package/dist/lib/fs.js

@@ -0,0 +1,179 @@
+/**
+ * Atomic file system utilities for crash-safe JSON operations.
+ *
+ * These utilities implement the write-tmp-fsync-rename pattern to ensure
+ * atomic file writes that survive crashes and power failures on POSIX systems.
+ */
+import { open, rename, unlink, readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Checks if a glob pattern is safe for file deletion operations.
+ *
+ * Safe patterns:
+ * - Relative paths like `envoi/*.tmp`, `envoi/**\/*.tmp`, `*.tmp`
+ *
+ * Unsafe patterns:
+ * - Empty or whitespace-only patterns
+ * - Patterns containing path traversal (`..`)
+ * - Unix absolute paths (starting with `/`)
+ * - Windows absolute paths (e.g., `C:\`)
+ * - UNC paths (`\\server\share` or `//server/share`)
+ *
+ * @param pattern - The glob pattern to check
+ * @returns Result indicating if the pattern is safe
+ */
+export function isGlobPatternSafe(pattern) {
+    // Check for empty or whitespace-only patterns
+    if (!pattern || pattern.trim() === '') {
+        return { safe: false, reason: 'Empty or whitespace-only pattern' };
+    }
+    // Check for path traversal
+    if (pattern.includes('..')) {
+        return { safe: false, reason: 'Pattern contains path traversal (..)' };
+    }
+    // Check for Unix absolute paths
+    if (pattern.startsWith('/')) {
+        return { safe: false, reason: 'Pattern is an absolute Unix path' };
+    }
+    // Check for Windows absolute paths (e.g., C:\, D:\)
+    if (/^[A-Za-z]:[\\\/]/.test(pattern)) {
+        return { safe: false, reason: 'Pattern is an absolute Windows path' };
+    }
+    // Check for UNC paths (\\server\share or //server/share)
+    if (pattern.startsWith('\\\\') || pattern.startsWith('//')) {
+        return { safe: false, reason: 'Pattern is a UNC path' };
+    }
+    return { safe: true };
+}
+/**
+ * Error thrown when atomic file operations fail.
+ */
+export class AtomicFsError extends Error {
+    filePath;
+    cause;
+    constructor(message, filePath, cause) {
+        super(message);
+        this.filePath = filePath;
+        this.cause = cause;
+        this.name = 'AtomicFsError';
+    }
+}
+/**
+ * Atomically writes JSON data to a file using the write-tmp-fsync-rename pattern.
+ *
+ * This ensures that the file is never in a partially-written state, even if the
+ * process crashes or the system loses power during the write operation.
+ *
+ * @param filePath - The path to write the JSON file to
+ * @param data - The data to serialize and write
+ * @throws {AtomicFsError} If the write operation fails
+ *
+ * @example
+ * ```typescript
+ * await atomicWriteJson('/path/to/config.json', { version: 1, enabled: true });
+ * ```
+ */
+export async function atomicWriteJson(filePath, data) {
+    const tmpPath = `${filePath}.tmp`;
+    let fileHandle = null;
+    try {
+        // Serialize with 2-space indent for readability
+        const content = JSON.stringify(data, null, 2) + '\n';
+        // Open file for writing, create if doesn't exist, truncate if exists
+        fileHandle = await open(tmpPath, 'w');
+        // Write the content
+        await fileHandle.writeFile(content, 'utf-8');
+        // fsync to ensure data is flushed to disk
+        await fileHandle.sync();
+        // Close before rename
+        await fileHandle.close();
+        fileHandle = null;
+        // Atomic rename (POSIX guarantees atomicity)
+        await rename(tmpPath, filePath);
+    }
+    catch (error) {
+        // Attempt to clean up the tmp file on error
+        if (fileHandle) {
+            try {
+                await fileHandle.close();
+            }
+            catch {
+                // Ignore close errors during cleanup
+            }
+        }
+        try {
+            await unlink(tmpPath);
+        }
+        catch {
+            // Ignore unlink errors - file may not exist
+        }
+        throw new AtomicFsError(`Failed to atomically write JSON to ${filePath}: ${error instanceof Error ? error.message : String(error)}`, filePath, error instanceof Error ? error : undefined);
+    }
+}
+/**
+ * Reads and parses a JSON file with proper typing.
+ *
+ * @param filePath - The path to the JSON file to read
+ * @returns The parsed JSON data
+ * @throws {AtomicFsError} If the file cannot be read or parsed
+ *
+ * @example
+ * ```typescript
+ * interface Config {
+ *   version: number;
+ *   enabled: boolean;
+ * }
+ * const config = await atomicReadJson<Config>('/path/to/config.json');
+ * ```
+ */
+export async function atomicReadJson(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new AtomicFsError(`Failed to read JSON from ${filePath}: ${error instanceof Error ? error.message : String(error)}`, filePath, error instanceof Error ? error : undefined);
+    }
+}
+/**
+ * Cleans up stale .tmp files in a directory.
+ *
+ * This should be called during startup preflight to remove any .tmp files
+ * left behind by interrupted write operations.
+ *
+ * @param dir - The directory to scan for .tmp files
+ * @param pattern - Optional pattern to match (defaults to '*.tmp')
+ * @returns List of deleted file paths
+ * @throws {AtomicFsError} If the cleanup operation fails
+ *
+ * @example
+ * ```typescript
+ * // Clean up all .tmp files in /envoi directory
+ * const deleted = await cleanupTmpFiles('/envoi');
+ * console.log(`Cleaned up ${deleted.length} stale tmp files`);
+ * ```
+ */
+export async function cleanupTmpFiles(dir, pattern = '.tmp') {
+    const deleted = [];
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith(pattern)) {
+                const filePath = join(dir, entry.name);
+                try {
+                    await unlink(filePath);
+                    deleted.push(filePath);
+                }
+                catch (error) {
+                    // Log but continue - we want to clean up as many as possible
+                    console.warn(`Failed to delete tmp file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        return deleted;
+    }
+    catch (error) {
+        throw new AtomicFsError(`Failed to cleanup tmp files in ${dir}: ${error instanceof Error ? error.message : String(error)}`, dir, error instanceof Error ? error : undefined);
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/lib/fs.js.map

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

package/dist/lib/git.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Git helper functions for preflight checks and diff tracking.
+ *
+ * Uses execSync for git operations to ensure synchronous, blocking behavior.
+ */
+/**
+ * Checks if the current directory is inside a git repository.
+ *
+ * @returns true if in a git repo, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (!isGitRepo()) {
+ *   console.error('Not in a git repository');
+ * }
+ * ```
+ */
+export declare function isGitRepo(): boolean;
+/**
+ * Checks if the git worktree is clean (no uncommitted tracked changes
+ * AND no untracked files).
+ *
+ * A clean worktree means:
+ * - No staged changes
+ * - No unstaged changes to tracked files
+ * - No untracked files
+ *
+ * @returns true if worktree is clean, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (!isWorktreeClean()) {
+ *   console.error('Worktree has uncommitted changes');
+ * }
+ * ```
+ */
+export declare function isWorktreeClean(): boolean;
+/**
+ * Parses git status porcelain output and filters files based on exclusion globs.
+ *
+ * This is a pure function that can be easily tested.
+ *
+ * @param statusOutput - Raw output from `git status --porcelain`
+ * @param excludeGlobs - Glob patterns for files to exclude from the dirty check
+ * @returns Object with `clean` (boolean), `dirtyFiles`, and `excludedFiles`
+ */
+export declare function parseGitStatusWithExclusions(statusOutput: string, excludeGlobs: string[]): {
+    clean: boolean;
+    dirtyFiles: string[];
+    excludedFiles: string[];
+};
+/**
+ * Checks if the git worktree is clean, excluding files matching specified globs.
+ *
+ * This is useful for ignoring runner-owned files (like REPORT.json, STATE.json)
+ * that are expected to change every tick.
+ *
+ * @param excludeGlobs - Glob patterns for files to exclude from the dirty check
+ * @returns Object with `clean` (boolean) and `dirtyFiles` (non-excluded dirty files)
+ *
+ * @example
+ * ```typescript
+ * const result = isWorktreeCleanExcluding(['envoi/**', 'pilot/**']);
+ * if (!result.clean) {
+ *   console.error('Dirty files:', result.dirtyFiles);
+ * }
+ * ```
+ */
+export declare function isWorktreeCleanExcluding(excludeGlobs: string[]): {
+    clean: boolean;
+    dirtyFiles: string[];
+    excludedFiles: string[];
+};
+/**
+ * Gets the current HEAD commit SHA.
+ *
+ * @returns The full 40-character SHA of HEAD
+ * @throws {Error} If not in a git repo or HEAD doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const sha = getHeadCommit();
+ * console.log(`Current commit: ${sha}`);
+ * ```
+ */
+export declare function getHeadCommit(): string;
+/**
+ * Gets the list of files that have changed since a base commit.
+ *
+ * Returns both modified and added files in the diff.
+ *
+ * @param base - The base commit SHA to diff against
+ * @returns Array of file paths that have changed
+ * @throws {Error} If the diff operation fails
+ *
+ * @example
+ * ```typescript
+ * const changedFiles = getDiffFiles('abc123');
+ * console.log(`${changedFiles.length} files changed`);
+ * ```
+ */
+export declare function getDiffFiles(base: string): string[];
+/**
+ * Gets the list of untracked files in the repository.
+ *
+ * @returns Array of untracked file paths
+ *
+ * @example
+ * ```typescript
+ * const untracked = getUntrackedFiles();
+ * if (untracked.length > 0) {
+ *   console.log(`Found ${untracked.length} untracked files`);
+ * }
+ * ```
+ */
+export declare function getUntrackedFiles(): string[];
+/**
+ * Gets the current git branch name.
+ *
+ * @returns The current branch name
+ * @throws {Error} If not in a git repo or branch cannot be determined
+ *
+ * @example
+ * ```typescript
+ * const branch = getCurrentBranch();
+ * console.log(`Current branch: ${branch}`);
+ * ```
+ */
+export declare function getCurrentBranch(): string;
+/**
+ * Gets the top-level directory of the git repository.
+ *
+ * @returns The absolute path to the git repository root, or null if not in a git repo
+ *
+ * @example
+ * ```typescript
+ * const root = getGitTopLevel();
+ * if (root) {
+ *   console.log(`Git root: ${root}`);
+ * }
+ * ```
+ */
+export declare function getGitTopLevel(): string | null;
+/**
+ * Stashes pilot/ directory files to prevent merge conflicts.
+ *
+ * Creates a stash containing only files in the pilot/ directory.
+ * This allows safe merging without losing pilot state.
+ *
+ * @returns The stash reference (e.g., "stash@{0}")
+ * @throws {Error} If the stash operation fails
+ *
+ * @example
+ * ```typescript
+ * const stashRef = stashPilotFiles();
+ * // Perform merge...
+ * popPilotStash(stashRef);
+ * ```
+ */
+export declare function stashPilotFiles(): string;
+/**
+ * Pops a previously created stash to restore pilot files.
+ *
+ * Restores the stashed pilot/ directory files back to the working tree.
+ *
+ * @param stashRef - The stash reference returned by stashPilotFiles (e.g., "stash@{0}")
+ * @throws {Error} If the stash pop operation fails
+ *
+ * @example
+ * ```typescript
+ * const stashRef = stashPilotFiles();
+ * // Perform merge...
+ * popPilotStash(stashRef);
+ * ```
+ */
+export declare function popPilotStash(stashRef: string): void;
+//# sourceMappingURL=git.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/lib/git.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAUnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAazC;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EAAE,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CA0CnE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EAAE,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CAYnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAYtC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAenD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAiB5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAYzC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAU9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAmCxC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAWpD"}