toolcraft 0.0.12 → 0.0.13

package/node_modules/@poe-code/process-runner/README.md

@@ -0,0 +1,41 @@
+# @poe-code/process-runner
+
+Low-level process execution abstraction. Single interface for launching processes on the host or inside Docker containers.
+
+## Overview
+
+- No external dependencies
+- Consumed by `@poe-code/agent-spawn`
+- Consumed by `process-launcher`
+
+## Host Factory
+
+- `createHostRunner(options)` returns a `Runner` that launches commands with `node:child_process.spawn`.
+- `options.detached` starts the child as a detached process and uses process-group kill on Unix.
+- `hostExecutionEnvFactory` implements the shared execution environment contract for local host execution.
+- Host environments do not upload, download, detach, or reattach because the caller workspace is already local and there is no addressable remote environment.
+
+## Docker Factories
+
+- `createDockerRunner(options)` returns a one-shot `Runner` that executes each command in a Docker or Podman container.
+- `dockerExecutionEnvFactory` creates an addressable long-lived container environment for Poe Code runtime jobs.
+- Docker environments support workspace upload/download, command execution, interactive shell, detach, attach, and cleanup.
+
+`DockerRunnerOptions`:
+
+- `image`: container image to run.
+- `engine`: `docker` or `podman`; detected when omitted.
+- `context`: Docker context name; detected when omitted.
+- `mounts`: container mounts.
+- `ports`: port mappings.
+- `network`: Docker network.
+- `extraArgs`: additional runtime arguments.
+- `containerName`: optional container name prefix.
+
+## Environment variables
+
+This package exposes no environment variables.
+
+## Configuration
+
+This package currently exposes no package-level configuration options.

package/node_modules/@poe-code/process-runner/dist/docker/args.d.ts

@@ -0,0 +1,2 @@
+import type { DockerRunArgs } from "../types.js";
+export declare function buildDockerRunArgs(input: DockerRunArgs): string[];

package/node_modules/@poe-code/process-runner/dist/docker/args.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+export function buildDockerRunArgs(input) {
+    const args = [input.engine];
+    if (input.engine === "docker" && input.context) {
+        args.push("--context", input.context);
+    }
+    args.push("run");
+    if (input.rm) {
+        args.push("--rm");
+    }
+    if (input.detached) {
+        args.push("-d");
+    }
+    if (input.interactive) {
+        args.push("-i");
+    }
+    if (input.tty) {
+        args.push("-t");
+    }
+    args.push("--name", input.containerName);
+    if (input.cwd !== undefined) {
+        args.push("-w", input.cwd);
+    }
+    for (const [key, value] of Object.entries(input.env ?? {})) {
+        args.push("-e", `${key}=${value}`);
+    }
+    for (const mount of input.mounts) {
+        const volume = `${path.resolve(mount.source)}:${mount.target}${mount.readonly ? ":ro" : ""}`;
+        args.push("-v", volume);
+    }
+    for (const port of input.ports) {
+        const mapping = `${port.host}:${port.container}${port.protocol === undefined || port.protocol === "tcp" ? "" : `/${port.protocol}`}`;
+        args.push("-p", mapping);
+    }
+    if (input.network !== undefined) {
+        args.push("--network", input.network);
+    }
+    args.push(...input.extraArgs, input.image, input.command, ...input.args);
+    return args;
+}

package/node_modules/@poe-code/process-runner/dist/docker/context.d.ts

@@ -0,0 +1,3 @@
+import type { Engine } from "../types.js";
+export declare function detectContext(): string | null;
+export declare function buildContextArgs(engine: Engine, context: string | null): string[];

package/node_modules/@poe-code/process-runner/dist/docker/context.js

