AgentHub/server/__tests__/file-explorer.test.js

/**
 * @file Route tests for the workspace File Explorer (`/api/lanes/:id/fs/*`,
 * server/lib/file-explorer.js): list, mkdir/newfile, rename, move, copy (in
 * place, across workspaces), delete into the trash and restore/purge, a
 * streamed upload into new sub-folders with every conflict policy, a batch
 * of many small files in one request (and, in a member's folder, as ONE
 * write-as `extract` of a tar that real `tar` unpacks), a resumable upload
 * sent in parts and committed from the staged bytes (and a member's upload
 * written to a hidden temp file, moved onto its name only when whole), a zip of
 * files and folders that unzips back to the same bytes — and the guards: no
 * `..`, no symlink walking out, nothing in `.git`, no secret file, the
 * workspace folder itself never moved or deleted, cross-origin refused.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

const { describe, it, before, after } = require("node:test");
const assert = require("node:assert/strict");
const fs = require("node:fs");
const os = require("node:os");
const path = require("node:path");
const http = require("node:http");

const ROOT = fs.mkdtempSync(path.join(os.tmpdir(), "file-explorer-"));
process.env.DASHBOARD_DB_PATH = path.join(ROOT, "t.db");
process.env.CLAUDE_HOME = path.join(ROOT, ".claude");
process.env.DASHBOARD_DATA_DIR = path.join(ROOT, "data");
process.env.DASHBOARD_REMOTE_SYNC_MS = "0";
process.env.DASHBOARD_LIVENESS_PROBE = "0";
process.env.HOME = ROOT;

const { createApp } = require("../index");
const AdmZip = require("adm-zip");

let app;
let base;
const W1 = path.join(ROOT, "w1");
const W2 = path.join(ROOT, "w2");
let lane1;
let lane2;

function request(method, p, body, headers = {}) {
  const raw = Buffer.isBuffer(body) || typeof body === "string";
  return fetch(`${base}${p}`, {
    method,
    headers: { ...(raw ? {} : { "Content-Type": "application/json" }), ...headers },
    body: body === undefined ? undefined : raw ? body : JSON.stringify(body),
  }).then(async (r) => {
    const buf = Buffer.from(await r.arrayBuffer());
    let json = null;
    try {
      json = JSON.parse(buf.toString("utf8"));
    } catch {
      /* binary */
    }
    return { status: r.status, body: json, buf, headers: r.headers };
  });
}
const fsApi = (lane, op, body) => request("POST", `/api/lanes/${lane}/fs/${op}`, body);
const ls = async (lane, p = "") =>
  (await request("GET", `/api/lanes/${lane}/fs/list?path=${encodeURIComponent(p)}`)).body;
const names = (l) => l.entries.map((e) => e.name);

before(async () => {
  for (const w of [W1, W2]) fs.mkdirSync(w, { recursive: true });
  fs.writeFileSync(path.join(W1, "a.txt"), "alpha\n");
  fs.mkdirSync(path.join(W1, "src/lib"), { recursive: true });
  fs.writeFileSync(path.join(W1, "src/lib/x.js"), "x\n");
  fs.mkdirSync(path.join(W1, ".git"));
  fs.writeFileSync(path.join(W1, ".git/config"), "[core]\n");
  fs.mkdirSync(path.join(W1, ".claude"));
  fs.writeFileSync(path.join(W1, ".claude/settings.local.json"), '{"secret":1}');
  fs.symlinkSync("/etc", path.join(W1, "out"));
  app = http.createServer(createApp());
  await new Promise((r) => app.listen(0, "127.0.0.1", r));
  base = `http://127.0.0.1:${app.address().port}`;
  lane1 = (await request("POST", "/api/lanes/ensure", { cwd: W1, exact: true })).body.lane.id;
  lane2 = (await request("POST", "/api/lanes/ensure", { cwd: W2, exact: true })).body.lane.id;
});
after(async () => {
  await new Promise((r) => app.close(r));
});

