@elaraai/e3-core 0.0.1-alpha.2

package/dist/src/workspaceStatus.js

@@ -0,0 +1,352 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Workspace status - dry-run analysis of dataflow execution state.
+ *
+ * Provides a complete view of workspace state including:
+ * - Lock status (who holds it, since when)
+ * - Dataset status (unset, stale, up-to-date)
+ * - Task status (up-to-date, ready, waiting, in-progress)
+ *
+ * This is read-only and does not require a lock.
+ */
+import { decodeBeast2For, variant } from '@elaraai/east';
+import { PackageObjectType, TaskObjectType, WorkspaceStateType, pathToString, } from '@elaraai/e3-types';
+import { objectRead } from './objects.js';
+import { executionGet, inputsHash, } from './executions.js';
+import { workspaceGetDatasetHash } from './trees.js';
+import { WorkspaceNotFoundError, WorkspaceNotDeployedError, isNotFoundError, } from './errors.js';
+import { getWorkspaceLockHolder } from './workspaceLock.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+// =============================================================================
+// Workspace State Reader (duplicated to avoid circular deps)
+// =============================================================================
+/**
+ * Read workspace state from file.
+ */
+async function readWorkspaceState(repoPath, ws) {
+    const stateFile = path.join(repoPath, 'workspaces', `${ws}.beast2`);
+    let data;
+    try {
+        data = await fs.readFile(stateFile);
+    }
+    catch (err) {
+        if (isNotFoundError(err)) {
+            throw new WorkspaceNotFoundError(ws);
+        }
+        throw err;
+    }
+    if (data.length === 0) {
+        throw new WorkspaceNotDeployedError(ws);
+    }
+    const decoder = decodeBeast2For(WorkspaceStateType);
+    return decoder(data);
+}
+// =============================================================================
+// Main Function
+// =============================================================================
+/**
+ * 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 async function workspaceStatus(repoPath, ws) {
+    // Check lock status first
+    const lock = await getWorkspaceLockHolder(repoPath, ws);
+    // Read workspace state
+    const state = await readWorkspaceState(repoPath, ws);
+    // Read package object to get tasks and structure
+    const pkgData = await objectRead(repoPath, state.packageHash);
+    const pkgDecoder = decodeBeast2For(PackageObjectType);
+    const pkgObject = pkgDecoder(Buffer.from(pkgData));
+    // Build task nodes
+    const taskNodes = new Map();
+    const outputToTask = new Map(); // output path -> task name
+    const taskDecoder = decodeBeast2For(TaskObjectType);
+    for (const [taskName, taskHash] of pkgObject.tasks) {
+        const taskData = await objectRead(repoPath, taskHash);
+        const task = taskDecoder(Buffer.from(taskData));
+        const outputPathStr = pathToString(task.output);
+        outputToTask.set(outputPathStr, taskName);
+        taskNodes.set(taskName, {
+            name: taskName,
+            hash: taskHash,
+            task,
+            inputPaths: task.inputs,
+            outputPath: task.output,
+        });
+    }
+    // Collect all dataset paths from structure
+    const datasetPaths = [];
+    collectDatasetPaths(pkgObject.data.structure, [], datasetPaths);
+    // Determine task dependencies
+    const taskDependsOn = new Map();
+    for (const [taskName, node] of taskNodes) {
+        const deps = [];
+        for (const inputPath of node.inputPaths) {
+            const inputPathStr = pathToString(inputPath);
+            const producerTask = outputToTask.get(inputPathStr);
+            if (producerTask) {
+                deps.push(producerTask);
+            }
+        }
+        taskDependsOn.set(taskName, deps);
+    }
+    // Determine which tasks are stale (need to rerun)
+    // A task is stale if:
+    // 1. No cached execution for current inputs, OR
+    // 2. Cached output doesn't match current workspace output, OR
+    // 3. Any upstream task is stale
+    const taskIsStale = new Map();
+    const taskStatus = new Map();
+    // First pass: determine which tasks have valid cached executions
+    for (const [taskName, node] of taskNodes) {
+        const status = await computeTaskStatus(repoPath, ws, node, outputToTask, taskNodes, taskIsStale);
+        taskStatus.set(taskName, status);
+        taskIsStale.set(taskName, status.type !== 'up-to-date');
+    }
+    // Second pass: mark tasks as waiting if their upstream is stale
+    for (const [taskName] of taskNodes) {
+        const currentStatus = taskStatus.get(taskName);
+        if (currentStatus.type === 'ready') {
+            // Check if any upstream task is stale
+            const deps = taskDependsOn.get(taskName) ?? [];
+            for (const depName of deps) {
+                if (taskIsStale.get(depName)) {
+                    taskStatus.set(taskName, {
+                        type: 'waiting',
+                        reason: `Waiting for task '${depName}'`,
+                    });
+                    break;
+                }
+            }
+        }
+    }
+    // Build dataset status
+    const datasetStatusInfos = [];
+    for (const datasetPath of datasetPaths) {
+        const pathStr = pathToString(datasetPath);
+        const { refType, hash } = await workspaceGetDatasetHash(repoPath, ws, datasetPath);
+        const producerTask = outputToTask.get(pathStr) ?? null;
+        const isTaskOutput = producerTask !== null;
+        let status;
+        if (refType === 'unassigned') {
+            status = { type: 'unset' };
+        }
+        else if (isTaskOutput && producerTask && taskIsStale.get(producerTask)) {
+            status = { type: 'stale' };
+        }
+        else {
+            status = { type: 'up-to-date' };
+        }
+        datasetStatusInfos.push({
+            path: pathStr,
+            status,
+            hash,
+            isTaskOutput,
+            producedBy: producerTask,
+        });
+    }
+    // Build task status info
+    const taskStatusInfos = [];
+    for (const [taskName, node] of taskNodes) {
+        taskStatusInfos.push({
+            name: taskName,
+            hash: node.hash,
+            status: taskStatus.get(taskName),
+            inputs: node.inputPaths.map(pathToString),
+            output: pathToString(node.outputPath),
+            dependsOn: taskDependsOn.get(taskName) ?? [],
+        });
+    }
+    // Compute summary
+    const summary = {
+        datasets: {
+            total: datasetStatusInfos.length,
+            unset: datasetStatusInfos.filter((d) => d.status.type === 'unset').length,
+            stale: datasetStatusInfos.filter((d) => d.status.type === 'stale').length,
+            upToDate: datasetStatusInfos.filter((d) => d.status.type === 'up-to-date').length,
+        },
+        tasks: {
+            total: taskStatusInfos.length,
+            upToDate: taskStatusInfos.filter((t) => t.status.type === 'up-to-date').length,
+            ready: taskStatusInfos.filter((t) => t.status.type === 'ready').length,
+            waiting: taskStatusInfos.filter((t) => t.status.type === 'waiting').length,
+            inProgress: taskStatusInfos.filter((t) => t.status.type === 'in-progress').length,
+            failed: taskStatusInfos.filter((t) => t.status.type === 'failed').length,
+            error: taskStatusInfos.filter((t) => t.status.type === 'error').length,
+            staleRunning: taskStatusInfos.filter((t) => t.status.type === 'stale-running').length,
+        },
+    };
+    return {
+        workspace: ws,
+        lock,
+        datasets: datasetStatusInfos,
+        tasks: taskStatusInfos,
+        summary,
+    };
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Recursively collect all dataset paths from a structure.
+ */
+function collectDatasetPaths(structure, currentPath, result) {
+    if (structure.type === 'value') {
+        result.push(currentPath);
+    }
+    else if (structure.type === 'struct') {
+        for (const [fieldName, childStructure] of structure.value) {
+            const childPath = [...currentPath, variant('field', fieldName)];
+            collectDatasetPaths(childStructure, childPath, result);
+        }
+    }
+}
+/**
+ * Compute the status of a task.
+ */
+async function computeTaskStatus(repoPath, ws, node, outputToTask, _taskNodes, _taskIsStale) {
+    // First, check if execution is in progress
+    const inProgressStatus = await checkInProgress(repoPath, node.hash);
+    if (inProgressStatus) {
+        return inProgressStatus;
+    }
+    // Gather current input hashes
+    const currentInputHashes = [];
+    let hasUnsetInputs = false;
+    let waitingOnTasks = [];
+    for (const inputPath of node.inputPaths) {
+        const inputPathStr = pathToString(inputPath);
+        const { refType, hash } = await workspaceGetDatasetHash(repoPath, ws, inputPath);
+        if (refType === 'unassigned' || hash === null) {
+            hasUnsetInputs = true;
+            // Check if this is produced by another task
+            const producerTask = outputToTask.get(inputPathStr);
+            if (producerTask) {
+                waitingOnTasks.push(producerTask);
+            }
+            else {
+                // External input that is unset
+                return {
+                    type: 'waiting',
+                    reason: `Input '${inputPathStr}' is not set`,
+                };
+            }
+        }
+        else {
+            currentInputHashes.push(hash);
+        }
+    }
+    // If any inputs are unset and produced by tasks, we're waiting
+    if (hasUnsetInputs && waitingOnTasks.length > 0) {
+        return {
+            type: 'waiting',
+            reason: `Waiting for task(s): ${waitingOnTasks.join(', ')}`,
+        };
+    }
+    // If any inputs are unset (external), we're waiting
+    if (hasUnsetInputs) {
+        return {
+            type: 'waiting',
+            reason: 'Some inputs are not set',
+        };
+    }
+    // Check the execution status for these inputs
+    const inHash = inputsHash(currentInputHashes);
+    const execStatus = await executionGet(repoPath, node.hash, inHash);
+    if (execStatus === null) {
+        // No execution attempted - task is ready to run
+        return { type: 'ready' };
+    }
+    // Check the execution status type
+    switch (execStatus.type) {
+        case 'running': {
+            // Execution was marked as running - check if process is still alive
+            // For now, just report it (process liveness check is done in checkInProgress)
+            // If we reach here, checkInProgress didn't find it, so it might be stale
+            return {
+                type: 'stale-running',
+                pid: Number(execStatus.value.pid),
+                startedAt: execStatus.value.startedAt.toISOString(),
+            };
+        }
+        case 'failed': {
+            // Task ran but returned non-zero exit code
+            return {
+                type: 'failed',
+                exitCode: Number(execStatus.value.exitCode),
+                completedAt: execStatus.value.completedAt.toISOString(),
+            };
+        }
+        case 'error': {
+            // Internal error during execution
+            return {
+                type: 'error',
+                message: execStatus.value.message,
+                completedAt: execStatus.value.completedAt.toISOString(),
+            };
+        }
+        case 'success': {
+            // Execution succeeded - check if workspace output matches
+            const cachedOutputHash = execStatus.value.outputHash;
+            const { refType, hash: wsOutputHash } = await workspaceGetDatasetHash(repoPath, ws, node.outputPath);
+            if (refType !== 'value' || wsOutputHash !== cachedOutputHash) {
+                // Workspace output doesn't match - task needs to run
+                // (This might happen if workspace was modified externally)
+                return { type: 'ready' };
+            }
+            // Everything matches - task is up-to-date
+            return { type: 'up-to-date', cached: true };
+        }
+        default:
+            // Unknown status type - treat as ready
+            return { type: 'ready' };
+    }
+}
+/**
+ * Check if an execution is currently in progress for a task.
+ *
+ * Looks for a 'running' execution status that is still alive.
+ */
+async function checkInProgress(repoPath, taskHash) {
+    // List all executions for this task
+    const execDir = path.join(repoPath, 'executions', taskHash);
+    try {
+        const entries = await fs.readdir(execDir);
+        for (const inHash of entries) {
+            if (!/^[a-f0-9]{64}$/.test(inHash))
+                continue;
+            const status = await executionGet(repoPath, taskHash, inHash);
+            if (status?.type === 'running') {
+                // Found a running execution
+                // We could also verify the process is still alive here
+                return {
+                    type: 'in-progress',
+                    pid: Number(status.value.pid),
+                    startedAt: status.value.startedAt.toISOString(),
+                };
+            }
+        }
+    }
+    catch {
+        // No executions directory
+    }
+    return null;
+}
+//# sourceMappingURL=workspaceStatus.js.map