@@ -0,0 +1,30 @@
+import { execSync } from "node:child_process";
+export function detectContext() {
+    try {
+        const output = execSync("colima list --json", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "ignore"]
+        });
+        const lines = output.trim().split("\n").filter(Boolean);
+        for (const line of lines) {
+            const profile = JSON.parse(line);
+            if (profile.status === "Running" && profile.runtime === "docker") {
+                const name = profile.name ?? profile.profile;
+                if (!name) {
+                    continue;
+                }
+                return name === "default" ? "colima" : `colima-${name}`;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export function buildContextArgs(engine, context) {
+    if (engine === "docker" && context) {
+        return ["--context", context];
+    }
+    return [];
+}

package/node_modules/@poe-code/process-runner/dist/docker/docker-execution-env.d.ts

@@ -0,0 +1,28 @@
+import type { DockerMount, Engine, ExecutionState, ExecutionEnvFactory, Runner } from "../types.js";
+interface DockerRuntime {
+    type: "docker";
+    image?: string;
+    dockerfile?: string;
+    build_context?: string;
+    build_args?: Record<string, string>;
+    mounts?: DockerMount[];
+    engine?: Engine;
+    network?: string;
+    extra_args?: string[];
+}
+export interface BuildDockerRuntimeTemplateInput {
+    cwd: string;
+    runtime: DockerRuntime;
+    state?: ExecutionState;
+    runner?: Runner;
+    force?: boolean;
+}
+export interface BuildDockerRuntimeTemplateResult {
+    backend: "docker";
+    hash: string;
+    image: string;
+    cached: boolean;
+}
+export declare const dockerExecutionEnvFactory: ExecutionEnvFactory;
+export declare function buildDockerRuntimeTemplate(input: BuildDockerRuntimeTemplateInput): Promise<BuildDockerRuntimeTemplateResult>;
+export {};

package/node_modules/@poe-code/process-runner/dist/docker/docker-execution-env.js

@@ -0,0 +1,428 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { buildDockerRunArgs } from "./args.js";
+import { buildContextArgs, detectContext } from "./context.js";
+import { detectEngine } from "./engine.js";
+import { createHostRunner } from "../host/host-runner.js";
+const containerCommand = ["sh", "-c", "while :; do sleep 3600; done"];
+export const dockerExecutionEnvFactory = {
+    type: "docker",
+    supportsDetach: true,
+    async open(spec) {
+        const runtime = parseDockerRuntime(spec.runtime);
+        const runner = spec.hostRunner ?? createHostRunner();
+        const engine = runtime.engine ?? detectEngine();
+        const context = detectContext();
+        const image = await resolveImage({
+            spec,
+            runtime,
+            runner,
+            engine,
+            context
+        });
+        const containerName = createContainerName();
+        const runArgs = buildDockerRunArgs({
+            engine,
+            context,
+            image,
+            command: containerCommand[0],
+            args: containerCommand.slice(1),
+            cwd: undefined,
+            env: undefined,
+            mounts: runtime.mounts ?? [],
+            ports: [],
+            network: runtime.network,
+            containerName,
+            detached: true,
+            interactive: true,
+            tty: false,
+            rm: false,
+            extraArgs: runtime.extra_args ?? []
+        });
+        const [command, ...args] = runArgs;
+        const id = (await runAndRead(runner, { command, args, stdout: "pipe", stderr: "pipe" })).trim();
+        return createDockerEnv({
+            id,
+            spec,
+            runner,
+            engine,
+            context
+        });
+    },
+    async attach(envId, context) {
+        const engine = detectEngine();
+        return createDockerEnv({
+            id: envId,
+            spec: createAttachedSpec(context?.cwd),
+            runner: createHostRunner(),
+            engine,
+            context: detectContext(),
+            attachedJobId: context?.jobId
+        });
+    }
+};
+function createDockerEnv(input) {
+    const containerRef = input.id;
+    return {
+        id: containerRef,
+        job: input.attachedJobId === undefined
+            ? null
+            : createContainerJob(containerRef, input.runner, input.engine, input.context, input.attachedJobId),
+        async uploadWorkspace() {
+            const tempDir = mkdtempSync(path.join(tmpdir(), "poe-docker-upload-"));
+            const archivePath = path.join(tempDir, "workspace.tar");
+            try {
+                const excludeArgs = input.spec.uploadIgnoreFiles.flatMap((ignored) => [
+                    "--exclude",
+                    ignored
+                ]);
+                const tarArgs = [...excludeArgs, "-cf", archivePath, "-C", input.spec.cwd, "."];
+                await runOrThrow(input.runner, {
+                    command: "tar",
+                    args: tarArgs,
+                    stdout: "pipe",
+                    stderr: "pipe"
+                });
+                await runOrThrow(input.runner, {
+                    command: input.engine,
+                    args: [
+                        ...buildContextArgs(input.engine, input.context),
+                        "cp",
+                        archivePath,
+                        `${containerRef}:/tmp/poe-workspace-upload.tar`
+                    ],
+                    stdout: "pipe",
+                    stderr: "pipe"
+                });
+                await runOrThrow(input.runner, {
+                    command: input.engine,
+                    args: [
+                        ...buildContextArgs(input.engine, input.context),
+                        "exec",
+                        containerRef,
+                        "sh",
+                        "-c",
+                        `mkdir -p ${shellQuote(input.spec.cwd)} && tar -xf /tmp/poe-workspace-upload.tar -C ${shellQuote(input.spec.cwd)}`
+                    ],
+                    stdout: "pipe",
+                    stderr: "pipe"
+                });
+                return { files: 0, bytes: 0, skipped: [] };
+            }
+            finally {
+                rmSync(tempDir, { recursive: true, force: true });
+            }
+        },
+        async downloadWorkspace(opts) {
+            const tempDir = mkdtempSync(path.join(tmpdir(), "poe-docker-download-"));
+            const archivePath = path.join(tempDir, "workspace.tar");
+            try {
+                await runOrThrow(input.runner, {
+                    command: input.engine,
+                    args: [
+                        ...buildContextArgs(input.engine, input.context),
+                        "exec",
+                        containerRef,
+                        "sh",
+                        "-c",
+                        `tar -cf /tmp/poe-workspace-download.tar -C ${shellQuote(input.spec.cwd)} .`
+                    ],
+                    stdout: "pipe",
+                    stderr: "pipe"
+                });
+                await runOrThrow(input.runner, {
+                    command: input.engine,
+                    args: [
+                        ...buildContextArgs(input.engine, input.context),
+                        "cp",
+                        `${containerRef}:/tmp/poe-workspace-download.tar`,
+                        archivePath
+                    ],
+                    stdout: "pipe",
+                    stderr: "pipe"
+                });
+                const extractMode = opts.conflictPolicy === "refuse" ? "-xkf" : "-xf";
+                await runOrThrow(input.runner, {
+                    command: "tar",
+                    args: [extractMode, archivePath, "-C", input.spec.cwd],
+                    stdout: "pipe",
+                    stderr: "pipe"
+                });
+                return { files: 0, bytes: 0, conflicts: [] };
+            }
+            finally {
+                rmSync(tempDir, { recursive: true, force: true });
+            }
+        },
+        exec(spec) {
+            return input.runner.exec({
+                command: input.engine,
+                args: [
+                    ...buildContextArgs(input.engine, input.context),
+                    "exec",
+                    ...(spec.stdin === "pipe" || spec.stdin === "inherit" ? ["-i"] : []),
+                    ...(spec.tty === true ? ["-t"] : []),
+                    ...(spec.cwd !== undefined ? ["-w", spec.cwd] : []),
+                    ...buildEnvArgs(spec.env),
+                    containerRef,
+                    spec.command,
+                    ...(spec.args ?? [])
+                ],
+                stdin: spec.stdin,
+                stdout: spec.stdout,
+                stderr: spec.stderr,
+                tty: spec.tty
+            });
+        },
+        async detach() {
+            return createContainerJob(containerRef, input.runner, input.engine, input.context);
+        },
+        shell() {
+            const shellSpec = input.spec.shellSpec;
+            return this.exec({
+                command: shellSpec?.command ?? input.spec.env.SHELL ?? "sh",
+                ...(shellSpec?.args ? { args: shellSpec.args } : {}),
+                cwd: input.spec.cwd,
+                env: shellSpec && "env" in shellSpec ? shellSpec.env : input.spec.env,
+                stdin: "inherit",
+                stdout: "inherit",
+                stderr: "inherit",
+                tty: true
+            });
+        },
+        async close() {
+            await runOrThrow(input.runner, {
+                command: input.engine,
+                args: [...buildContextArgs(input.engine, input.context), "rm", "-f", containerRef],
+                stdout: "pipe",
+                stderr: "pipe"
+            });
+        }
+    };
+}
+async function resolveImage(input) {
+    if (input.runtime.image !== undefined) {
+        return input.runtime.image;
+    }
+    const result = await buildDockerRuntimeTemplate({
+        cwd: input.spec.cwd,
+        runtime: input.runtime,
+        state: input.spec.state,
+        runner: input.runner
+    });
+    return result.image;
+}
+export async function buildDockerRuntimeTemplate(input) {
+    const runner = input.runner ?? createHostRunner();
+    const engine = input.runtime.engine ?? detectEngine();
+    const context = detectContext();
+    const dockerfilePath = path.resolve(input.cwd, input.runtime.dockerfile ?? path.join(".poe-code", "Dockerfile"));
+    const buildContext = path.resolve(input.cwd, input.runtime.build_context ?? ".");
+    const dockerfileBytes = await readFile(dockerfilePath);
+    const hash = hashDockerTemplate(dockerfileBytes, input.runtime.build_args ?? {});
+    const cached = input.force ? null : await input.state?.templates.get("docker", hash);
+    if (cached?.image !== undefined) {
+        return {
+            backend: "docker",
+            hash,
+            image: cached.image,
+            cached: true
+        };
+    }
+    const image = `poe-code/local:${hash}`;
+    await buildImage({
+        runner,
+        engine,
+        context,
+        image,
+        dockerfilePath,
+        buildContext,
+        buildArgs: input.runtime.build_args ?? {}
+    });
+    await input.state?.templates.put("docker", {
+        hash,
+        image,
+        runtime_type: "docker",
+        dockerfile_path: dockerfilePath,
+        built_at: new Date().toISOString()
+    });
+    return {
+        backend: "docker",
+        hash,
+        image,
+        cached: false
+    };
+}
+function hashDockerTemplate(dockerfileBytes, buildArgs) {
+    const hash = createHash("sha256");
+    hash.update(dockerfileBytes);
+    hash.update("\0");
+    for (const [key, value] of sortedBuildArgs(buildArgs)) {
+        hash.update(key);
+        hash.update("=");
+        hash.update(value);
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+async function buildImage(input) {
+    await runOrThrow(input.runner, {
+        command: input.engine,
+        args: [
+            ...buildContextArgs(input.engine, input.context),
+            "build",
+            "--tag",
+            input.image,
+            "-f",
+            input.dockerfilePath,
+            ...sortedBuildArgs(input.buildArgs).flatMap(([key, value]) => [
+                "--build-arg",
+                `${key}=${value}`
+            ]),
+            input.buildContext
+        ],
+        stdout: "pipe",
+        stderr: "pipe"
+    });
+}
+function parseDockerRuntime(runtime) {
+    if (!runtime || typeof runtime !== "object" || Array.isArray(runtime)) {
+        throw new Error("docker runtime must be an object");
+    }
+    const record = runtime;
+    if (record.type !== "docker") {
+        throw new Error('docker runtime type must be "docker"');
+    }
+    return record;
+}
+async function runAndRead(runner, spec) {
+    const handle = runner.exec(spec);
+    const stdout = readStream(handle.stdout);
+    const stderr = readStream(handle.stderr);
+    const result = await handle.result;
+    const output = await stdout;
+    if (result.exitCode !== 0) {
+        const errorOutput = await stderr;
+        throw new Error(`Command failed with exit code ${result.exitCode}: ${spec.command} ${(spec.args ?? []).join(" ")}${errorOutput ? `\n${errorOutput}` : ""}`);
+    }
+    return output;
+}
+async function runOrThrow(runner, spec) {
+    await runAndRead(runner, spec);
+}
+async function readStream(stream) {
+    if (stream === null) {
+        return "";
+    }
+    stream.setEncoding("utf8");
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(String(chunk));
+    }
+    return chunks.join("");
+}
+function sortedBuildArgs(buildArgs) {
+    return Object.entries(buildArgs).sort(([left], [right]) => left.localeCompare(right));
+}
+function buildEnvArgs(env) {
+    if (env === undefined) {
+        return [];
+    }
+    return Object.entries(env).flatMap(([key, value]) => ["-e", `${key}=${value}`]);
+}
+function createContainerName() {
+    return `poe-env-${randomBytes(6).toString("hex")}`;
+}
+function createContainerJob(containerId, runner, engine, context, jobId = containerId) {
+    return {
+        id: jobId,
+        envId: containerId,
+        tool: "docker",
+        argv: ["attach", containerId],
+        async status() {
+            const handle = runner.exec({
+                command: engine,
+                args: [
+                    ...buildContextArgs(engine, context),
+                    "inspect",
+                    "-f",
+                    "{{.State.Status}}",
+                    containerId
+                ],
+                stdout: "pipe",
+                stderr: "pipe"
+            });
+            const stdout = await readStream(handle.stdout);
+            const result = await handle.result;
+            if (result.exitCode !== 0) {
+                return "lost";
+            }
+            return stdout.trim() === "running" ? "running" : "exited";
+        },
+        async *stream(opts) {
+            const handle = runner.exec({
+                command: engine,
+                args: [
+                    ...buildContextArgs(engine, context),
+                    "exec",
+                    containerId,
+                    "sh",
+                    "-c",
+                    `test -f ${shellQuote(`/tmp/poe-jobs/${jobId}.log`)} && tail -c +${(opts?.sinceByte ?? 0) + 1} ${shellQuote(`/tmp/poe-jobs/${jobId}.log`)} || true`
+                ],
+                stdout: "pipe",
+                stderr: "pipe"
+            });
+            const stdout = await readStream(handle.stdout);
+            await handle.result;
+            if (stdout.length > 0) {
+                yield { byteOffset: opts?.sinceByte ?? 0, data: stdout };
+            }
+        },
+        async wait() {
+            const handle = runner.exec({
+                command: engine,
+                args: [...buildContextArgs(engine, context), "wait", containerId],
+                stdout: "pipe",
+                stderr: "pipe"
+            });
+            const stdout = await readStream(handle.stdout);
+            const result = await handle.result;
+            return { exitCode: Number.parseInt(stdout.trim(), 10) || result.exitCode };
+        },
+        async kill(signal) {
+            const args = signal === undefined || signal === "SIGTERM"
+                ? ["stop", containerId]
+                : ["kill", ...(signal === "SIGKILL" ? [] : [`--signal=${signal}`]), containerId];
+            await runOrThrow(runner, {
+                command: engine,
+                args: [...buildContextArgs(engine, context), ...args],
+                stdout: "pipe",
+                stderr: "pipe"
+            });
+        }
+    };
+}
+function createAttachedSpec(cwd = "/workspace") {
+    return {
+        cwd,
+        runtime: {
+            type: "docker",
+            image: "attached",
+            build_args: {},
+            mounts: []
+        },
+        env: {},
+        uploadIgnoreFiles: [],
+        jobLabel: {
+            tool: "docker",
+            argv: []
+        }
+    };
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/node_modules/@poe-code/process-runner/dist/docker/docker-runner.d.ts

@@ -0,0 +1,2 @@
+import type { DockerRunnerOptions, Runner } from "../types.js";
+export declare function createDockerRunner(options: DockerRunnerOptions): Runner;