describe("File Explorer", () => {
  it("lists folders first, never a secret, a symlink shown as a link", async () => {
    const l = await ls(lane1);
    assert.equal(l.path, "");
    assert.equal(l.parent, null);
    assert.deepEqual(
      l.entries.filter((e) => e.type === "dir").map((e) => e.name),
      [".claude", ".git", "src"]
    );
    assert.ok(names(l).includes("a.txt"));
    assert.equal(l.entries.find((e) => e.name === "out").type, "link");
    const claude = await ls(lane1, ".claude");
    assert.ok(!names(claude).includes("settings.local.json"));
    assert.equal((await ls(lane1, "src")).parent, "");
  });

  it("refuses paths that leave the workspace", async () => {
    for (const p of ["../", "/etc", "out", "out/passwd", "src/../../x"]) {
      const r = await request("GET", `/api/lanes/${lane1}/fs/list?path=${encodeURIComponent(p)}`);
      assert.ok([400, 403, 404].includes(r.status), `${p} → ${r.status}`);
    }
  });

  it("makes a folder and an empty file, refusing a taken name", async () => {
    assert.equal((await fsApi(lane1, "mkdir", { path: "docs" })).status, 201);
    assert.equal((await fsApi(lane1, "newfile", { path: "docs/readme.md" })).status, 201);
    assert.equal(fs.readFileSync(path.join(W1, "docs/readme.md"), "utf8"), "");
    const again = await fsApi(lane1, "mkdir", { path: "docs" });
    assert.equal(again.status, 409);
    assert.deepEqual(again.body.error.names, ["docs"]);
    assert.equal((await fsApi(lane1, "mkdir", { path: ".git/hooks2" })).status, 400);
    assert.equal((await fsApi(lane1, "newfile", { path: "a/b\\c" })).status, 404);
  });

  it("renames, never onto a taken name or out of the folder", async () => {
    assert.equal(
      (await fsApi(lane1, "rename", { path: "docs/readme.md", name: "README.md" })).status,
      200
    );
    assert.ok(fs.existsSync(path.join(W1, "docs/README.md")));
    assert.equal(
      (await fsApi(lane1, "rename", { path: "docs/README.md", name: "../a.txt" })).status,
      400
    );
    fs.writeFileSync(path.join(W1, "docs/other.md"), "o");
    assert.equal(
      (await fsApi(lane1, "rename", { path: "docs/other.md", name: "README.md" })).status,
      409
    );
  });

  it("moves, asking about a taken name, and never a folder into itself", async () => {
    fs.writeFileSync(path.join(W1, "src/a.txt"), "other alpha\n");
    const clash = await fsApi(lane1, "move", { paths: ["a.txt"], dest: "src" });
    assert.equal(clash.status, 409);
    assert.deepEqual(clash.body.error.names, ["a.txt"]);
    const keep = await fsApi(lane1, "move", { paths: ["a.txt"], dest: "src", conflict: "keep" });
    assert.deepEqual(keep.body.moved, ["src/a (1).txt"]);
    assert.equal((await fsApi(lane1, "move", { paths: ["src"], dest: "src/lib" })).status, 400);
    assert.equal((await fsApi(lane1, "move", { paths: [".git"], dest: "docs" })).status, 400);
  });

  it("copies in place (keeping both) and into another workspace of the account", async () => {
    const inPlace = await fsApi(lane1, "copy", { paths: ["src/lib/x.js"], dest: "src/lib" });
    assert.deepEqual(inPlace.body.copied, ["src/lib/x (1).js"]);
    const across = await request("POST", `/api/lanes/${lane2}/fs/copy`, {
      paths: ["src"],
      dest: "",
      fromLane: lane1,
    });
    assert.equal(across.status, 200, JSON.stringify(across.body));
    assert.equal(fs.readFileSync(path.join(W2, "src/lib/x.js"), "utf8"), "x\n");
    // A symlink inside a copied folder stays a link — never followed.
    fs.symlinkSync("/etc/hostname", path.join(W1, "docs/link"));
    await request("POST", `/api/lanes/${lane2}/fs/copy`, {
      paths: ["docs"],
      dest: "",
      fromLane: lane1,
    });
    assert.ok(fs.lstatSync(path.join(W2, "docs/link")).isSymbolicLink());
  });

  it("deletes into the trash, restores to the same place, and purges", async () => {
    const del = await fsApi(lane1, "delete", { paths: ["docs/README.md", "src/lib"] });
    assert.equal(del.status, 200);
    assert.ok(!fs.existsSync(path.join(W1, "src/lib")));
    const trash = (await request("GET", `/api/lanes/${lane1}/fs/trash`)).body;
    assert.equal(trash.items.length, 2);
    const lib = trash.items.find((i) => i.name === "lib");
    assert.equal(lib.isDir, true);
    const back = await fsApi(lane1, "trash/restore", { id: lib.id });
    assert.equal(back.status, 200, JSON.stringify(back.body));
    assert.equal(fs.readFileSync(path.join(W1, "src/lib/x.js"), "utf8"), "x\n");
    assert.equal((await fsApi(lane1, "trash/purge", { id: "all" })).body.purged, 1);
    assert.equal((await request("GET", `/api/lanes/${lane1}/fs/trash`)).body.items.length, 0);
    assert.equal((await fsApi(lane1, "trash/restore", { id: "../../x" })).status, 400);
  });

  it("never deletes the workspace itself, .git, or a secret", async () => {
    for (const p of [".", "", ".git", ".git/config", ".claude/settings.local.json"]) {
      const r = await fsApi(lane1, "delete", { paths: [p] });
      assert.ok(r.status >= 400, `${p} → ${r.status}`);
    }
    assert.ok(fs.existsSync(path.join(W1, ".git/config")));
  });

  it("uploads a stream into new sub-folders, with every conflict policy", async () => {
    const up = (p, body, conflict) =>
      request(
        "POST",
        `/api/lanes/${lane1}/fs/upload?path=${encodeURIComponent(p)}${conflict ? `&conflict=${conflict}` : ""}`,
        Buffer.from(body),
        { "Content-Type": "application/octet-stream" }
      );
    assert.equal((await up("site/css/app.css", "body{}")).status, 201);
    assert.equal(fs.readFileSync(path.join(W1, "site/css/app.css"), "utf8"), "body{}");
    const clash = await up("site/css/app.css", "new");
    assert.equal(clash.status, 409);
    assert.equal((await up("site/css/app.css", "new", "skip")).body.skipped, true);
    assert.equal((await up("site/css/app.css", "kept", "keep")).body.path, "site/css/app (1).css");
    await up("site/css/app.css", "replaced", "replace");
    assert.equal(fs.readFileSync(path.join(W1, "site/css/app.css"), "utf8"), "replaced");
    // The replaced one is in the trash, restorable.
    assert.ok(
      (await request("GET", `/api/lanes/${lane1}/fs/trash`)).body.items.some(
        (i) => i.name === "app.css"
      )
    );
    assert.equal((await up(".git/hooks/post-commit", "x")).status, 400);
    assert.equal((await up("out/evil", "x")).status >= 400, true);
    // A declared size over the cap is refused before a byte is stored.
    const big = await new Promise((resolve) => {
      const req = http.request(
        `${base}/api/lanes/${lane1}/fs/upload?path=big.bin`,
        { method: "POST", headers: { "Content-Length": String(600 * 1024 * 1024) } },
        (r) => resolve(r.statusCode)
      );
      req.on("error", () => resolve("reset"));
      req.write("x");
    });
    assert.equal(big, 413);
    assert.ok(!fs.existsSync(path.join(W1, "big.bin")));
  });

  it("uploads many small files as one batch, planned whole before writing", async () => {
    const files = [
      ["many/a.txt", "a"],
      ["many/deep/b.txt", "bb"],
      ["many/empty", ""],
      [`many/${"n".repeat(120)}/long.txt`, "long"],
    ];
    const body = (list) => {
      const head = Buffer.from(
        JSON.stringify({ files: list.map(([p, c]) => ({ path: p, size: Buffer.byteLength(c) })) })
      );
      const len = Buffer.alloc(4);
      len.writeUInt32BE(head.length);
      return Buffer.concat([len, head, ...list.map(([, c]) => Buffer.from(c))]);
    };
    const batch = (list, conflict = "", dir = "up") =>
      request(
        "POST",
        `/api/lanes/${lane1}/fs/upload-batch?dir=${dir}${conflict ? `&conflict=${conflict}` : ""}`,
        body(list),
        { "Content-Type": "application/octet-stream" }
      );
    assert.equal((await fsApi(lane1, "mkdir", { path: "up" })).status, 201);
    const check = await fsApi(lane1, "upload-check", { dir: "up", paths: files.map(([p]) => p) });
    assert.deepEqual(check.body, { taken: [], batch: true });
    const r = await batch(files);
    assert.equal(r.status, 201);
    assert.equal(r.body.saved, 4);
    for (const [p, c] of files) assert.equal(fs.readFileSync(path.join(W1, "up", p), "utf8"), c);
    // Taken names: one 409 naming them all, and nothing of the batch written.
    const again = await batch([
      ["many/a.txt", "x"],
      ["many/new.txt", "n"],
      ["many/deep/b.txt", "y"],
    ]);
    assert.equal(again.status, 409);
    assert.deepEqual(again.body.error.names, ["many/a.txt", "many/deep/b.txt"]);
    assert.ok(!fs.existsSync(path.join(W1, "up/many/new.txt")));
    const taken = await fsApi(lane1, "upload-check", { dir: "up", paths: ["many/a.txt", "z"] });
    assert.deepEqual(taken.body.taken, ["many/a.txt"]);
    // skip / keep / replace for the whole batch.
    const skip = await batch(
      [
        ["many/a.txt", "x"],
        ["many/new.txt", "n"],
      ],
      "skip"
    );
    assert.deepEqual([skip.body.saved, skip.body.skipped], [1, 1]);
    const keep = await batch(
      [
        ["many/a.txt", "k"],
        ["many/a (1).txt", "k1"],
      ],
      "keep"
    );
    assert.deepEqual(keep.body.paths, ["up/many/a (2).txt", "up/many/a (1).txt"]);
    await batch([["many/a.txt", "R"]], "replace");
    assert.equal(fs.readFileSync(path.join(W1, "up/many/a.txt"), "utf8"), "R");
    // The guards are upload's: no .git, no `..`, no file over a folder, no short body.
    assert.equal((await batch([[".git/hooks/x", "x"]], "", "")).status, 400);
    assert.equal((await batch([["../out", "x"]])).status, 400);
    assert.equal((await batch([["many", "x"]])).status, 409);
    const short = body([["s.txt", "12345"]]).subarray(0, -2);
    const cut = await request("POST", `/api/lanes/${lane1}/fs/upload-batch?dir=up`, short, {
      "Content-Type": "application/octet-stream",
    });
    assert.equal(cut.status, 400);
    assert.ok(!fs.existsSync(path.join(W1, "up/s.txt")));
  });

  it("resumes an upload sent in parts, and writes it only once every byte is staged", async () => {
    const staging = require("../lib/upload-staging");
    const id = "resume-test-0000000001";
    const data = Buffer.from("0123456789abcdefghij");
    const part = (offset, bytes, upload = id) =>
      request(
        "POST",
        `/api/lanes/${lane1}/fs/upload-part?upload=${upload}&offset=${offset}&total=${data.length}`,
        bytes,
        { "Content-Type": "application/octet-stream" }
      );
    const status = async () =>
      (await request("GET", `/api/lanes/${lane1}/fs/upload-part?upload=${id}`)).body;
    assert.deepEqual(await status(), { received: 0, total: null, done: false });
    assert.equal((await part(0, data.subarray(0, 8))).body.received, 8);
    // A part that does not start where the staged bytes end: 409 with the truth.
    const off = await part(4, data.subarray(4, 12));
    assert.equal(off.status, 409);
    assert.equal(off.body.error.code, "EOFFSET");
    assert.equal(off.body.error.received, 8);
    // Committing early writes nothing.
    const early = await request(
      "POST",
      `/api/lanes/${lane1}/fs/upload?path=res/file.bin&staged=${id}`
    );
    assert.equal(early.status, 409);
    assert.equal(early.body.error.code, "EINCOMPLETE");
    assert.ok(!fs.existsSync(path.join(W1, "res/file.bin")));
    // A part past the end is refused.
    assert.equal((await part(8, Buffer.alloc(13))).status, 413);
    assert.equal((await status()).received, 8);
    assert.equal((await part(8, data.subarray(8))).body.received, data.length);
    const commit = () =>
      request("POST", `/api/lanes/${lane1}/fs/upload?path=res/file.bin&staged=${id}`);
    const done = await commit();
    assert.equal(done.status, 201);
    assert.deepEqual(done.body, { path: "res/file.bin" });
    assert.deepEqual(fs.readFileSync(path.join(W1, "res/file.bin")), data);
    // A commit whose answer was lost is answered again, never written twice.
    fs.writeFileSync(path.join(W1, "res/file.bin"), "changed since");
    const again = await commit();
    assert.equal(again.status, 201);
    assert.deepEqual(again.body, { path: "res/file.bin" });
    assert.equal(fs.readFileSync(path.join(W1, "res/file.bin"), "utf8"), "changed since");
    assert.deepEqual(await status(), { received: data.length, total: data.length, done: true });
    // A taken name keeps the staged bytes for a retry with another policy.
    const id2 = "resume-test-0000000002";
    await part(0, data, id2);
    const taken = await request(
      "POST",
      `/api/lanes/${lane1}/fs/upload?path=res/file.bin&staged=${id2}`
    );
    assert.equal(taken.status, 409);
    assert.equal(taken.body.error.code, "EEXISTS");
    const kept = await request(
      "POST",
      `/api/lanes/${lane1}/fs/upload?path=res/file.bin&staged=${id2}&conflict=keep`
    );
    assert.equal(kept.body.path, "res/file (1).bin");
    assert.deepEqual(fs.readFileSync(path.join(W1, "res/file (1).bin")), data);
    // A batch goes the same way.
    const head = Buffer.from(JSON.stringify({ files: [{ path: "b1.txt", size: 2 }] }));
    const len = Buffer.alloc(4);
    len.writeUInt32BE(head.length);
    const batch = Buffer.concat([len, head, Buffer.from("hi")]);
    const id3 = "resume-test-0000000003";
    await request(
      "POST",
      `/api/lanes/${lane1}/fs/upload-part?upload=${id3}&offset=0&total=${batch.length}`,
      batch,
      { "Content-Type": "application/octet-stream" }
    );
    const b = await request("POST", `/api/lanes/${lane1}/fs/upload-batch?dir=res&staged=${id3}`);
    assert.equal(b.status, 201);
    assert.equal(fs.readFileSync(path.join(W1, "res/b1.txt"), "utf8"), "hi");
    // Stop: forgotten. A bad id or an unknown upload is refused, never a path.
    assert.equal(
      (await request("DELETE", `/api/lanes/${lane1}/fs/upload-part?upload=${id}`)).status,
      200
    );
    assert.equal((await status()).received, 0);
    assert.equal(
      (await request("GET", `/api/lanes/${lane1}/fs/upload-part?upload=../../etc`)).status,
      400
    );
    assert.equal(
      (await request("POST", `/api/lanes/${lane1}/fs/upload?path=x&staged=nope-nope-nope-nope`))
        .status,
      404
    );
    // Uploads are per user: another user's key never sees this one.
    assert.equal(staging.status("42", id3).received, 0);
    assert.ok(fs.statSync(path.join(staging.root(), "local")).isDirectory());
    for (const i of [id2, id3]) staging.drop("local", i);
  });

  it("keeps the bytes of a part cut short, caps unfinished uploads, sweeps old ones", async () => {
    const staging = require("../lib/upload-staging");
    const { Readable } = require("node:stream");
    const id = "cut-short-0000000001";
    let sent = false;
    const cut = new Readable({
      read() {
        if (!sent) {
          sent = true;
          this.push(Buffer.from("abcd"));
        } else setTimeout(() => this.destroy(new Error("connection reset")), 30);
      },
    });
    await assert.rejects(staging.putPart("u1", id, { offset: 0, total: 10, stream: cut }));
    assert.equal(staging.status("u1", id).received, 4);
    const rest = Readable.from([Buffer.from("efghij")]);
    assert.equal(
      (await staging.putPart("u1", id, { offset: 4, total: 10, stream: rest })).received,
      10
    );
    // At most MAX_OPEN unfinished uploads per user.
    for (let i = 1; i < staging.MAX_OPEN; i++) {
      await staging.putPart("u1", `cap-test-${String(i).padStart(10, "0")}`, {
        offset: 0,
        total: 5,
        stream: Readable.from([Buffer.from("a")]),
      });
    }
    await assert.rejects(
      staging.putPart("u1", "cap-test-overflow-01", {
        offset: 0,
        total: 5,
        stream: Readable.from([Buffer.from("a")]),
      }),
      { code: "ETOOMANY" }
    );
    // A day untouched: swept.
    staging.sweep(Date.now() + staging.KEEP_MS + 60_000);
    assert.equal(staging.status("u1", id).received, 0);
    assert.deepEqual(fs.readdirSync(path.join(staging.root(), "u1")), []);
  });

  it("zips files and folders into one download that unzips to the same bytes", async () => {
    const r = await request("GET", `/api/lanes/${lane1}/fs/zip?p=src&p=site/css/app.css`);
    assert.equal(r.status, 200);
    assert.equal(r.headers.get("content-type"), "application/zip");
    const z = new AdmZip(r.buf);
    const got = Object.fromEntries(
      z
        .getEntries()
        .filter((e) => !e.isDirectory)
        .map((e) => [e.entryName, e.getData().toString()])
    );
    assert.equal(got["src/lib/x.js"], "x\n");
    assert.equal(got["app.css"], "replaced");
    assert.ok(z.getEntries().some((e) => e.entryName === "src/lib/"));
    // A secret is never in a zip.
    const s = await request("GET", `/api/lanes/${lane1}/fs/zip?p=.claude`);
    const zs = new AdmZip(s.buf);
    assert.ok(!zs.getEntries().some((e) => e.entryName.includes("settings.local.json")));
  });

  it("refuses a cross-origin write", async () => {
    const r = await request(
      "POST",
      `/api/lanes/${lane1}/fs/mkdir`,
      { path: "x" },
      { Origin: "https://evil.example" }
    );
    assert.equal(r.status, 403);
  });
});

