@intentius/chant-lexicon-fly 0.124.31 → 0.124.32

package/dist/op/activities/sprite-config.js

@@ -0,0 +1,409 @@
+/**
+ * Sprite config reconcile activities (#849) — the two pieces of genuine
+ * desired-state a Sprite carries: its outbound network policy and its background
+ * services. Unlike the sprite itself (an Op primitive with no reconcilable
+ * create body), these are set after create and persist across cold boots, so
+ * chant reconciles typed config against the live Sprite — the `flyApply`
+ * plan→CRUD pattern scoped to one Sprite, not a declarable resource.
+ *
+ * Both use the JSON `SpritesHttp` client from `sprites.ts`; endpoint + bearer
+ * resolution is shared. Validation is pure and runs before any HTTP (invalid
+ * rules / a `needs` cycle throw up front), so a bad config fails the step
+ * cleanly rather than half-applying.
+ *
+ * Scope (v1): network policy is a whole-object replace (converges by
+ * construction); services reconcile is additive + update (create-or-update each
+ * desired service, optionally start). Owned-only prune of stale services is out
+ * of scope — the documented Services REST surface exposes no delete.
+ *
+ * `spriteApplyServices` with no `id` runs inside the sprite instead (#2880):
+ * it applies the box block's services (`box: true`) through `sprite-env
+ * services`, which has no update, so a changed service is deleted and created.
+ * It deletes nothing the box block does not declare.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { serviceCommandArgv, inStartOrder, boxServices } from "./box-services.js";
+import { findSpriteEnv } from "./sprite-service-converge.js";
+import { resolveSpritesEndpoint, defaultSpritesHttp } from "./sprites.js";
+import { logProgress } from "./progress.js";
+const execFileAsync = promisify(execFile);
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Validate a ruleset: every rule needs a non-empty `domain` and an `allow`/`deny`
+ * `action`. Pure; throws on the first offender.
+ */
+export function validateNetworkRules(rules) {
+    rules.forEach((r, i) => {
+        if (!r || typeof r.domain !== "string" || r.domain.trim() === "") {
+            throw new Error(`network rule ${i}: missing domain`);
+        }
+        if (r.action !== "allow" && r.action !== "deny") {
+            throw new Error(`network rule ${i} (${r.domain}): action must be "allow" or "deny", got ${JSON.stringify(r.action)}`);
+        }
+    });
+}
+/** Order-sensitive equality of two rulesets (position is significant). Pure. */
+export function networkRulesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((r, i) => r.domain === b[i].domain && r.action === b[i].action);
+}
+const policyUrl = (base, id) => `${base}/v1/sprites/${encodeURIComponent(id)}/policy/network`;
+/**
+ * Reconcile a Sprite's outbound network policy. GET the live ruleset, and POST
+ * the desired set only when it differs (`GET`/`POST /policy/network`). Returns
+ * whether a change was applied.
+ */
+export async function spriteApplyNetworkPolicy(args, signal, http = defaultSpritesHttp(args.token)) {
+    validateNetworkRules(args.rules);
+    const base = resolveSpritesEndpoint(args);
+    const url = policyUrl(base, args.id);
+    const cur = await http("GET", url, undefined, undefined, signal);
+    if (cur.status >= 300)
+        throw new Error(`sprite ${args.id} get policy failed (${cur.status}): ${cur.text}`);
+    const live = safeJson(cur.text)?.rules ?? [];
+    if (networkRulesEqual(live, args.rules)) {
+        logProgress(`policy: sprite/${args.id} already converged (${args.rules.length} rules)`);
+        return { changed: false };
+    }
+    const res = await http("POST", url, { rules: args.rules }, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`sprite ${args.id} set policy failed (${res.status}): ${res.text}`);
+    logProgress(`policy: sprite/${args.id} applied ${args.rules.length} rules (${base})`);
+    return { changed: true };
+}
+/**
+ * Validate a service set: names are unique, every `needs` target exists, and the
+ * dependency graph is acyclic. Pure; throws on the first violation. Returns the
+ * names in a valid start order (dependencies first).
+ */
+export function validateServices(services) {
+    const byName = new Map();
+    for (const s of services) {
+        if (!s.name)
+            throw new Error("service: missing name");
+        if (byName.has(s.name))
+            throw new Error(`service ${s.name}: duplicate name`);
+        byName.set(s.name, s);
+    }
+    for (const s of services) {
+        for (const dep of s.needs ?? []) {
+            if (!byName.has(dep))
+                throw new Error(`service ${s.name}: needs "${dep}" which is not defined`);
+        }
+    }
+    // Topological order via DFS; a back-edge is a cycle.
+    const order = [];
+    const state = new Map();
+    const visit = (name, trail) => {
+        const st = state.get(name);
+        if (st === "done")
+            return;
+        if (st === "visiting")
+            throw new Error(`service dependency cycle: ${[...trail, name].join(" -> ")}`);
+        state.set(name, "visiting");
+        for (const dep of byName.get(name).needs ?? [])
+            visit(dep, [...trail, name]);
+        state.set(name, "done");
+        order.push(name);
+    };
+    for (const s of services)
+        visit(s.name, []);
+    return order;
+}
+/** Comparable service config (the fields the reconcile diffs on). Pure. */
+export function serviceConfigEqual(a, b) {
+    const norm = (s) => JSON.stringify({
+        cmd: s.cmd ?? "",
+        args: s.args ?? [],
+        env: s.env ?? {},
+        dir: s.dir ?? "",
+        needs: s.needs ?? [],
+        http_port: s.http_port ?? null,
+    });
+    return norm(a) === norm(b);
+}
+const servicesUrl = (base, id) => `${base}/v1/sprites/${encodeURIComponent(id)}/services`;
+const serviceUrl = (base, id, svc) => `${servicesUrl(base, id)}/${encodeURIComponent(svc)}`;
+function serviceBody(s) {
+    return {
+        cmd: s.cmd,
+        ...(s.args ? { args: s.args } : {}),
+        ...(s.env ? { env: s.env } : {}),
+        ...(s.dir ? { dir: s.dir } : {}),
+        ...(s.needs ? { needs: s.needs } : {}),
+        ...(s.http_port !== undefined ? { http_port: s.http_port } : {}),
+    };
+}
+/**
+ * Reconcile a Sprite's background services (additive + update). Lists the live
+ * services, then `PUT`s each desired service that is new or changed
+ * (create-or-update by name); when `start` is set, `POST .../start`s them in
+ * dependency order. Converged services are skipped. Owned-only prune is out of
+ * scope (no delete in the Services REST surface).
+ */
+export async function spriteApplyServices(args, signal, http) {
+    if (!args.id)
+        return applyThroughSpriteEnv(args, signal);
+    if (args.box || args.only || args.restart) {
+        throw new Error("spriteApplyServices: box, only and restart apply a box's services through sprite-env inside the sprite; drop the id to use them");
+    }
+    if (!args.services)
+        throw new Error("spriteApplyServices: an id needs its services");
+    return applyThroughApi({ ...args, id: args.id, services: args.services }, signal, http ?? defaultSpritesHttp(args.token));
+}
+async function applyThroughApi(args, signal, http) {
+    const startOrder = validateServices(args.services);
+    const base = resolveSpritesEndpoint(args);
+    const byName = new Map(args.services.map((s) => [s.name, s]));
+    // Live services, keyed by name, for the create-vs-update diff.
+    const listRes = await http("GET", servicesUrl(base, args.id), undefined, undefined, signal);
+    if (listRes.status >= 300)
+        throw new Error(`sprite ${args.id} list services failed (${listRes.status}): ${listRes.text}`);
+    const liveList = safeJson(listRes.text);
+    const live = new Map();
+    if (Array.isArray(liveList)) {
+        for (const s of liveList) {
+            if (s.name)
+                live.set(s.name, s);
+        }
+    }
+    const applied = [];
+    for (const s of args.services) {
+        const cur = live.get(s.name);
+        if (cur && serviceConfigEqual(cur, s))
+            continue; // already converged
+        const res = await http("PUT", serviceUrl(base, args.id, s.name), serviceBody(s), undefined, signal);
+        if (res.status >= 300)
+            throw new Error(`sprite ${args.id} apply service ${s.name} failed (${res.status}): ${res.text}`);
+        applied.push(s.name);
+    }
+    logProgress(`services: sprite/${args.id} applied ${applied.length}/${args.services.length} (${base})`);
+    const started = [];
+    if (args.start) {
+        for (const name of startOrder) {
+            if (!byName.has(name))
+                continue;
+            const res = await http("POST", `${serviceUrl(base, args.id, name)}/start`, undefined, undefined, signal);
+            if (res.status >= 300)
+                throw new Error(`sprite ${args.id} start service ${name} failed (${res.status}): ${res.text}`);
+            started.push(name);
+        }
+        logProgress(`services: sprite/${args.id} started ${started.length} in dependency order`);
+    }
+    return { applied, started };
+}
+/**
+ * `sprite-env services list` with each service's definition. A sprite's
+ * sprite-env prints JSON (`[{ name, cmd, args, needs, http_port, state: {
+ * status } }]`); the studio kit's stand-in has printed a table of name,
+ * state, needs (`-` for none), http port (`-`) and cmd, tab-separated. A
+ * table with fewer columns gives the name and state only. Pure.
+ */
+export function parseServiceDefinitions(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return [];
+    if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+        const parsed = JSON.parse(trimmed);
+        const list = Array.isArray(parsed) ? parsed : (parsed.services ?? []);
+        const out = [];
+        for (const s of list) {
+            if (typeof s?.name !== "string")
+                continue;
+            const state = s.state;
+            const status = typeof state?.status === "string" ? state.status : typeof s.status === "string" ? s.status : null;
+            const args = Array.isArray(s.args) ? s.args.map(String) : [];
+            out.push({
+                name: s.name,
+                status,
+                ...(typeof s.cmd === "string" ? { cmd: args.length > 0 ? [s.cmd, ...args].join(" ") : s.cmd } : {}),
+                ...(Array.isArray(s.needs) ? { needs: s.needs.map(String) } : s.needs === null ? { needs: [] } : {}),
+                ...("http_port" in s ? { httpPort: typeof s.http_port === "number" && s.http_port > 0 ? s.http_port : null } : {}),
+            });
+        }
+        return out;
+    }
+    const out = [];
+    for (const line of trimmed.split("\n")) {
+        const cols = line.split("\t");
+        const name = cols[0]?.trim();
+        if (!name)
+            continue;
+        const listed = { name, status: cols[1]?.trim() || null };
+        if (cols.length >= 5) {
+            const needs = cols[2].trim();
+            const port = cols[3].trim();
+            listed.needs = needs === "-" || needs === "" ? [] : needs.split(",");
+            listed.httpPort = port === "-" || port === "" ? null : Number(port);
+            listed.cmd = cols.slice(4).join("\t");
+        }
+        out.push(listed);
+    }
+    return out;
+}
+/** Whether a listed service differs from the declared one in `cmd`, `needs` or `httpPort`. A field the listing does not carry is not compared. Pure. */
+export function listedServiceDiffers(listed, declared, cmd) {
+    if (listed.cmd !== undefined && listed.cmd !== cmd)
+        return `cmd ${JSON.stringify(listed.cmd)} is now ${JSON.stringify(cmd)}`;
+    if (listed.needs !== undefined) {
+        const a = [...listed.needs].sort().join(",");
+        const b = [...declared.needs].sort().join(",");
+        if (a !== b)
+            return `needs [${a}] is now [${b}]`;
+    }
+    if (listed.httpPort !== undefined && (listed.httpPort ?? null) !== declared.httpPort)
+        return `httpPort ${listed.httpPort ?? "none"} is now ${declared.httpPort ?? "none"}`;
+    return null;
+}
+/**
+ * The arguments of `sprite-env services create` for a declared service.
+ * `argv` is the command from {@link serviceCommandArgv}: its first word is
+ * `--cmd`, the rest `--args` (comma-separated), as sprite-env and upstream
+ * Sprites take them; neither runs `--cmd` through a shell. A string is split
+ * on whitespace. With a `duration`, sprite-env streams the service's output
+ * for that long and fails the create if the service exits in it, so
+ * `--no-stream` (which returns as soon as the service is defined) is passed
+ * only without one. Pure.
+ */
+export function spriteEnvCreateArgs(s, argv) {
+    const [cmd, ...rest] = typeof argv === "string" ? argv.trim().split(/\s+/) : argv;
+    return [
+        "services",
+        "create",
+        s.name,
+        "--cmd",
+        cmd,
+        ...(rest.length > 0 ? ["--args", rest.join(",")] : []),
+        ...(s.needs.length > 0 ? ["--needs", s.needs.join(",")] : []),
+        ...(s.httpPort !== null ? ["--http-port", String(s.httpPort)] : []),
+        ...(s.duration !== null ? ["--duration", s.duration] : ["--no-stream"]),
+    ];
+}
+/** The states a service is in once started: `start` leaves it be. */
+const UP = new Set(["running", "starting"]);
+/**
+ * Apply the box block's services through sprite-env, in dependency order:
+ * create a declared service the supervisor doesn't have, delete and create
+ * one whose `cmd`, `needs` or `httpPort` differ from what the list reports,
+ * and leave a converged one running (restart it with `restart`). Then, with
+ * `start`, start each applied service that is not running.
+ */
+async function applyThroughSpriteEnv(args, signal) {
+    if (!args.box)
+        throw new Error("spriteApplyServices: without an id it applies the box block's services through sprite-env; pass box: true (or an id and services for the Sprites API)");
+    if (args.services)
+        throw new Error("spriteApplyServices: box: true reads the services from the box block, so it takes no services beside it");
+    const declared = await boxServices();
+    const names = new Set(declared.map((s) => s.name));
+    const unknown = (args.only ?? []).filter((n) => !names.has(n));
+    if (unknown.length > 0) {
+        throw new Error(`spriteApplyServices: only names ${unknown.join(", ")}, which the box block does not declare; declared: ${[...names].join(", ") || "none"}`);
+    }
+    const only = args.only ? new Set(args.only) : null;
+    const targets = inStartOrder(declared).filter((s) => (only ? only.has(s.name) : !s.optional));
+    // Expand every command before changing anything, so a missing variable fails the step with nothing half-applied.
+    const commands = new Map(targets.map((s) => [s.name, serviceCommandArgv(s.name, s.cmd)]));
+    const bin = findSpriteEnv(args.spriteEnv);
+    if (!bin)
+        throw new Error("spriteApplyServices: no sprite-env on PATH or in /.sprite/bin, and no sprite id to reach the Sprites API with");
+    const spriteEnv = async (argv) => {
+        try {
+            return (await execFileAsync(bin, argv, { signal, timeout: 120000, maxBuffer: 16 * 1024 * 1024 })).stdout;
+        }
+        catch (err) {
+            const e = err;
+            throw new Error(`sprite-env ${argv.slice(0, 3).join(" ")} failed: ${(e.stderr || e.message || String(err)).trim()}`);
+        }
+    };
+    const live = new Map(parseServiceDefinitions(await spriteEnv(["services", "list"])).map((s) => [s.name, s]));
+    // A full apply leaves the supervisor with the declared services only: one
+    // the block no longer declares is deleted, before anything is defined, so
+    // the HTTP port or a name it held is free. Dependants go before what they need.
+    const services = [];
+    if (!only && args.prune !== false) {
+        const undeclared = new Set([...live.keys()].filter((n) => !names.has(n)));
+        while (undeclared.size > 0) {
+            const needed = new Set([...undeclared].flatMap((n) => live.get(n)?.needs ?? []));
+            const next = [...undeclared].sort().find((n) => !needed.has(n)) ?? [...undeclared].sort()[0];
+            await spriteEnv(["services", "delete", next]);
+            logProgress(`services: deleted ${next}, which the box block does not declare`);
+            services.push({ name: next, action: "deleted" });
+            undeclared.delete(next);
+            live.delete(next);
+        }
+    }
+    // The supervisor gives one service the HTTP port and refuses a second holder
+    // (409) while the first still has it. So a service whose listed port is not
+    // the declared one is replaced first, before any service is defined with a
+    // port: when the port moves from one service to another, the old holder has
+    // let go of it by the time the new one asks. One whose declared needs are not
+    // all defined yet can't be created early and waits for its turn below.
+    const released = new Set();
+    for (const s of targets) {
+        const cur = live.get(s.name);
+        if (!cur || cur.httpPort === undefined || cur.httpPort === null || cur.httpPort === s.httpPort)
+            continue;
+        if (!s.needs.every((n) => live.has(n)))
+            continue;
+        const argv = commands.get(s.name);
+        const why = listedServiceDiffers(cur, s, argv.join(" "));
+        await spriteEnv(["services", "delete", s.name]);
+        await spriteEnv(spriteEnvCreateArgs(s, argv));
+        logProgress(`services: replaced ${s.name} (${why}) first, to free the HTTP port`);
+        released.add(s.name);
+    }
+    for (const s of targets) {
+        if (released.has(s.name)) {
+            services.push({ name: s.name, action: "replaced" });
+            continue;
+        }
+        const argv = commands.get(s.name);
+        const cmd = argv.join(" ");
+        const cur = live.get(s.name);
+        if (!cur) {
+            await spriteEnv(spriteEnvCreateArgs(s, argv));
+            logProgress(`services: created ${s.name}`);
+            services.push({ name: s.name, action: "created" });
+            continue;
+        }
+        const why = listedServiceDiffers(cur, s, cmd);
+        if (why) {
+            await spriteEnv(["services", "delete", s.name]);
+            await spriteEnv(spriteEnvCreateArgs(s, argv));
+            logProgress(`services: replaced ${s.name} (${why})`);
+            services.push({ name: s.name, action: "replaced" });
+            continue;
+        }
+        if (args.restart) {
+            await spriteEnv(["services", "restart", s.name]);
+            logProgress(`services: restarted ${s.name}`);
+            services.push({ name: s.name, action: "restarted" });
+            continue;
+        }
+        services.push({ name: s.name, action: "left" });
+    }
+    const started = [];
+    if (args.start) {
+        for (const entry of services) {
+            if (entry.action !== "left" || UP.has(live.get(entry.name)?.status ?? ""))
+                continue;
+            await spriteEnv(["services", "start", entry.name]);
+            logProgress(`services: started ${entry.name}`);
+            entry.action = "started";
+            started.push(entry.name);
+        }
+    }
+    const applied = services.filter((e) => e.action === "created" || e.action === "replaced").map((e) => e.name);
+    const deleted = services.filter((e) => e.action === "deleted").length;
+    logProgress(`services: applied ${applied.length}/${targets.length} through sprite-env, started ${started.length}${deleted > 0 ? `, deleted ${deleted}` : ""}`);
+    return { applied, started, services };
+}

