promigence 0.1.0-beta.12

package/dist/live.js

@@ -0,0 +1,469 @@
+import { readFileSync } from "node:fs";
+import { ptyCommand, shellQuote, toEntryInfo, } from "./sdk/index.js";
+import { bool, client, list, nexts, positional, required, str, } from "./commands.js";
+import { parseRange } from "./handlers.js";
+import { emit, exitWith, noCommandFix, okEnvelope, parseCommandTimeout, parseMaxOutput, usageError, write } from "./io.js";
+import { fieldForTerminal, jsonLine, sh, shellArg } from "./term.js";
+const FOLLOW_WAIT_MS = 1_000;
+const FOLLOW_POLL_MS = 250;
+const pause = (ms) => new Promise((r) => { setTimeout(r, ms); });
+const sandboxFlag = (ctx) => required(ctx, "--sandbox", `Pass --sandbox sbx_<id> (from \`promigence run report <run_id>\`), e.g. promigence ${ctx.cmd.name} … --sandbox sbx_01.`);
+export const RECONNECTED_LINE = "the service restarted; reconnected to a new shell";
+const sandboxShell = async (ctx) => {
+    const sid = positional(ctx, "a sandbox id", "promigence sandbox shell sbx_01");
+    const tail = ctx.cmdTail.length ? ctx.cmdTail.map(shellQuote).join(" ") : undefined;
+    const flagCmd = str(ctx, "--cmd");
+    if (tail !== undefined && flagCmd !== undefined) {
+        throw usageError("sandbox shell takes --cmd or a command after --, not both", "Pick one: promigence sandbox shell sbx_01 -- htop.");
+    }
+    const cwd = str(ctx, "--cwd");
+    const envs = {};
+    for (const kv of list(ctx, "--env")) {
+        const eq = kv.indexOf("=");
+        if (eq <= 0)
+            throw usageError(`--env '${kv}' is not K=V`, "Pass --env NAME=value (repeatable).");
+        envs[kv.slice(0, eq)] = kv.slice(eq + 1);
+    }
+    const secrets = [];
+    for (const spec of list(ctx, "--secret")) {
+        const eq = spec.indexOf("=");
+        if (eq === 0)
+            throw usageError(`--secret '${spec}' has no name`, "Pass --secret NAME or --secret NAME=VAR.");
+        secrets.push(eq < 0 ? spec : { name: spec.slice(0, eq), as: spec.slice(eq + 1) });
+    }
+    const inner = tail ?? flagCmd;
+    const cmd = ptyCommand({
+        ...(inner === undefined ? {} : { cmd: tail !== undefined ? `exec ${inner}` : inner }),
+        ...(cwd === undefined ? {} : { cwd }),
+        envs,
+    });
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    const tty = Boolean(stdin.isTTY && stdout.isTTY);
+    const size = () => ({ cols: stdout.columns || 80, rows: stdout.rows || 24 });
+    const session = await client(ctx).sandboxes.pty(sid, {
+        ...size(),
+        ...(cmd === undefined ? {} : { cmd }),
+        ...(secrets.length ? { secrets } : {}),
+        onData: (d) => { stdout.write(d); },
+        reconnect: inner === undefined,
+        onReconnected: ({ resumed }) => {
+            if (resumed)
+                return;
+            const line = RECONNECTED_LINE;
+            void write(process.stderr, process.stderr.isTTY ? `\r\n\x1b[2m${line}\x1b[0m\r\n` : `promigence sandbox shell: ${line}\n`);
+        },
+    });
+    const restore = () => {
+        if (tty && stdin.isRaw)
+            stdin.setRawMode(false);
+        stdin.pause();
+    };
+    if (tty)
+        stdin.setRawMode(true);
+    stdin.on("data", (d) => session.write(d));
+    stdin.on("end", () => session.eof());
+    stdin.resume();
+    const onResize = () => session.resize(size());
+    if (tty)
+        stdout.on("resize", onResize);
+    for (const sig of ["SIGTERM", "SIGHUP"]) {
+        process.on(sig, () => { restore(); session.disconnect(); });
+    }
+    const exit = await session.wait();
+    restore();
+    stdout.off("resize", onResize);
+    if (exit.exitCode === null && exit.signal === null) {
+        const why = exit.error && exit.error.code !== "closed"
+            ? `the terminal failed: ${exit.error.code}: ${exit.error.message}`
+            : "the connection closed without an exit record";
+        await write(process.stderr, `\r\npromigence sandbox shell: ${why}\r\n`);
+        return exitWith(125);
+    }
+    return exitWith(exit.exitCode ?? 128 + (exit.signal ?? 0));
+};
+const portExpose = async (ctx) => {
+    const raw = positional(ctx, "a port", "promigence port expose 3000 --sandbox sbx_01");
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw usageError(`'${raw}' is not a port`, "Pass the port your process listens on inside the sandbox, 1..65535.");
+    }
+    const sid = sandboxFlag(ctx);
+    const p = await client(ctx).sandboxes.ports.expose(sid, port);
+    const next = nexts([sh `promigence port list --sandbox ${sid}`, "every URL this sandbox has"], [sh `promigence port revoke ${port} --sandbox ${sid}`, "take the URL down (anyone with it can reach the port)"]);
+    if (ctx.mode === "text") {
+        await write(process.stdout, `${p.url}\n`);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, {}, next), [`port ${port} of ${sid} is public at the URL above until revoked`], 0, ctx.pointer, "stderr");
+    }
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...p }, next), [], 0, ctx.pointer);
+};
+const portList = async (ctx) => {
+    const sid = sandboxFlag(ctx);
+    const ports = await client(ctx).sandboxes.ports.list(sid);
+    const next = ports.length ? nexts([sh `promigence port revoke PORT --sandbox ${sid}`, "stop publishing one: put its port from this list in place of PORT"]) : [];
+    const lines = ports.length
+        ? ports.map((p) => `  ${String(p.port).padEnd(6)} ${p.url}`)
+        : [`  no published ports on ${sid}`];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { sandbox_id: sid, ports }, next), [`ports of ${sid}:`, ...lines], 0, ctx.pointer);
+};
+const portRevoke = async (ctx) => {
+    const which = positional(ctx, "a token or a port", "promigence port revoke 3000 --sandbox sbx_01");
+    const sid = sandboxFlag(ctx);
+    const r = await client(ctx).sandboxes.ports.revoke(sid, which);
+    const next = nexts([sh `promigence port list --sandbox ${sid}`, "what is still published"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { sandbox_id: sid, revoked: r.revoked }, next), [`${sid}: revoked ${r.revoked.length} URL${r.revoked.length === 1 ? "" : "s"}`], 0, ctx.pointer);
+};
+export async function execBackground(ctx) {
+    const sid = str(ctx, "--sandbox");
+    if (sid === undefined) {
+        throw usageError("exec --background needs --sandbox SID", "Background execs run in one sandbox: promigence exec --sandbox sbx_01 --background -- npm run dev.");
+    }
+    if (str(ctx, "--run") !== undefined)
+        throw usageError("exec --background takes --sandbox, not --run", "Start it in one sandbox.");
+    if (ctx.cmdTail.length === 0) {
+        throw usageError("no command: everything after `--` is the command to run", noCommandFix("e.g. promigence exec --sandbox sbx_01 --background -- npm run dev."));
+    }
+    const maxOutput = str(ctx, "--max-output");
+    const timeout = str(ctx, "--timeout");
+    const secrets = list(ctx, "--secret");
+    const stdin = bool(ctx, "--stdin");
+    const rec = await client(ctx).sandboxes.execBackground(sid, {
+        argv: ctx.cmdTail,
+        ...(secrets.length ? { secrets } : {}),
+        ...(stdin ? { stdin: true } : {}),
+        ...(maxOutput === undefined ? {} : { maxOutputBytes: parseMaxOutput(maxOutput) }),
+        ...(timeout === undefined ? {} : { timeoutMs: parseCommandTimeout(timeout, "--timeout") }),
+    });
+    const stdinHint = stdin
+        ? [[sh `promigence exec stdin ${rec.exec_id} --sandbox ${sid}`, "write to its stdin, then close it"]]
+        : [];
+    const next = nexts(...stdinHint, [sh `promigence exec output ${rec.exec_id} --sandbox ${sid} --follow`, "stream its output until it exits"], [sh `promigence exec kill ${rec.exec_id} --sandbox ${sid}`, "stop it"], [sh `promigence exec kill ${rec.exec_id} --sandbox ${sid} --forget`, FORGET_WHY]);
+    if (ctx.mode === "text") {
+        await write(process.stdout, `${rec.exec_id}\n`);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, {}, next), [`started in the background on ${sid}: ${ctx.cmdTail.join(" ")}`, `  next: ${next[0].cmd}`], 0, false);
+    }
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { sandbox_id: sid, exec_id: rec.exec_id, state: rec.state, argv: ctx.cmdTail, background: true }, next), [], 0, false);
+}
+export const FORGET_WHY = "once it has finished: until its output is read to the end or it is forgotten, it holds off an idle pause for a minute";
+function exitOf(r) {
+    if (!r.exit)
+        return undefined;
+    return r.exit.exit_code ?? (r.exit.signal ? 128 + r.exit.signal : undefined);
+}
+const execPs = async (ctx) => {
+    const sid = sandboxFlag(ctx);
+    const execs = await client(ctx).sandboxes.execs.list(sid);
+    const running = execs.find((e) => e.state === "running");
+    const next = nexts(...(execs.length ? [[sh `promigence exec output ${execs[execs.length - 1].exec_id} --sandbox ${sid}`, "read one's output"]] : []), ...(running ? [[sh `promigence exec kill EXEC_ID --sandbox ${sid}`, "stop one: put its id from this list in place of EXEC_ID"]] : []));
+    const lines = execs.length
+        ? execs.map((e) => {
+            const code = exitOf(e);
+            return `  ${e.exec_id.padEnd(28)} ${(e.state + (code === undefined ? "" : ` ${code}`)).padEnd(10)} ${e.argv}`;
+        })
+        : [`  no background execs on ${sid}`];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { sandbox_id: sid, execs }, next), [`background execs on ${sid}:`, ...lines], 0, ctx.pointer);
+};
+export function signalOk(sig) {
+    if (/^\d+$/.test(sig))
+        return Number(sig) >= 1 && Number(sig) <= 64;
+    const name = sig.toUpperCase().replace(/^SIG/, "");
+    return ["HUP", "INT", "QUIT", "KILL", "USR1", "USR2", "TERM", "CONT", "STOP"].includes(name);
+}
+const execKill = async (ctx) => {
+    const eid = positional(ctx, "an exec id", "promigence exec kill x_4f1c2a9e --sandbox sbx_01");
+    const sid = sandboxFlag(ctx);
+    const c = client(ctx);
+    const sig = str(ctx, "--signal") ?? "SIGKILL";
+    if (!signalOk(sig)) {
+        throw usageError(`--signal ${sig} is not a signal`, "Pass a number 1-64 or a name: HUP, INT, QUIT, KILL, USR1, USR2, TERM, CONT, STOP (with or without SIG).");
+    }
+    const r = await c.sandboxes.execs.signal(sid, eid, /^\d+$/.test(sig) ? Number(sig) : sig);
+    let forgotten = false;
+    if (bool(ctx, "--forget")) {
+        await c.sandboxes.execs.forget(sid, eid);
+        forgotten = true;
+    }
+    const next = nexts([sh `promigence exec ps --sandbox ${sid}`, "what is still running"]);
+    const what = r.delivered ? `signal ${r.signal} delivered` : "had already exited";
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { sandbox_id: sid, exec_id: eid, signal: r.signal, delivered: r.delivered, forgotten }, next), [`${eid}: ${what}${forgotten ? "; handle and output dropped" : ""}`], 0, ctx.pointer);
+};
+export async function backgroundOutput(ctx, execId) {
+    const sid = str(ctx, "--sandbox");
+    if (sid === undefined) {
+        throw usageError(`${execId} is a background exec; its output lives on the sandbox that runs it`, `Name it: ${sh `promigence exec output ${execId} --sandbox sbx_<id>`}.`);
+    }
+    const c = client(ctx);
+    if (bool(ctx, "--follow")) {
+        const off = { stdout: 0, stderr: 0 };
+        const dec = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+        let rec = await c.sandboxes.execs.get(sid, execId);
+        for (;;) {
+            const ended = rec.state !== "running";
+            let more = false;
+            for (const s of ["stdout", "stderr"]) {
+                const r = await c.sandboxes.execs.read(sid, execId, s, { offset: off[s] });
+                rec = r.record;
+                if (r.data.length) {
+                    more = true;
+                    off[s] += r.data.length;
+                    const text = dec[s].decode(r.data, { stream: true });
+                    if (ctx.mode === "json")
+                        await write(process.stdout, jsonLine(process.stdout, { stream: s, data: text }));
+                    else
+                        await write(s === "stdout" ? process.stdout : process.stderr, text);
+                }
+            }
+            if (ended && !more)
+                break;
+            if (!more) {
+                rec = await c.sandboxes.execs.get(sid, execId, { waitMs: FOLLOW_WAIT_MS });
+                if (rec.state === "running" && !((rec.waited_ms ?? 0) >= FOLLOW_WAIT_MS))
+                    await pause(FOLLOW_POLL_MS);
+            }
+        }
+        const code = exitOf(rec) ?? (rec.state === "failed" ? 125 : 0);
+        const forget = nexts([sh `promigence exec kill ${execId} --sandbox ${sid} --forget`, FORGET_WHY]);
+        if (ctx.mode === "json") {
+            await write(process.stdout, jsonLine(process.stdout, okEnvelope(ctx.cmd.name, { sandbox_id: sid, exec_id: execId, state: rec.state, exit: rec.exit ?? null, ...(rec.error ? { error: rec.error } : {}) }, forget)));
+        }
+        return exitWith(code);
+    }
+    const stream = bool(ctx, "--stderr") ? "stderr" : "stdout";
+    const range = str(ctx, "--range");
+    const rg = range === undefined ? {} : parseRange(range);
+    const from = rg.from ?? 0;
+    const len = rg.to === undefined ? undefined : rg.to - from + 1;
+    const parts = [];
+    let at = from;
+    let rec;
+    for (;;) {
+        const want = len === undefined ? undefined : len - (at - from);
+        if (want !== undefined && want <= 0)
+            break;
+        const r = await c.sandboxes.execs.read(sid, execId, stream, { offset: at, ...(want === undefined ? {} : { len: want }) });
+        rec = r.record;
+        if (r.data.length === 0)
+            break;
+        parts.push(r.data);
+        at += r.data.length;
+    }
+    const bytes = Buffer.concat(parts);
+    if (ctx.mode === "text") {
+        await new Promise((resolve) => { process.stdout.write(bytes, () => resolve()); });
+        return exitWith(0);
+    }
+    const next = rec !== undefined && rec.state !== "running"
+        ? nexts([sh `promigence exec kill ${execId} --sandbox ${sid} --forget`, FORGET_WHY])
+        : nexts([sh `promigence exec output ${execId} --sandbox ${sid} --follow`, "stream it until it exits"], [sh `promigence exec kill ${execId} --sandbox ${sid}`, "stop it"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+        exec_id: execId, sandbox_id: sid, background: true, state: rec?.state, stream,
+        [stream]: bytes.toString("utf8"), bytes: bytes.length,
+        total_bytes: stream === "stdout" ? rec?.stdout_total : rec?.stderr_total,
+        ...(rec?.exit ? { exit: rec.exit } : {}),
+        range: { from, to: from + bytes.length - 1 },
+    }, next), [], 0, false);
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        const parts = [];
+        process.stdin.on("data", (d) => parts.push(d));
+        process.stdin.on("end", () => resolve(Buffer.concat(parts)));
+        process.stdin.on("error", reject);
+        process.stdin.resume();
+    });
+}
+const execStdin = async (ctx) => {
+    const eid = positional(ctx, "an exec id", "promigence exec stdin x_4f1c2a9e --sandbox sbx_01 --data 'y\\n'");
+    const sid = sandboxFlag(ctx);
+    const data = str(ctx, "--data");
+    const file = str(ctx, "--file");
+    if (data !== undefined && file !== undefined) {
+        throw usageError("exec stdin takes --data or --file, not both", "Pick one, or pipe the bytes in and pass neither.");
+    }
+    let bytes;
+    let eof;
+    if (data !== undefined) {
+        bytes = new TextEncoder().encode(data);
+        eof = bool(ctx, "--eof");
+    }
+    else if (file !== undefined) {
+        try {
+            bytes = new Uint8Array(readFileSync(file));
+        }
+        catch (e) {
+            throw usageError(`cannot read ${file}: ${e.message}`, "Give a readable local path; its bytes are written to the exec's stdin as they are.");
+        }
+        eof = bool(ctx, "--eof");
+    }
+    else {
+        bytes = new Uint8Array(await readStdin());
+        eof = !bool(ctx, "--no-eof");
+    }
+    if (bool(ctx, "--no-eof"))
+        eof = false;
+    const r = await client(ctx).sandboxes.execs.stdin(sid, eid, { data: bytes, ...(eof ? { eof: true } : {}) });
+    const next = nexts([sh `promigence exec output ${eid} --sandbox ${sid} --follow`, "read what it wrote back"], [sh `promigence exec kill ${eid} --sandbox ${sid}`, "stop it"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { sandbox_id: sid, exec_id: eid, written: r.written, eof: r.eof }, next), [`${eid}: wrote ${r.written} byte${r.written === 1 ? "" : "s"}${r.eof ? ", stdin closed" : "; stdin left open (pass --eof to close it)"}`], 0, ctx.pointer);
+};
+function absArg(ctx, index, fallback) {
+    const p = ctx.args[index] ?? fallback;
+    if (p === undefined) {
+        throw usageError(`${ctx.cmd.name} needs a path`, `Example: promigence ${ctx.cmd.name} /tmp --sandbox sbx_01.`);
+    }
+    if (!p.startsWith("/")) {
+        throw usageError(`'${p}' must be absolute inside the sandbox`, `Paths inside a sandbox are absolute: promigence ${ctx.cmd.name} /tmp … .`);
+    }
+    return p;
+}
+function modeFlag(ctx) {
+    const raw = str(ctx, "--mode");
+    if (raw === undefined)
+        return undefined;
+    if (!/^[0-7]{3,4}$/.test(raw)) {
+        throw usageError(`--mode: '${raw}' is not an octal mode`, "Pass three or four octal digits, e.g. --mode 755.");
+    }
+    return raw;
+}
+function uintFlag(ctx, name) {
+    const raw = str(ctx, name);
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 0)
+        throw usageError(`${name}: '${raw}' is not a non-negative integer`, `Pass ${name} N with N >= 0.`);
+    return n;
+}
+function fileLine(f) {
+    return `${f.path}${f.is_dir ? "/" : ""} mode ${f.mode}${f.size ? ` · ${f.size} bytes` : ""}`;
+}
+const filesLs = async (ctx) => {
+    const path = absArg(ctx, 0, "/");
+    const sid = sandboxFlag(ctx);
+    const depth = uintFlag(ctx, "--depth");
+    const limit = uintFlag(ctx, "--limit");
+    const r = await client(ctx).sandboxes.files.list(sid, path, {
+        ...(bool(ctx, "--recursive") ? { recursive: true } : {}),
+        ...(depth === undefined ? {} : { depth }),
+        ...(limit === undefined ? {} : { limit }),
+        ...(bool(ctx, "--no-hidden") ? { hidden: false } : {}),
+    });
+    const file = r.entries.find((e) => !e.is_dir && !e.is_symlink);
+    const next = file
+        ? nexts([sh `promigence files get ${file.path} ${`./${file.name.split("/").pop()}`} --sandbox ${sid}`, "copy one out"])
+        : [];
+    const lines = r.entries.map((e) => {
+        const info = toEntryInfo(e);
+        const kind = e.is_symlink ? "l" : e.is_dir ? "d" : "-";
+        const when = `${info.modifiedTime.toISOString().slice(0, 16).replace("T", " ")}Z`;
+        const base = r.path === "/" ? "/" : `${r.path.replace(/\/+$/, "")}/`;
+        const shown = bool(ctx, "--recursive") && typeof e.path === "string" && e.path.startsWith(base) ? e.path.slice(base.length) : e.name;
+        return `${kind}${info.permissions} ${String(e.size).padStart(10)} ${when} ${shown}${e.is_dir ? "/" : ""}`;
+    });
+    if (ctx.mode === "text") {
+        await write(process.stdout, lines.length ? lines.map((l) => fieldForTerminal(process.stdout, l)).join("\n") + "\n" : "");
+        if (r.truncated)
+            await write(process.stderr, `promigence files ls: truncated at ${r.entries.length} entries\n`);
+        return exitWith(0);
+    }
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...r }, next), [], 0, ctx.pointer);
+};
+const filesSearch = async (ctx) => {
+    const path = absArg(ctx, 0, "/");
+    const sid = sandboxFlag(ctx);
+    const pattern = str(ctx, "--name");
+    const contains = str(ctx, "--contains");
+    if (pattern === undefined && contains === undefined) {
+        throw usageError("files search needs --name, --contains, or both", "Example: promigence files search /tmp --name '*.py' --sandbox sbx_01, or --contains TODO.");
+    }
+    const limit = uintFlag(ctx, "--limit");
+    const r = await client(ctx).sandboxes.files.search(sid, path, {
+        ...(pattern === undefined ? {} : { pattern }),
+        ...(contains === undefined ? {} : { contains }),
+        ...(bool(ctx, "--ignore-case") ? { ignoreCase: true } : {}),
+        ...(limit === undefined ? {} : { limit }),
+        ...(bool(ctx, "--no-hidden") ? { hidden: false } : {}),
+    });
+    const hit = r.matches[0];
+    const next = hit ? nexts([sh `promigence files get ${hit.path} ${`./${hit.path.split("/").pop()}`} --sandbox ${sid}`, "copy one out"]) : [];
+    const lines = r.matches.map((m) => (m.line ? `${m.path}:${m.line}: ${m.text ?? ""}` : m.path));
+    if (ctx.mode === "text") {
+        await write(process.stdout, lines.length ? lines.map((l) => fieldForTerminal(process.stdout, l)).join("\n") + "\n" : "");
+        if (r.truncated)
+            await write(process.stderr, `promigence files search: truncated at ${r.matches.length} matches\n`);
+        return exitWith(0);
+    }
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...r }, next), [], 0, ctx.pointer);
+};
+const filesMkdir = async (ctx) => {
+    const path = absArg(ctx, 0);
+    const sid = sandboxFlag(ctx);
+    const mode = modeFlag(ctx);
+    const f = await client(ctx).sandboxes.files.mkdir(sid, path, {
+        ...(mode === undefined ? {} : { mode }),
+        ...(bool(ctx, "--parents") ? { parents: true } : {}),
+    });
+    const next = nexts([sh `promigence files ls ${path} --sandbox ${sid}`, "what is in it"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...f }, next), [fileLine(f)], 0, ctx.pointer);
+};
+function insidePair(ctx) {
+    const sid = sandboxFlag(ctx);
+    const [from, to] = [ctx.args[0], ctx.args[1]];
+    if (!from || !to) {
+        throw usageError(`${ctx.cmd.name} needs SRC and DST`, `Both are inside the sandbox: promigence ${ctx.cmd.name} /tmp/a /tmp/b --sandbox ${shellArg(sid)}.`);
+    }
+    for (const p of [from, to]) {
+        if (!p.startsWith("/"))
+            throw usageError(`'${p}' must be absolute inside the sandbox`, "Example: /tmp/out.json.");
+    }
+    return { sid, from, to };
+}
+const filesMv = async (ctx) => {
+    const { sid, from, to } = insidePair(ctx);
+    const f = await client(ctx).sandboxes.files.move(sid, from, to, {
+        ...(bool(ctx, "--overwrite") ? { overwrite: true } : {}),
+    });
+    const next = nexts([sh `promigence files ls ${to} --sandbox ${sid}`, "see it where it landed"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...f, from }, next), [`${from} -> ${fileLine(f)}`], 0, ctx.pointer);
+};
+const filesCp = async (ctx) => {
+    const { sid, from, to } = insidePair(ctx);
+    const f = await client(ctx).sandboxes.files.copy(sid, from, to, {
+        ...(bool(ctx, "--recursive") ? { recursive: true } : {}),
+        ...(bool(ctx, "--overwrite") ? { overwrite: true } : {}),
+    });
+    const next = nexts([sh `promigence files ls ${to} --sandbox ${sid}`, "see the copy"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...f, from }, next), [`${from} -> ${fileLine(f)}`], 0, ctx.pointer);
+};
+const filesChmod = async (ctx) => {
+    const path = absArg(ctx, 0);
+    const sid = sandboxFlag(ctx);
+    const mode = modeFlag(ctx);
+    const uid = uintFlag(ctx, "--uid");
+    const gid = uintFlag(ctx, "--gid");
+    if (mode === undefined && uid === undefined && gid === undefined) {
+        throw usageError("files chmod needs --mode, --uid or --gid", "A chmod that changes nothing is a round trip that answers nothing: promigence files chmod /tmp/run.sh --mode 755 --sandbox sbx_01.");
+    }
+    const f = await client(ctx).sandboxes.files.chmod(sid, path, {
+        ...(mode === undefined ? {} : { mode }),
+        ...(uid === undefined ? {} : { uid }),
+        ...(gid === undefined ? {} : { gid }),
+        ...(bool(ctx, "--recursive") ? { recursive: true } : {}),
+    });
+    const next = nexts([sh `promigence files ls ${path} --sandbox ${sid}`, "confirm it"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...f }, next), [fileLine(f)], 0, ctx.pointer);
+};
+export const LIVE_HANDLERS = {
+    "sandbox shell": sandboxShell,
+    "port expose": portExpose,
+    "port list": portList,
+    "port revoke": portRevoke,
+    "exec ps": execPs,
+    "exec kill": execKill,
+    "exec stdin": execStdin,
+    "files ls": filesLs,
+    "files search": filesSearch,
+    "files mkdir": filesMkdir,
+    "files mv": filesMv,
+    "files cp": filesCp,
+    "files chmod": filesChmod,
+};