@livingdata/pipex 0.0.8 → 0.0.10

package/dist/engine/workspace.js

@@ -1,23 +1,28 @@
-import { access, mkdir, readdir, rename, rm, symlink } from 'node:fs/promises';
+import { access, mkdir, readdir, readFile, rename, rm, symlink, writeFile } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
+import { WorkspaceError, StagingError } from '../errors.js';
 /**
  * Isolated execution environment for container runs.
  *
  * A workspace provides:
  * - **staging/**: Temporary write location during execution
- * - **artifacts/**: Committed outputs (immutable, read-only)
+ * - **runs/**: Committed run outputs (immutable, read-only)
  * - **caches/**: Persistent read-write caches (shared across steps)
  * - **state.json**: Managed by orchestration layer (e.g., CLI) for caching
  *
- * ## Artifact Lifecycle
+ * ## Run Lifecycle
  *
- * 1. `prepareArtifact()` creates `staging/{artifactId}/`
- * 2. Container writes to `staging/{artifactId}/` (mounted as `/output`)
- * 3. Success: `commitArtifact()` atomically moves to `artifacts/{artifactId}/`
- *    OR Failure: `discardArtifact()` deletes `staging/{artifactId}/`
+ * Each step execution produces a **run**, a structured directory containing
+ * artifacts (files produced by the step), logs (stdout/stderr), and metadata.
  *
- * Artifacts are immutable once committed.
+ * 1. `prepareRun()` creates `staging/{runId}/` with `artifacts/` subdirectory
+ * 2. Container writes to `staging/{runId}/artifacts/` (mounted as `/output`)
+ * 3. Orchestration layer writes logs and metadata to `staging/{runId}/`
+ * 4. Success: `commitRun()` atomically moves to `runs/{runId}/`
+ *    OR Failure: `discardRun()` deletes `staging/{runId}/`
+ *
+ * Runs are immutable once committed.
  *
  * ## Cache Lifecycle
  *
@@ -30,12 +35,12 @@ import { join } from 'node:path';
  * @example
  * ```typescript
  * const ws = await Workspace.create('/tmp/workdir', 'my-workspace')
- * const artifactId = ws.generateArtifactId()
- * await ws.prepareArtifact(artifactId)
+ * const runId = ws.generateRunId()
+ * await ws.prepareRun(runId)
  * await ws.prepareCache('pnpm-store')
  * // ... container execution ...
- * await ws.commitArtifact(artifactId) // On success
- * // OR await ws.discardArtifact(artifactId) // On failure
+ * await ws.commitRun(runId) // On success
+ * // OR await ws.discardRun(runId) // On failure
  * ```
  */
 export class Workspace {
@@ -49,7 +54,7 @@ export class Workspace {
         return Workspace.generateId();
     }
     /**
-     * Creates a new workspace with staging, artifacts, and caches directories.
+     * Creates a new workspace with staging, runs, and caches directories.
      * @param workdirRoot - Root directory for all workspaces
      * @param id - Optional workspace ID (auto-generated if omitted)
      * @returns Newly created workspace
@@ -58,7 +63,7 @@ export class Workspace {
         const workspaceId = id ?? Workspace.generateWorkspaceId();
         const root = join(workdirRoot, workspaceId);
         await mkdir(join(root, 'staging'), { recursive: true });
-        await mkdir(join(root, 'artifacts'), { recursive: true });
+        await mkdir(join(root, 'runs'), { recursive: true });
         await mkdir(join(root, 'caches'), { recursive: true });
         return new Workspace(workspaceId, root);
     }
@@ -96,7 +101,7 @@ export class Workspace {
      */
     static async remove(workdirRoot, id) {
         if (id.includes('..') || id.includes('/')) {
-            throw new Error(`Invalid workspace ID: ${id}`);
+            throw new WorkspaceError('INVALID_WORKSPACE_ID', `Invalid workspace ID: ${id}`);
         }
         await rm(join(workdirRoot, id), { recursive: true, force: true });
     }
@@ -113,75 +118,104 @@ export class Workspace {
         this.root = root;
     }
     /**
-     * Generates a unique artifact identifier.
-     * @returns Artifact ID in format: `{timestamp}-{uuid-prefix}`
+     * Generates a unique run identifier.
+     * @returns Run ID in format: `{timestamp}-{uuid-prefix}`
      */
-    generateArtifactId() {
+    generateRunId() {
         return Workspace.generateId();
     }
     /**
-     * Returns the staging directory path for an artifact.
-     * Staging is used for temporary writes during execution.
-     * @param artifactId - Artifact identifier
+     * Returns the staging directory path for a run.
+     * @param runId - Run identifier
      * @returns Absolute path to staging directory
-     * @throws If artifact ID is invalid
      */
-    stagingPath(artifactId) {
-        this.validateArtifactId(artifactId);
-        return join(this.root, 'staging', artifactId);
+    runStagingPath(runId) {
+        this.validateRunId(runId);
+        return join(this.root, 'staging', runId);
+    }
+    /**
+     * Returns the staging artifacts directory path for a run.
+     * @param runId - Run identifier
+     * @returns Absolute path to staging artifacts directory
+     */
+    runStagingArtifactsPath(runId) {
+        return join(this.runStagingPath(runId), 'artifacts');
+    }
+    /**
+     * Returns the committed run directory path.
+     * @param runId - Run identifier
+     * @returns Absolute path to run directory
+     */
+    runPath(runId) {
+        this.validateRunId(runId);
+        return join(this.root, 'runs', runId);
     }
     /**
-     * Returns the committed artifact directory path.
-     * Artifacts are immutable once committed.
-     * @param artifactId - Artifact identifier
-     * @returns Absolute path to artifact directory
-     * @throws If artifact ID is invalid
+     * Returns the artifacts directory path within a committed run.
+     * @param runId - Run identifier
+     * @returns Absolute path to run artifacts directory
      */
-    artifactPath(artifactId) {
-        this.validateArtifactId(artifactId);
-        return join(this.root, 'artifacts', artifactId);
+    runArtifactsPath(runId) {
+        return join(this.runPath(runId), 'artifacts');
     }
     /**
-     * Prepares a staging directory for a new artifact.
-     * @param artifactId - Artifact identifier
+     * Prepares a staging directory for a new run.
+     * Creates both the run directory and its artifacts subdirectory.
+     * @param runId - Run identifier
      * @returns Absolute path to the created staging directory
      */
-    async prepareArtifact(artifactId) {
-        const path = this.stagingPath(artifactId);
-        await mkdir(path, { recursive: true });
-        return path;
+    async prepareRun(runId) {
+        try {
+            const path = this.runStagingPath(runId);
+            await mkdir(path, { recursive: true });
+            await mkdir(join(path, 'artifacts'), { recursive: true });
+            return path;
+        }
+        catch (error) {
+            throw new StagingError(`Failed to prepare run ${runId}`, { cause: error });
+        }
     }
     /**
-     * Commits a staging artifact to the artifacts directory.
+     * Commits a staging run to the runs directory.
      * Uses atomic rename operation for consistency.
-     * @param artifactId - Artifact identifier
+     * @param runId - Run identifier
      */
-    async commitArtifact(artifactId) {
-        await rename(this.stagingPath(artifactId), this.artifactPath(artifactId));
+    async commitRun(runId) {
+        try {
+            await rename(this.runStagingPath(runId), this.runPath(runId));
+        }
+        catch (error) {
+            throw new StagingError(`Failed to commit run ${runId}`, { cause: error });
+        }
     }
     /**
-     * Creates a symlink from `step-artifacts/{stepId}` to the committed artifact.
+     * Creates a symlink from `step-runs/{stepId}` to the committed run.
      * Replaces any existing symlink for the same step.
      * @param stepId - Step identifier
-     * @param artifactId - Committed artifact identifier
+     * @param runId - Committed run identifier
      */
-    async linkArtifact(stepId, artifactId) {
-        const dir = join(this.root, 'step-artifacts');
+    async linkRun(stepId, runId) {
+        const dir = join(this.root, 'step-runs');
         await mkdir(dir, { recursive: true });
         const linkPath = join(dir, stepId);
         await rm(linkPath, { force: true });
-        await symlink(join('..', 'artifacts', artifactId), linkPath);
+        await symlink(join('..', 'runs', runId), linkPath);
     }
     /**
-     * Discards a staging artifact (on execution failure).
-     * @param artifactId - Artifact identifier
+     * Discards a staging run (on execution failure).
+     * @param runId - Run identifier
      */
-    async discardArtifact(artifactId) {
-        await rm(this.stagingPath(artifactId), { recursive: true, force: true });
+    async discardRun(runId) {
+        try {
+            await rm(this.runStagingPath(runId), { recursive: true, force: true });
+        }
+        catch (error) {
+            throw new StagingError(`Failed to discard run ${runId}`, { cause: error });
+        }
     }
     /**
      * Removes all staging directories.
-     * Should be called on workspace initialization to clean up incomplete artifacts.
+     * Should be called on workspace initialization to clean up incomplete runs.
      */
     async cleanupStaging() {
         const stagingDir = join(this.root, 'staging');
@@ -198,18 +232,34 @@ export class Workspace {
         }
     }
     /**
-     * Lists all committed artifact IDs in this workspace.
-     * @returns Array of artifact IDs (directory names in artifacts/)
+     * Lists all committed run IDs in this workspace.
+     * @returns Array of run IDs (directory names in runs/)
      */
-    async listArtifacts() {
+    async listRuns() {
         try {
-            const entries = await readdir(join(this.root, 'artifacts'), { withFileTypes: true });
+            const entries = await readdir(join(this.root, 'runs'), { withFileTypes: true });
             return entries.filter(e => e.isDirectory()).map(e => e.name);
         }
         catch {
             return [];
         }
     }
+    /**
+     * Removes runs not in the given set of active run IDs.
+     * @param activeRunIds - Set of run IDs to keep
+     * @returns Number of runs removed
+     */
+    async pruneRuns(activeRunIds) {
+        const allRuns = await this.listRuns();
+        let removed = 0;
+        for (const runId of allRuns) {
+            if (!activeRunIds.has(runId)) {
+                await rm(join(this.root, 'runs', runId), { recursive: true, force: true });
+                removed++;
+            }
+        }
+        return removed;
+    }
     /**
      * Returns the cache directory path.
      * Caches are persistent read-write directories shared across steps.
@@ -246,32 +296,80 @@ export class Workspace {
         }
     }
     /**
-     * Validates an artifact ID to prevent path traversal attacks.
-     * @param id - Artifact identifier to validate
-     * @throws If the artifact ID contains invalid characters or path traversal attempts
+     * Marks a step as currently running by writing a marker file.
+     * @param stepId - Step identifier
+     * @param meta - Metadata about the running step
+     */
+    async markStepRunning(stepId, meta) {
+        const dir = join(this.root, 'running');
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, stepId), JSON.stringify(meta), 'utf8');
+    }
+    /**
+     * Removes the running marker for a step.
+     * @param stepId - Step identifier
+     */
+    async markStepDone(stepId) {
+        await rm(join(this.root, 'running', stepId), { force: true });
+    }
+    /**
+     * Lists all steps currently marked as running.
+     * @returns Array of running step metadata
+     */
+    async listRunningSteps() {
+        const dir = join(this.root, 'running');
+        try {
+            const entries = await readdir(dir);
+            const results = [];
+            for (const entry of entries) {
+                try {
+                    const content = await readFile(join(dir, entry), 'utf8');
+                    const meta = JSON.parse(content);
+                    results.push({ stepId: entry, ...meta });
+                }
+                catch {
+                    // Ignore malformed entries
+                }
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Removes all running markers.
+     */
+    async cleanupRunning() {
+        await rm(join(this.root, 'running'), { recursive: true, force: true });
+    }
+    /**
+     * Validates a run ID to prevent path traversal attacks.
+     * @param id - Run identifier to validate
+     * @throws If the run ID contains invalid characters or path traversal attempts
      * @internal
      */
-    validateArtifactId(id) {
+    validateRunId(id) {
         if (!/^[\w-]+$/.test(id)) {
-            throw new Error(`Invalid artifact ID: ${id}. Must contain only alphanumeric characters, dashes, and underscores.`);
+            throw new WorkspaceError('INVALID_RUN_ID', `Invalid run ID: ${id}. Must contain only alphanumeric characters, dashes, and underscores.`);
         }
         if (id.includes('..')) {
-            throw new Error(`Invalid artifact ID: ${id}. Path traversal is not allowed.`);
+            throw new WorkspaceError('INVALID_RUN_ID', `Invalid run ID: ${id}. Path traversal is not allowed.`);
         }
     }
     /**
      * Validates a cache name to prevent path traversal attacks.
-     * Same rules as artifact IDs: alphanumeric, dashes, underscores only.
+     * Same rules as run IDs: alphanumeric, dashes, underscores only.
      * @param name - Cache name to validate
      * @throws If the cache name contains invalid characters or path traversal attempts
      * @internal
      */
     validateCacheName(name) {
         if (!/^[\w-]+$/.test(name)) {
-            throw new Error(`Invalid cache name: ${name}. Must contain only alphanumeric characters, dashes, and underscores.`);
+            throw new WorkspaceError('INVALID_CACHE_NAME', `Invalid cache name: ${name}. Must contain only alphanumeric characters, dashes, and underscores.`);
         }
         if (name.includes('..')) {
-            throw new Error(`Invalid cache name: ${name}. Path traversal is not allowed.`);
+            throw new WorkspaceError('INVALID_CACHE_NAME', `Invalid cache name: ${name}. Path traversal is not allowed.`);
         }
     }
 }

package/dist/errors.js

@@ -0,0 +1,122 @@
+export class PipexError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'PipexError';
+    }
+    get transient() {
+        return false;
+    }
+}
+// -- Docker errors -----------------------------------------------------------
+export class DockerError extends PipexError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'DockerError';
+    }
+}
+export class DockerNotAvailableError extends DockerError {
+    constructor(options) {
+        super('DOCKER_NOT_AVAILABLE', 'Docker CLI not found. Please install Docker.', options);
+        this.name = 'DockerNotAvailableError';
+    }
+    get transient() {
+        return true;
+    }
+}
+export class ImagePullError extends DockerError {
+    constructor(image, options) {
+        super('IMAGE_PULL_FAILED', `Failed to pull image "${image}"`, options);
+        this.name = 'ImagePullError';
+    }
+    get transient() {
+        return true;
+    }
+}
+export class ContainerTimeoutError extends DockerError {
+    constructor(timeoutSec, options) {
+        super('CONTAINER_TIMEOUT', `Container exceeded timeout of ${timeoutSec}s`, options);
+        this.name = 'ContainerTimeoutError';
+    }
+}
+export class ContainerCrashError extends DockerError {
+    stepId;
+    exitCode;
+    constructor(stepId, exitCode, options) {
+        super('CONTAINER_CRASH', `Step ${stepId} failed with exit code ${exitCode}`, options);
+        this.stepId = stepId;
+        this.exitCode = exitCode;
+        this.name = 'ContainerCrashError';
+    }
+}
+export class ContainerCleanupError extends DockerError {
+    constructor(options) {
+        super('CONTAINER_CLEANUP_FAILED', 'Failed to clean up container', options);
+        this.name = 'ContainerCleanupError';
+    }
+}
+// -- Workspace errors --------------------------------------------------------
+export class WorkspaceError extends PipexError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'WorkspaceError';
+    }
+}
+export class ArtifactNotFoundError extends WorkspaceError {
+    constructor(message, options) {
+        super('ARTIFACT_NOT_FOUND', message, options);
+        this.name = 'ArtifactNotFoundError';
+    }
+}
+export class StagingError extends WorkspaceError {
+    constructor(message, options) {
+        super('STAGING_FAILED', message, options);
+        this.name = 'StagingError';
+    }
+}
+// -- Pipeline errors ---------------------------------------------------------
+export class PipelineError extends PipexError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'PipelineError';
+    }
+}
+export class ValidationError extends PipelineError {
+    constructor(message, options) {
+        super('VALIDATION_ERROR', message, options);
+        this.name = 'ValidationError';
+    }
+}
+export class CyclicDependencyError extends PipelineError {
+    constructor(message, options) {
+        super('CYCLIC_DEPENDENCY', message, options);
+        this.name = 'CyclicDependencyError';
+    }
+}
+export class StepNotFoundError extends PipelineError {
+    constructor(stepId, referencedStep, options) {
+        super('STEP_NOT_FOUND', `Step ${stepId}: input step '${referencedStep}' not found or not yet executed`, options);
+        this.name = 'StepNotFoundError';
+    }
+}
+// -- Bundle errors -----------------------------------------------------------
+export class BundleError extends PipexError {
+    constructor(message, options) {
+        super('BUNDLE_ERROR', message, options);
+        this.name = 'BundleError';
+    }
+}
+// -- Kit errors --------------------------------------------------------------
+export class KitError extends PipexError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'KitError';
+    }
+}
+export class MissingParameterError extends KitError {
+    constructor(kitName, paramName, options) {
+        super('MISSING_PARAMETER', `Kit "${kitName}": "${paramName}" parameter is required`, options);
+        this.name = 'MissingParameterError';
+    }
+}