package/dist/src/workspaceStatus.js.map

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

package/dist/src/workspaces.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import type { WorkspaceState } from '@elaraai/e3-types';
+import { type WorkspaceLockHandle } from './workspaceLock.js';
+/**
+ * Create an empty workspace.
+ *
+ * Creates an undeployed workspace (state file with null package info).
+ * Use workspaceDeploy to deploy a package.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Workspace name
+ * @throws {WorkspaceExistsError} If workspace already exists
+ */
+export declare function workspaceCreate(repoPath: string, name: string): Promise<void>;
+/**
+ * Options for workspace removal.
+ */
+export interface WorkspaceRemoveOptions {
+    /**
+     * External workspace lock to use. If provided, the caller is responsible
+     * for releasing the lock after the operation. If not provided, workspaceRemove
+     * will acquire and release a lock internally.
+     */
+    lock?: WorkspaceLockHandle;
+}
+/**
+ * Remove a workspace.
+ *
+ * Objects remain until repoGc is run.
+ *
+ * Acquires a workspace lock to prevent removing a workspace while a dataflow
+ * is running. Throws WorkspaceLockError if the workspace is currently locked.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Workspace name
+ * @param options - Optional settings including external lock
+ * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+ * @throws {WorkspaceLockError} If workspace is locked by another process
+ */
+export declare function workspaceRemove(repoPath: string, name: string, options?: WorkspaceRemoveOptions): Promise<void>;
+/**
+ * List workspace names.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @returns Array of workspace names
+ */
+export declare function workspaceList(repoPath: string): Promise<string[]>;
+/**
+ * Get the full state for a workspace.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Workspace name
+ * @returns Workspace state, or null if workspace doesn't exist or is not deployed
+ */
+export declare function workspaceGetState(repoPath: string, name: string): Promise<WorkspaceState | null>;
+/**
+ * Get the deployed package for a workspace.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Workspace name
+ * @returns Package name, version, and hash
+ * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+ * @throws {WorkspaceNotDeployedError} If workspace exists but has no package deployed
+ */
+export declare function workspaceGetPackage(repoPath: string, name: string): Promise<{
+    name: string;
+    version: string;
+    hash: string;
+}>;
+/**
+ * Get the root tree hash for a workspace.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Workspace name
+ * @returns Root tree object hash
+ * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+ * @throws {WorkspaceNotDeployedError} If workspace exists but has no package deployed
+ */
+export declare function workspaceGetRoot(repoPath: string, name: string): Promise<string>;
+/**
+ * Atomically update the root tree hash for a workspace.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Workspace name
+ * @param hash - New root tree object hash
+ * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+ * @throws {WorkspaceNotDeployedError} If workspace exists but has no package deployed
+ */
+export declare function workspaceSetRoot(repoPath: string, name: string, hash: string): Promise<void>;
+/**
+ * Options for workspace deployment.
+ */
+export interface WorkspaceDeployOptions {
+    /**
+     * External workspace lock to use. If provided, the caller is responsible
+     * for releasing the lock after the operation. If not provided, workspaceDeploy
+     * will acquire and release a lock internally.
+     */
+    lock?: WorkspaceLockHandle;
+}
+/**
+ * Deploy a package to a workspace.
+ *
+ * Creates the workspace if it doesn't exist. Writes state file atomically
+ * containing deployment info and root hash.
+ *
+ * Acquires a workspace lock to prevent conflicts with running dataflows
+ * or concurrent deploys. Throws WorkspaceLockError if the workspace is
+ * currently locked by another process.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Workspace name
+ * @param pkgName - Package name
+ * @param pkgVersion - Package version
+ * @param options - Optional settings including external lock
+ * @throws {WorkspaceLockError} If workspace is locked by another process
+ */
+export declare function workspaceDeploy(repoPath: string, name: string, pkgName: string, pkgVersion: string, options?: WorkspaceDeployOptions): Promise<void>;
+/**
+ * Result of exporting a workspace
+ */
+export interface WorkspaceExportResult {
+    packageHash: string;
+    objectCount: number;
+    name: string;
+    version: string;
+}
+/**
+ * Export a workspace as a package.
+ *
+ * 1. Read workspace state
+ * 2. Read deployed package structure using stored packageHash
+ * 3. Create new PackageObject with data.value set to current rootHash
+ * 4. Collect all referenced objects
+ * 5. Write to .zip
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Workspace name
+ * @param zipPath - Path to write the .zip file
+ * @param outputName - Package name (default: deployed package name)
+ * @param version - Package version (default: <pkgVersion>-<rootHash[0..8]>)
+ * @returns Export result with package info
+ * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+ * @throws {WorkspaceNotDeployedError} If workspace exists but has no package deployed
+ */
+export declare function workspaceExport(repoPath: string, name: string, zipPath: string, outputName?: string, version?: string): Promise<WorkspaceExportResult>;
+//# sourceMappingURL=workspaces.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspaces.d.ts","sourceRoot":"","sources":["../../src/workspaces.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,mBAAmB,CAAC;AASvE,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA6EpF;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAMhC;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAO1D;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,CAAC,CAqGhC"}