@elaraai/e3-core 0.0.1-alpha.2

package/dist/src/workspaceLock.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type LockHolder } from './errors.js';
+/**
+ * Handle to a held workspace lock.
+ * Call release() when done to free the lock.
+ */
+export interface WorkspaceLockHandle {
+    /** The workspace name this lock is for */
+    readonly workspace: string;
+    /** Path to the lock file */
+    readonly lockPath: string;
+    /** Release the lock. Safe to call multiple times. */
+    release(): Promise<void>;
+}
+/**
+ * Options for acquiring a workspace lock.
+ */
+export interface AcquireLockOptions {
+    /**
+     * If true, wait for the lock to become available instead of failing immediately.
+     * Default: false (fail fast if locked)
+     */
+    wait?: boolean;
+    /**
+     * Timeout in milliseconds when wait=true. Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+}
+/**
+ * Get the lock file path for a workspace.
+ */
+export declare function workspaceLockPath(repoPath: string, workspace: string): string;
+/**
+ * Acquire an exclusive lock on a workspace.
+ *
+ * Uses Linux flock() for kernel-managed locking. The lock is automatically
+ * released when the process exits (even on crash/kill).
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param workspace - Workspace name to lock
+ * @param options - Lock acquisition options
+ * @returns Lock handle - call release() when done
+ * @throws {WorkspaceLockError} If workspace is locked by another process
+ *
+ * @example
+ * ```typescript
+ * const lock = await acquireWorkspaceLock(repoPath, 'production');
+ * try {
+ *   await dataflowExecute(repoPath, 'production', { lock });
+ * } finally {
+ *   await lock.release();
+ * }
+ * ```
+ */
+export declare function acquireWorkspaceLock(repoPath: string, workspace: string, options?: AcquireLockOptions): Promise<WorkspaceLockHandle>;
+/**
+ * Check if a workspace is currently locked.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param workspace - Workspace name to check
+ * @returns Lock holder info if locked, null if not locked
+ */
+export declare function getWorkspaceLockHolder(repoPath: string, workspace: string): Promise<LockHolder | null>;
+//# sourceMappingURL=workspaceLock.d.ts.map

package/dist/src/workspaceLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceLock.d.ts","sourceRoot":"","sources":["../../src/workspaceLock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmBH,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAOlE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAcD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7E;AAgCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAiD9B;AAsFD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAoB5B"}

package/dist/src/workspaceLock.js

@@ -0,0 +1,217 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Workspace locking for safe concurrent access.
+ *
+ * Provides exclusive locks on workspaces to prevent concurrent dataflow
+ * executions or writes that could corrupt workspace state. Uses Linux
+ * flock() for automatic lock release on process death.
+ *
+ * Lock mechanism:
+ * - Uses flock(LOCK_EX | LOCK_NB) via the `flock` command for kernel-managed locking
+ * - Lock is automatically released when the process dies (kernel handles this)
+ * - Metadata (PID, bootId, startTime) written to lock file for diagnostics
+ * - Stale lock detection via bootId comparison (handles system restarts)
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { WorkspaceLockError } from './errors.js';
+import { getBootId, getPidStartTime, isProcessAlive } from './executions.js';
+/**
+ * Get the lock file path for a workspace.
+ */
+export function workspaceLockPath(repoPath, workspace) {
+    return path.join(repoPath, 'workspaces', `${workspace}.lock`);
+}
+/**
+ * Read lock metadata from a lock file.
+ * Returns null if file doesn't exist or is invalid.
+ */
+async function readLockMetadata(lockPath) {
+    try {
+        const data = await fs.readFile(lockPath, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Convert internal metadata to public LockHolder interface.
+ */
+function metadataToHolder(metadata) {
+    return {
+        pid: metadata.pid,
+        acquiredAt: metadata.acquiredAt,
+        bootId: metadata.bootId,
+        startTime: metadata.startTime,
+        command: metadata.command,
+    };
+}
+// =============================================================================
+// Lock Acquisition
+// =============================================================================
+/**
+ * Acquire an exclusive lock on a workspace.
+ *
+ * Uses Linux flock() for kernel-managed locking. The lock is automatically
+ * released when the process exits (even on crash/kill).
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param workspace - Workspace name to lock
+ * @param options - Lock acquisition options
+ * @returns Lock handle - call release() when done
+ * @throws {WorkspaceLockError} If workspace is locked by another process
+ *
+ * @example
+ * ```typescript
+ * const lock = await acquireWorkspaceLock(repoPath, 'production');
+ * try {
+ *   await dataflowExecute(repoPath, 'production', { lock });
+ * } finally {
+ *   await lock.release();
+ * }
+ * ```
+ */
+export async function acquireWorkspaceLock(repoPath, workspace, options = {}) {
+    const lockPath = workspaceLockPath(repoPath, workspace);
+    // Ensure workspaces directory exists
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    // Gather our process identification
+    const pid = process.pid;
+    const bootId = await getBootId();
+    const startTime = await getPidStartTime(pid);
+    const command = process.argv.join(' ');
+    const acquiredAt = new Date().toISOString();
+    const metadata = { pid, bootId, startTime, acquiredAt, command };
+    // Try to acquire flock via subprocess
+    // The subprocess holds the lock and we communicate with it via stdin/signals
+    const flockProcess = await tryAcquireFlock(lockPath, metadata, options);
+    if (!flockProcess) {
+        // Failed to acquire - read metadata to report who has it
+        const existingMetadata = await readLockMetadata(lockPath);
+        const holder = existingMetadata ? metadataToHolder(existingMetadata) : undefined;
+        throw new WorkspaceLockError(workspace, holder);
+    }
+    // Lock acquired! Create handle
+    let released = false;
+    const handle = {
+        workspace,
+        lockPath,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            // Kill the flock subprocess to release the lock
+            flockProcess.kill('SIGTERM');
+            // Clean up lock file (best effort)
+            try {
+                await fs.unlink(lockPath);
+            }
+            catch {
+                // Ignore - file might already be gone
+            }
+        },
+    };
+    return handle;
+}
+/**
+ * Try to acquire flock using a subprocess.
+ *
+ * We spawn `flock --nonblock <lockfile> cat` which:
+ * 1. Tries to acquire exclusive lock (non-blocking)
+ * 2. If successful, runs `cat` which blocks reading stdin forever
+ * 3. We keep the subprocess alive to hold the lock
+ * 4. When we kill the subprocess, the lock is released
+ *
+ * Returns the subprocess if lock acquired, null if lock is held by another.
+ */
+async function tryAcquireFlock(lockPath, metadata, options) {
+    // First, check if there's a stale lock we can clean up
+    await checkAndCleanStaleLock(lockPath);
+    const args = options.wait
+        ? ['--timeout', String((options.timeout ?? 30000) / 1000), lockPath, 'cat']
+        : ['--nonblock', lockPath, 'cat'];
+    const child = spawn('flock', args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: false,
+    });
+    return new Promise((resolve) => {
+        let resolved = false;
+        // If flock fails to acquire, it exits with code 1
+        child.on('error', () => {
+            if (!resolved) {
+                resolved = true;
+                resolve(null);
+            }
+        });
+        child.on('exit', () => {
+            if (!resolved) {
+                resolved = true;
+                // Exit code 1 means lock is held by another
+                resolve(null);
+            }
+        });
+        // Give flock a moment to either acquire or fail
+        // If it's still running after 100ms, we have the lock
+        setTimeout(() => {
+            if (!resolved && !child.killed && child.exitCode === null) {
+                resolved = true;
+                // Write metadata to lock file now that we have the lock
+                // Use void to explicitly ignore the promise (metadata is informational only)
+                void fs.writeFile(lockPath, JSON.stringify(metadata, null, 2)).catch(() => { });
+                resolve(child);
+            }
+        }, 100);
+    });
+}
+/**
+ * Check if a lock file exists with stale metadata and clean it up.
+ * A lock is stale if the holder process no longer exists.
+ */
+async function checkAndCleanStaleLock(lockPath) {
+    const metadata = await readLockMetadata(lockPath);
+    if (!metadata)
+        return;
+    // Check if the process that created this lock is still alive
+    const alive = await isProcessAlive(metadata.pid, metadata.startTime, metadata.bootId);
+    if (!alive) {
+        // Stale lock - try to remove it
+        try {
+            await fs.unlink(lockPath);
+        }
+        catch {
+            // Ignore - another process might have cleaned it up
+        }
+    }
+}
+/**
+ * Check if a workspace is currently locked.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param workspace - Workspace name to check
+ * @returns Lock holder info if locked, null if not locked
+ */
+export async function getWorkspaceLockHolder(repoPath, workspace) {
+    const lockPath = workspaceLockPath(repoPath, workspace);
+    const metadata = await readLockMetadata(lockPath);
+    if (!metadata)
+        return null;
+    // Check if the holder is still alive
+    const alive = await isProcessAlive(metadata.pid, metadata.startTime, metadata.bootId);
+    if (!alive) {
+        // Stale lock - clean it up and report as not locked
+        try {
+            await fs.unlink(lockPath);
+        }
+        catch {
+            // Ignore
+        }
+        return null;
+    }
+    return metadataToHolder(metadata);
+}
+//# sourceMappingURL=workspaceLock.js.map

package/dist/src/workspaceLock.js.map

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

package/dist/src/workspaceStatus.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type LockHolder } from './errors.js';
+/**
+ * Status of a dataset in the workspace.
+ */
+export type DatasetStatus = {
+    type: 'unset';
+} | {
+    type: 'stale';
+} | {
+    type: 'up-to-date';
+};
+/**
+ * Status of a task in the workspace.
+ */
+export type TaskStatus = {
+    type: 'up-to-date';
+    cached: boolean;
+} | {
+    type: 'ready';
+} | {
+    type: 'waiting';
+    reason: string;
+} | {
+    type: 'in-progress';
+    pid?: number;
+    startedAt?: string;
+} | {
+    type: 'failed';
+    exitCode: number;
+    completedAt?: string;
+} | {
+    type: 'error';
+    message: string;
+    completedAt?: string;
+} | {
+    type: 'stale-running';
+    pid?: number;
+    startedAt?: string;
+};
+/**
+ * Information about a dataset in the status report.
+ */
+export interface DatasetStatusInfo {
+    /** Dataset path (e.g., "inputs.sales_data") */
+    path: string;
+    /** Current status */
+    status: DatasetStatus;
+    /** Hash of current value (if set) */
+    hash: string | null;
+    /** True if this is a task output */
+    isTaskOutput: boolean;
+    /** Name of task that produces this (if any) */
+    producedBy: string | null;
+}
+/**
+ * Information about a task in the status report.
+ */
+export interface TaskStatusInfo {
+    /** Task name */
+    name: string;
+    /** Task hash */
+    hash: string;
+    /** Current status */
+    status: TaskStatus;
+    /** Input dataset paths */
+    inputs: string[];
+    /** Output dataset path */
+    output: string;
+    /** Tasks this one depends on */
+    dependsOn: string[];
+}
+/**
+ * Complete workspace status report.
+ */
+export interface WorkspaceStatusResult {
+    /** Workspace name */
+    workspace: string;
+    /** Lock status - null if not locked */
+    lock: LockHolder | null;
+    /** Status of all datasets */
+    datasets: DatasetStatusInfo[];
+    /** Status of all tasks */
+    tasks: TaskStatusInfo[];
+    /** Summary counts */
+    summary: {
+        datasets: {
+            total: number;
+            unset: number;
+            stale: number;
+            upToDate: number;
+        };
+        tasks: {
+            total: number;
+            upToDate: number;
+            ready: number;
+            waiting: number;
+            inProgress: number;
+            failed: number;
+            error: number;
+            staleRunning: number;
+        };
+    };
+}
+/**
+ * Get comprehensive status of a workspace.
+ *
+ * Performs a dry-run analysis of the workspace to determine:
+ * - Whether the workspace is locked (and by whom)
+ * - Status of each dataset (unset, stale, up-to-date)
+ * - Status of each task (up-to-date, ready, waiting, in-progress)
+ *
+ * This is a read-only operation that does not modify workspace state
+ * and does not require acquiring a lock.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @returns Complete status report
+ * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+ * @throws {WorkspaceNotDeployedError} If workspace has no package deployed
+ */
+export declare function workspaceStatus(repoPath: string, ws: string): Promise<WorkspaceStatusResult>;
+//# sourceMappingURL=workspaceStatus.d.ts.map

package/dist/src/workspaceStatus.d.ts.map

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