package/dist/index.js

@@ -38,3 +38,6 @@
  */
 // Export engine layer for programmatic use
 export { Workspace, ContainerExecutor, DockerCliExecutor } from './engine/index.js';
+// Export core layer for pipeline orchestration
+export { PipelineRunner, StepRunner, PipelineLoader, StateManager, ConsoleReporter, StreamReporter, CompositeReporter, InMemoryTransport, EventAggregator, buildGraph, topologicalLevels, subgraph, leafNodes, evaluateCondition, dirSize, formatSize, formatDuration } from './core/index.js';
+export { PipexError, DockerError, DockerNotAvailableError, ImagePullError, ContainerTimeoutError, ContainerCrashError, ContainerCleanupError, WorkspaceError, ArtifactNotFoundError, StagingError, PipelineError, ValidationError, CyclicDependencyError, StepNotFoundError, KitError, MissingParameterError } from './errors.js';

package/dist/kits/__tests__/index.js

@@ -0,0 +1,23 @@
+import test from 'ava';
+import { KitError } from '../../errors.js';
+import { getKit } from '../index.js';
+test('getKit returns node kit', t => {
+    const kit = getKit('node');
+    t.is(kit.name, 'node');
+});
+test('getKit returns python kit', t => {
+    const kit = getKit('python');
+    t.is(kit.name, 'python');
+});
+test('getKit returns shell kit', t => {
+    const kit = getKit('shell');
+    t.is(kit.name, 'shell');
+});
+test('getKit throws KitError on unknown kit with available list', t => {
+    const error = t.throws(() => getKit('unknown'));
+    t.true(error instanceof KitError);
+    t.truthy(error?.message.includes('Unknown kit'));
+    t.truthy(error?.message.includes('node'));
+    t.truthy(error?.message.includes('python'));
+    t.truthy(error?.message.includes('shell'));
+});

