@crewhaus/tool-media 0.7.0

package/dist/paths.d.ts

@@ -0,0 +1,53 @@
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export declare class ToolPermissionError extends CrewhausError {
+    readonly name = "ToolPermissionError";
+    readonly toolName: string;
+    readonly path: string;
+    constructor(toolName: string, attemptedPath: string);
+}
+/**
+ * A validated path, in both forms the tools need.
+ *
+ * `real` has every in-workspace symlink already resolved and is what I/O
+ * should use — operating on it closes most of the check-to-use window.
+ * `abs` is the lexical resolution, which is what a tool must use when the
+ * question is about the link ITSELF (`Stat` reporting a symlink target,
+ * `RemovePath` deleting a link rather than its destination).
+ */
+export type SafePath = {
+    readonly abs: string;
+    readonly real: string;
+    /** The path as the caller wrote it, for echoing back in results. */
+    readonly given: string;
+    /** Slash-separated path relative to the workspace root. */
+    readonly rel: string;
+};
+/** The workspace root, resolved. Every path is contained within it. */
+export declare function workspaceRoot(): string;
+/**
+ * Resolve `rel` inside the workspace, or throw `ToolPermissionError`.
+ *
+ * The leaf is allowed not to exist — every tool here that creates something
+ * needs to validate a destination before it is made — so the deepest
+ * ancestor that EXISTS AS A NAME is resolved and the missing tail
+ * re-appended. "Exists as a name" rather than "exists": a symlink pointing
+ * at a file that is not there yet is still followed by `open(…, "w")`, so it
+ * is resolved here too rather than treated as a plain missing leaf. Any
+ * failure other than that walk fails closed.
+ */
+export declare function resolveSafe(toolName: string, rel: string, root?: string): SafePath;
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export declare function toPosix(p: string): string;
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export declare function isInside(parent: string, candidate: string): boolean;
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export declare function archiveEntryEscapes(name: string): boolean;

package/dist/paths.js

@@ -0,0 +1,161 @@
+/**
+ * Path containment — the gate every caller-supplied path in this package
+ * passes through before any syscall touches it.
+ *
+ * The approach is the one `@crewhaus/tool-fs` uses, and for the same reasons:
+ * a lexical check alone is fooled by a symlink that lives inside the
+ * workspace and points outside it (CWE-59), so the real path is checked too.
+ * The workspace root is `process.cwd()`, matching tool-fs, so a harness that
+ * trusts one tool's boundary gets the same boundary here.
+ */
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export class ToolPermissionError extends CrewhausError {
+    name = "ToolPermissionError";
+    toolName;
+    path;
+    constructor(toolName, attemptedPath) {
+        super("tool", `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`);
+        this.toolName = toolName;
+        this.path = attemptedPath;
+    }
+}
+/** The workspace root, resolved. Every path is contained within it. */
+export function workspaceRoot() {
+    return path.resolve(process.cwd());
+}
+/**
+ * True when the NAME exists, whether or not it leads anywhere.
+ *
+ * `existsSync` follows symlinks, so it answers false for a link whose target
+ * is missing — and a missing target is exactly the case that matters here: a
+ * dangling link is still a door. `open(…, "w")` through `evil -> /etc/x`
+ * CREATES `/etc/x`. Probing with `lstat` keeps that name in the part of the
+ * path that gets resolved rather than in the "does not exist yet" tail that
+ * is appended to the root verbatim.
+ */
+function nameExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `target` would actually land, with every symlink on the way already
+ * followed — including one whose own target does not exist yet.
+ *
+ * `realpathSync` gives up with ENOENT on a dangling link, which would leave
+ * that link unresolved and let it stand in for a plain missing file. So the
+ * deepest ancestor that exists as a NAME is resolved, a dangling one is
+ * followed a hop by hand, and the components that do not exist are appended.
+ * The result is the path an `open` would create, which is the only path
+ * worth checking containment against.
+ */
+function resolveLocation(target, depth = 0) {
+    if (depth > 40)
+        throw new Error(`symlink chain at "${target}" is too long to resolve`);
+    let probe = target;
+    const tail = [];
+    while (!nameExists(probe)) {
+        tail.unshift(path.basename(probe));
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            break; // reached the filesystem root
+        probe = parent;
+    }
+    let probeReal;
+    try {
+        probeReal = realpathSync(probe);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        // The name is there but `realpath` cannot finish it: a symlink with a
+        // missing target. `readlinkSync` throws EINVAL on anything else, which
+        // fails closed.
+        const link = readlinkSync(probe);
+        // A RELATIVE target resolves against the directory that actually CONTAINS
+        // the link, which is not the link's lexical parent when that parent is
+        // itself reached through a symlink. `<root>/dirlink/x -> ../y` with
+        // `dirlink` pointing out of the root really lands at `<elsewhere>/y`, but
+        // measured from the lexical parent it reads as `<root>/y` — an in-root
+        // path the caller's path does not lead to. So the parent is made real
+        // first. An absolute target ignores the base.
+        const base = realpathSync(path.dirname(probe));
+        probeReal = resolveLocation(path.resolve(base, link), depth + 1);
+    }
+    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+}
+/**
+ * Resolve `rel` inside the workspace, or throw `ToolPermissionError`.
+ *
+ * The leaf is allowed not to exist — every tool here that creates something
+ * needs to validate a destination before it is made — so the deepest
+ * ancestor that EXISTS AS A NAME is resolved and the missing tail
+ * re-appended. "Exists as a name" rather than "exists": a symlink pointing
+ * at a file that is not there yet is still followed by `open(…, "w")`, so it
+ * is resolved here too rather than treated as a plain missing leaf. Any
+ * failure other than that walk fails closed.
+ */
+export function resolveSafe(toolName, rel, root = workspaceRoot()) {
+    const rootResolved = path.resolve(root);
+    const abs = path.resolve(rootResolved, rel);
+    // 1) Lexical containment — rejects `..` and absolute escapes. The trailing
+    //    separator avoids the `/root` vs `/root-sibling` prefix pitfall.
+    if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new ToolPermissionError(toolName, rel);
+    }
+    let real;
+    try {
+        const rootReal = realpathSync(rootResolved);
+        real = resolveLocation(abs);
+        // 2) Symlink-aware containment. The real path must land inside the real
+        //    root, so an in-workspace symlink pointing at /etc is refused here.
+        if (real !== rootReal && !real.startsWith(`${rootReal}${path.sep}`)) {
+            throw new ToolPermissionError(toolName, rel);
+        }
+    }
+    catch (err) {
+        if (err instanceof ToolPermissionError)
+            throw err;
+        throw new ToolPermissionError(toolName, rel);
+    }
+    return {
+        abs,
+        real,
+        given: rel,
+        rel: toPosix(path.relative(rootResolved, abs)),
+    };
+}
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export function toPosix(p) {
+    return path.sep === "/" ? p : p.split(path.sep).join("/");
+}
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export function isInside(parent, candidate) {
+    const p = path.resolve(parent);
+    const c = path.resolve(candidate);
+    return c === p || c.startsWith(`${p}${path.sep}`);
+}
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export function archiveEntryEscapes(name) {
+    const normalized = name.replace(/\\/g, "/");
+    if (normalized.startsWith("/"))
+        return true;
+    if (/^[A-Za-z]:/.test(normalized))
+        return true;
+    return normalized.split("/").some((segment) => segment === "..");
+}