package/dist/op/activities/sprite-fs.js

@@ -0,0 +1,131 @@
+/**
+ * Sprite filesystem activities (#848) — imperative file-I/O primitives over the
+ * Sprites filesystem API (`/v1/sprites/{id}/fs/*`). Same category as the
+ * lifecycle activities in `sprites.ts`: runtime-orchestration primitives, no
+ * desired state. They let an Op stage an input file into a sprite and read a
+ * result out without shelling it through `spriteExec` + `cat`/`tee`.
+ *
+ * read/write move raw file bytes in the body (not JSON), so these use a small
+ * raw HTTP client (`SpritesRawHttp`) rather than the JSON `SpritesHttp` the
+ * lifecycle activities use; path/mode/mkdir/recursive ride as query params.
+ * Endpoint + bearer resolution go through `sprites.ts`'s shared resolvers
+ * (`resolveSpritesEndpoint`/`resolveSpritesToken`) — an explicit `endpoint` /
+ * `token` wins, then `SPRITES_BASE_URL`/`SPRITES_API_URL`, then
+ * `SPRITES_API_TOKEN`/its `SPRITE_TOKEN` alias (#2711, #2765: this module
+ * used to read `SPRITES_API_TOKEN` directly, missing the alias the other
+ * Sprites activities honor).
+ */
+import { resolveSpritesEndpoint, resolveSpritesToken } from "./sprites.js";
+import { logProgress } from "./progress.js";
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── Pure URL builders (unit-testable) ──────────────────────────────────────────
+/**
+ * Build a `/v1/sprites/{id}/fs/{op}?...` URL. `params` values that are undefined
+ * or empty are dropped so the query only carries what the caller set. Pure.
+ */
+export function spriteFsUrl(base, id, op, params) {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === "")
+            continue;
+        q.set(k, typeof v === "boolean" ? String(v) : v);
+    }
+    const qs = q.toString();
+    return `${base}/v1/sprites/${encodeURIComponent(id)}/fs/${op}${qs ? `?${qs}` : ""}`;
+}
+/**
+ * Default `fetch`-based raw client. Sends the body as-is with an
+ * `application/octet-stream` content-type and `Authorization: Bearer <token>`
+ * when a token is set (real Sprites); the fake ignores the token. The token
+ * resolves through `resolveSpritesToken` at call time — `SPRITES_API_TOKEN`,
+ * then its `SPRITE_TOKEN` alias (#2711, #2765) — the same resolver
+ * `sprites.ts`'s `defaultSpritesHttp` uses, so every fs activity
+ * (`spriteWriteFile`, `spriteReadFile`, `spriteListDir`, `spriteRemove`)
+ * authenticates the same way the lifecycle activities do. `fetchImpl` is
+ * injectable.
+ */
+export function defaultSpritesRawHttp(token, fetchImpl = fetch) {
+    return async (method, url, body, headers, signal) => {
+        const h = { ...headers };
+        if (body !== undefined)
+            h["content-type"] = "application/octet-stream";
+        const tok = resolveSpritesToken(token);
+        if (tok)
+            h["authorization"] = `Bearer ${tok}`;
+        const res = await fetchImpl(url, {
+            method,
+            headers: Object.keys(h).length ? h : undefined,
+            body,
+            signal,
+        });
+        return { status: res.status, text: await res.text() };
+    };
+}
+// ── Activities (ActivityFn: (args, signal?) => Promise<unknown>) ──────────────
+/** Write a file into the sprite. `PUT /v1/sprites/{id}/fs/write` with raw body. */
+export async function spriteWriteFile(args, signal, http = defaultSpritesRawHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const url = spriteFsUrl(base, args.id, "write", {
+        path: args.path,
+        mode: args.mode,
+        mkdir: args.mkdir,
+        workingDir: args.workingDir,
+    });
+    const res = await http("PUT", url, args.content, undefined, signal);
+    if (res.status >= 300) {
+        throw new Error(`sprite ${args.id} write ${args.path} failed (${res.status}): ${res.text}`);
+    }
+    logProgress(`wrote: sprite/${args.id}:${args.path} (${args.content.length}b)`);
+    return {};
+}
+/** Read a file from the sprite. `GET /v1/sprites/{id}/fs/read` → raw body. */
+export async function spriteReadFile(args, signal, http = defaultSpritesRawHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const url = spriteFsUrl(base, args.id, "read", { path: args.path, workingDir: args.workingDir });
+    const res = await http("GET", url, undefined, undefined, signal);
+    if (res.status === 404)
+        throw new Error(`sprite ${args.id} read ${args.path}: not found`);
+    if (res.status >= 300)
+        throw new Error(`sprite ${args.id} read ${args.path} failed (${res.status}): ${res.text}`);
+    return { content: res.text };
+}
+/** List a directory in the sprite. `GET /v1/sprites/{id}/fs/list` → entry array. */
+export async function spriteListDir(args, signal, http = defaultSpritesRawHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const url = spriteFsUrl(base, args.id, "list", { path: args.path, workingDir: args.workingDir });
+    const res = await http("GET", url, undefined, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`sprite ${args.id} list ${args.path} failed (${res.status}): ${res.text}`);
+    const parsed = safeJson(res.text);
+    // Accept a bare array or a `{ entries: [...] }` envelope.
+    if (Array.isArray(parsed))
+        return parsed;
+    const entries = parsed?.entries;
+    return Array.isArray(entries) ? entries : [];
+}
+/**
+ * Remove a path in the sprite. `DELETE /v1/sprites/{id}/fs/delete`. Idempotent:
+ * a 404 (already gone) is a no-op, matching `rm -f` and the destroy activity.
+ */
+export async function spriteRemove(args, signal, http = defaultSpritesRawHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const url = spriteFsUrl(base, args.id, "delete", {
+        path: args.path,
+        recursive: args.recursive,
+        asRoot: args.asRoot,
+        workingDir: args.workingDir,
+    });
+    const res = await http("DELETE", url, undefined, undefined, signal);
+    if (res.status >= 300 && res.status !== 404) {
+        throw new Error(`sprite ${args.id} remove ${args.path} failed (${res.status}): ${res.text}`);
+    }
+    logProgress(`removed: sprite/${args.id}:${args.path}`);
+    return {};
+}