describe("File Explorer in a member's folder (S3, run-as stubbed)", () => {
  const runAs = require("../lib/run-as");
  const fx = require("../lib/file-explorer");
  const M = path.join(ROOT, "users", "an", "proj");
  const acct = {
    name: "an",
    login: "ah-an",
    home: path.join(ROOT, "users", "an"),
    uid: process.getuid(),
  };
  const saved = {};
  let calls = [];
  before(() => {
    fs.mkdirSync(path.join(M, "d"), { recursive: true });
    fs.writeFileSync(path.join(M, "f.txt"), "f");
    for (const k of ["accountForPath", "writeAsAsync", "writeAsCanMove", "mkdirAs"])
      saved[k] = runAs[k];
    runAs.accountForPath = (p) => (String(p).startsWith(acct.home) ? acct : null);
    runAs.writeAsCanMove = () => true;
    runAs.mkdirAs = (_a, d) => calls.push(["mkdir", d]);
    runAs.writeAsAsync = async (_a, file, args) => {
      calls.push([file, ...args]);
    };
  });
  after(() => Object.assign(runAs, saved));

  it("moves and copies through write-as as the member, never with fs", async () => {
    calls = [];
    await fx.move(M, ["f.txt"], "d");
    await fx.copy(M, ["d"], "", {});
    assert.deepEqual(calls[0], [path.join(M, "f.txt"), "move", path.join(M, "d", "f.txt")]);
    assert.deepEqual(calls[1], [path.join(M, "d"), "copy", path.join(M, "d (1)")]);
    assert.ok(fs.existsSync(path.join(M, "f.txt")), "the host itself moved nothing");
  });

  it("writes a batch as ONE write-as extract whose tar real tar unpacks", async () => {
    const { spawn } = require("node:child_process");
    const prev = [runAs.writeAsAsync, runAs.writeAsCanExtract];
    const runs = [];
    runAs.writeAsCanExtract = () => true;
    runAs.writeAsAsync = (_a, file, args, { input }) => {
      runs.push([file, ...args]);
      return new Promise((resolve, reject) => {
        const tar = spawn("tar", ["-x", "-k", "-p", "--no-same-owner", "-f", "-", "-C", file]);
        let err = "";
        tar.stderr.on("data", (d) => (err += d));
        tar.on("close", (code) => (code ? reject(new Error(err)) : resolve()));
        input.pipe(tar.stdin);
      });
    };
    try {
      const long = `${"x".repeat(150)}/${"y".repeat(90)}.txt`;
      const list = [
        ["b/one.txt", "1"],
        ["b/sub/two.txt", "22"],
        [long, "L"],
      ];
      const head = Buffer.from(
        JSON.stringify({ files: list.map(([p, c]) => ({ path: p, size: c.length })) })
      );
      const len = Buffer.alloc(4);
      len.writeUInt32BE(head.length);
      const { Readable } = require("node:stream");
      const out = await fx.uploadBatch(
        M,
        "d",
        Readable.from([Buffer.concat([len, head, ...list.map(([, c]) => Buffer.from(c))])])
      );
      assert.equal(out.saved, 3);
      assert.deepEqual(runs, [[path.join(M, "d"), "extract"]]);
      for (const [p, c] of list) assert.equal(fs.readFileSync(path.join(M, "d", p), "utf8"), c);
      assert.equal((fs.statSync(path.join(M, "d/b/one.txt")).mode & 0o777).toString(8), "644");
      // An old helper: the check says "no batch", the batch says EUPGRADE.
      runAs.writeAsCanExtract = () => false;
      assert.equal((await fx.uploadCheck(M, "d", ["z.txt"])).batch, false);
    } finally {
      [runAs.writeAsAsync, runAs.writeAsCanExtract] = prev;
    }
  });

  it("writes an upload to a hidden temp file and moves it onto the name only when complete", async () => {
    const { Readable } = require("node:stream");
    const prev = runAs.writeAsAsync;
    const runs = [];
    // write-as as a shell would run it: `cat >file` takes whatever arrived.
    runAs.writeAsAsync = async (_a, file, args, { input } = {}) => {
      runs.push([path.basename(file), ...args.map((a) => path.basename(a))]);
      if (!args.length) {
        const chunks = [];
        for await (const c of input) chunks.push(c);
        fs.writeFileSync(file, Buffer.concat(chunks));
      } else if (args[0] === "move") fs.renameSync(file, args[1]);
      else if (args[0] === "remove") fs.rmSync(file, { force: true });
    };
    try {
      const out = await fx.upload(M, "up.txt", Readable.from([Buffer.from("whole")]), {
        length: "5",
      });
      assert.equal(out.path, "up.txt");
      assert.equal(fs.readFileSync(path.join(M, "up.txt"), "utf8"), "whole");
      assert.match(runs[0][0], /^\.up\.txt\.agenthub-upload-/);
      assert.deepEqual(runs[1].slice(1), ["move", "up.txt"]);
      // The body ended early (a dropped connection, a dying server): nothing
      // under the real name, and the temp file is removed.
      runs.length = 0;
      await assert.rejects(
        fx.upload(M, "cut.txt", Readable.from([Buffer.from("par")]), { length: "10" }),
        { code: "EBADBODY" }
      );
      assert.ok(!fs.existsSync(path.join(M, "cut.txt")));
      assert.deepEqual(
        fs.readdirSync(M).filter((n) => n.includes("agenthub-upload")),
        []
      );
      assert.deepEqual(
        runs.map((r) => r[1] ?? "write"),
        ["write", "remove"]
      );
    } finally {
      runAs.writeAsAsync = prev;
    }
  });

  it("says the helper needs updating instead of failing obscurely", async () => {
    runAs.writeAsCanMove = () => false;
    try {
      await assert.rejects(fx.rename(M, "f.txt", "g.txt"), { code: "EUPGRADE" });
    } finally {
      runAs.writeAsCanMove = () => true;
    }
  });
});