package/dist/proc.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Spawning, with the three properties a process-launching tool in this repo
+ * owes its caller: a deadline it cannot outlive, cooperation with the turn's
+ * `AbortSignal`, and an output cap that bounds MEMORY rather than being
+ * applied after the fact.
+ *
+ * That last one is why this reads the pipes chunk by chunk instead of
+ * `new Response(proc.stdout).text()`: a process that prints a gigabyte must
+ * cost a bounded number of bytes here, and be killed, not buffered and then
+ * measured.
+ *
+ * Arguments are always an argv array, never a shell string, so a file name
+ * containing a space, a quote or a `;` is an argument rather than a command.
+ * Nothing in this package builds a shell line.
+ */
+export type RunResult = {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    /** True when the executable itself could not be found. */
+    readonly missing: boolean;
+    /** True when either stream was cut off at the byte cap. */
+    readonly truncated: boolean;
+};
+export declare const DEFAULT_PROCESS_TIMEOUT_MS = 20000;
+export declare const MAX_PROCESS_TIMEOUT_MS = 120000;
+/** Plenty for structured probe output; a process past it is misbehaving. */
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+export type RunOptions = {
+    readonly cwd: string;
+    readonly timeoutMs: number;
+    readonly maxOutputBytes?: number;
+    readonly signal?: AbortSignal;
+};
+/** Run `argv` to completion, or kill it when the deadline passes. */
+export declare function runProcess(argv: ReadonlyArray<string>, options: RunOptions): Promise<RunResult>;
+/** A one-line description of a failed run, safe to hand back to a caller. */
+export declare function describeFailure(argv: ReadonlyArray<string>, result: RunResult): string;

package/dist/proc.js