package/dist/kits/builtin/__tests__/node.js

@@ -0,0 +1,74 @@
+import test from 'ava';
+import { KitError, MissingParameterError } from '../../../errors.js';
+import { nodeKit } from '../node.js';
+test('resolve with minimal params (script only)', t => {
+    const result = nodeKit.resolve({ script: 'index.js' });
+    t.is(result.image, 'node:24-alpine');
+    t.truthy(result.cmd[2].includes('node /app/index.js'));
+    t.is(result.sources, undefined);
+});
+test('resolve uses default version and variant', t => {
+    const result = nodeKit.resolve({ script: 'app.js' });
+    t.is(result.image, 'node:24-alpine');
+});
+test('resolve with npm package manager', t => {
+    const result = nodeKit.resolve({ script: 'app.js', packageManager: 'npm' });
+    t.truthy(result.cmd[2].includes('cd /app && npm install'));
+    t.deepEqual(result.caches, [{ name: 'npm-cache', path: '/root/.npm' }]);
+});
+test('resolve with pnpm package manager', t => {
+    const result = nodeKit.resolve({ script: 'app.js', packageManager: 'pnpm' });
+    t.truthy(result.cmd[2].includes('pnpm install'));
+    t.deepEqual(result.caches, [{ name: 'pnpm-store', path: '/root/.local/share/pnpm/store' }]);
+});
+test('resolve with yarn package manager', t => {
+    const result = nodeKit.resolve({ script: 'app.js', packageManager: 'yarn' });
+    t.truthy(result.cmd[2].includes('yarn install'));
+    t.deepEqual(result.caches, [{ name: 'yarn-cache', path: '/usr/local/share/.cache/yarn' }]);
+});
+test('resolve with install=false skips install command', t => {
+    const result = nodeKit.resolve({ script: 'app.js', install: false });
+    t.falsy(result.cmd[2].includes('npm install'));
+    t.truthy(result.cmd[2].includes('node /app/app.js'));
+});
+test('resolve with src adds source', t => {
+    const result = nodeKit.resolve({ script: 'app.js', src: 'myapp' });
+    t.deepEqual(result.sources, [{ host: 'myapp', container: '/app' }]);
+    t.is(result.mounts, undefined);
+});
+test('resolve sets allowNetwork to true', t => {
+    const result = nodeKit.resolve({ script: 'app.js' });
+    t.true(result.allowNetwork);
+});
+test('resolve throws KitError on unsupported packageManager', t => {
+    const error = t.throws(() => nodeKit.resolve({ script: 'app.js', packageManager: 'bun' }), {
+        message: /unsupported packageManager/
+    });
+    t.true(error instanceof KitError);
+});
+test('resolve throws MissingParameterError without script or run', t => {
+    const error = t.throws(() => nodeKit.resolve({}), { message: /required/i });
+    t.true(error instanceof MissingParameterError);
+});
+test('resolve throws KitError when both script and run are provided', t => {
+    const error = t.throws(() => nodeKit.resolve({ script: 'app.js', run: 'npm run build' }), {
+        message: /mutually exclusive/
+    });
+    t.true(error instanceof KitError);
+});
+// -- run parameter ------------------------------------------------------------
+test('resolve with run uses the command directly', t => {
+    const result = nodeKit.resolve({ run: 'npm run build --prefix /app' });
+    t.truthy(result.cmd[2].includes('npm run build --prefix /app'));
+    t.falsy(result.cmd[2].includes('node /app/'));
+});
+test('resolve with run still runs install by default', t => {
+    const result = nodeKit.resolve({ run: 'npx eslint /app/src' });
+    t.truthy(result.cmd[2].includes('npm install'));
+    t.truthy(result.cmd[2].includes('npx eslint /app/src'));
+});
+test('resolve with run and install=false skips install', t => {
+    const result = nodeKit.resolve({ run: 'node --version', install: false });
+    t.falsy(result.cmd[2].includes('npm install'));
+    t.is(result.cmd[2], 'node --version');
+});