@@ -0,0 +1,158 @@
+/**
+ * Spawning, with the three properties a process-launching tool in this repo
+ * owes its caller: a deadline it cannot outlive, cooperation with the turn's
+ * `AbortSignal`, and an output cap that bounds MEMORY rather than being
+ * applied after the fact.
+ *
+ * That last one is why this reads the pipes chunk by chunk instead of
+ * `new Response(proc.stdout).text()`: a process that prints a gigabyte must
+ * cost a bounded number of bytes here, and be killed, not buffered and then
+ * measured.
+ *
+ * Arguments are always an argv array, never a shell string, so a file name
+ * containing a space, a quote or a `;` is an argument rather than a command.
+ * Nothing in this package builds a shell line.
+ */
+export const DEFAULT_PROCESS_TIMEOUT_MS = 20_000;
+export const MAX_PROCESS_TIMEOUT_MS = 120_000;
+/** Plenty for structured probe output; a process past it is misbehaving. */
+export const DEFAULT_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+/** How long a killed process gets to let its pipes reach EOF. */
+const DRAIN_GRACE_MS = 500;
+/**
+ * Read a pipe until it ends, `limit` bytes have arrived, or `stop` resolves.
+ *
+ * That third condition is not decoration. A shell script killed mid-`sleep`
+ * leaves the `sleep` holding the write end of the pipe, so waiting for EOF
+ * waits for a process nobody is going to kill. `stop` fires a short grace
+ * period after the child exits, and the reader is cancelled either way.
+ */
+async function readCapped(stream, limit, stop) {
+    if (stream === null)
+        return { text: "", truncated: false };
+    const reader = stream.getReader();
+    const parts = [];
+    let total = 0;
+    let truncated = false;
+    try {
+        while (true) {
+            const next = await Promise.race([reader.read(), stop]);
+            if (next === "stop") {
+                truncated = true;
+                break;
+            }
+            const { done, value } = next;
+            if (done)
+                break;
+            if (value === undefined)
+                continue;
+            if (total + value.length > limit) {
+                parts.push(value.subarray(0, Math.max(0, limit - total)));
+                total = limit;
+                truncated = true;
+                break;
+            }
+            parts.push(value);
+            total += value.length;
+        }
+    }
+    finally {
+        // Cancelling releases the pipe, so the child sees EPIPE and stops
+        // writing instead of blocking on a reader that has gone away.
+        try {
+            await reader.cancel();
+        }
+        catch {
+            // Already closed.
+        }
+    }
+    const joined = new Uint8Array(total);
+    let at = 0;
+    for (const part of parts) {
+        joined.set(part, at);
+        at += part.length;
+    }
+    return { text: new TextDecoder().decode(joined), truncated };
+}
+/** Run `argv` to completion, or kill it when the deadline passes. */
+export async function runProcess(argv, options) {
+    const limit = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    let proc;
+    try {
+        proc = Bun.spawn([...argv], {
+            cwd: options.cwd,
+            stdout: "pipe",
+            stderr: "pipe",
+            stdin: "ignore",
+            // Passed explicitly rather than inherited: Bun resolves the
+            // executable against the env it is HANDED, and a caller that has
+            // adjusted PATH since the process started expects the new one.
+            env: { ...process.env },
+            // The runtime aborts the turn by firing this signal; Bun forwards it
+            // to the child, so a cancelled turn does not leave a process behind.
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            code: 127,
+            stdout: "",
+            stderr: message,
+            timedOut: false,
+            missing: true,
+            truncated: false,
+        };
+    }
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        try {
+            proc.kill("SIGKILL");
+        }
+        catch {
+            // Already exited between the timer firing and the kill.
+        }
+    }, options.timeoutMs);
+    let stopReading = () => { };
+    const stop = new Promise((resolve) => {
+        stopReading = resolve;
+    });
+    // Reading starts BEFORE the wait on exit: a child that fills its pipe
+    // blocks until somebody drains it, and a deadlock is not a deadline.
+    const stdout = readCapped(proc.stdout, limit, stop);
+    const stderr = readCapped(proc.stderr, limit, stop);
+    let drainTimer;
+    try {
+        const code = await proc.exited;
+        drainTimer = setTimeout(() => stopReading("stop"), DRAIN_GRACE_MS);
+        const [out, err] = await Promise.all([stdout, stderr]);
+        return {
+            code,
+            stdout: out.text,
+            stderr: err.text,
+            timedOut,
+            missing: code === 127 && out.text === "" && err.text === "",
+            truncated: out.truncated || err.truncated,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        if (drainTimer !== undefined)
+            clearTimeout(drainTimer);
+        stopReading("stop");
+    }
+}
+/** A one-line description of a failed run, safe to hand back to a caller. */
+export function describeFailure(argv, result) {
+    const command = argv[0] ?? "";
+    if (result.missing) {
+        return `\`${command}\` is not installed on this machine, so this cannot be done here`;
+    }
+    if (result.timedOut) {
+        return `\`${command}\` was killed for exceeding its timeout`;
+    }
+    const detail = (result.stderr.trim() !== "" ? result.stderr : result.stdout).trim();
+    const clipped = detail.length > 2000 ? `${detail.slice(0, 2000)}…` : detail;
+    return `\`${command}\` exited ${result.code}${clipped === "" ? "" : `: ${clipped}`}`;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@crewhaus/tool-media",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Deterministic media tools: image inspection and transformation, barcode encoding and decoding, chart and diagram rendering, and audio and video probing",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.7.0",
+    "@crewhaus/tool-builder": "0.7.0",
+    "@crewhaus/tool-catalog": "0.7.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-media"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-media#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}