package/dist/kits/builtin/__tests__/python.js

@@ -0,0 +1,67 @@
+import test from 'ava';
+import { KitError, MissingParameterError } from '../../../errors.js';
+import { pythonKit } from '../python.js';
+test('resolve with minimal params (script only)', t => {
+    const result = pythonKit.resolve({ script: 'main.py' });
+    t.is(result.image, 'python:3.12-slim');
+    t.truthy(result.cmd[2].includes('python /app/main.py'));
+});
+test('resolve uses default version and variant', t => {
+    const result = pythonKit.resolve({ script: 'app.py' });
+    t.is(result.image, 'python:3.12-slim');
+});
+test('resolve with pip package manager', t => {
+    const result = pythonKit.resolve({ script: 'app.py', packageManager: 'pip' });
+    t.truthy(result.cmd[2].includes('pip install'));
+    t.deepEqual(result.caches, [{ name: 'pip-cache', path: '/root/.cache/pip' }]);
+});
+test('resolve with uv package manager', t => {
+    const result = pythonKit.resolve({ script: 'app.py', packageManager: 'uv' });
+    t.truthy(result.cmd[2].includes('uv pip install'));
+    t.deepEqual(result.caches, [{ name: 'uv-cache', path: '/root/.cache/uv' }]);
+});
+test('resolve with install=false skips install command', t => {
+    const result = pythonKit.resolve({ script: 'app.py', install: false });
+    t.falsy(result.cmd[2].includes('pip install'));
+    t.truthy(result.cmd[2].includes('python /app/app.py'));
+});
+test('resolve with src adds mount', t => {
+    const result = pythonKit.resolve({ script: 'app.py', src: 'myproject' });
+    t.deepEqual(result.mounts, [{ host: 'myproject', container: '/app' }]);
+});
+test('resolve sets allowNetwork to true', t => {
+    const result = pythonKit.resolve({ script: 'app.py' });
+    t.true(result.allowNetwork);
+});
+test('resolve throws KitError on unsupported packageManager', t => {
+    const error = t.throws(() => pythonKit.resolve({ script: 'app.py', packageManager: 'conda' }), {
+        message: /unsupported packageManager/
+    });
+    t.true(error instanceof KitError);
+});
+test('resolve throws MissingParameterError without script or run', t => {
+    const error = t.throws(() => pythonKit.resolve({}), { message: /required/i });
+    t.true(error instanceof MissingParameterError);
+});
+test('resolve throws KitError when both script and run are provided', t => {
+    const error = t.throws(() => pythonKit.resolve({ script: 'app.py', run: 'pytest /app/tests' }), {
+        message: /mutually exclusive/
+    });
+    t.true(error instanceof KitError);
+});
+// -- run parameter ------------------------------------------------------------
+test('resolve with run uses the command directly', t => {
+    const result = pythonKit.resolve({ run: 'pytest /app/tests -v' });
+    t.truthy(result.cmd[2].includes('pytest /app/tests -v'));
+    t.falsy(result.cmd[2].includes('python /app/'));
+});
+test('resolve with run still runs install by default', t => {
+    const result = pythonKit.resolve({ run: 'pytest /app/tests' });
+    t.truthy(result.cmd[2].includes('pip install'));
+    t.truthy(result.cmd[2].includes('pytest /app/tests'));
+});
+test('resolve with run and install=false skips install', t => {
+    const result = pythonKit.resolve({ run: 'python --version', install: false });
+    t.falsy(result.cmd[2].includes('pip install'));
+    t.is(result.cmd[2], 'python --version');
+});