@intentius/chant-lexicon-fly 0.18.5 → 0.18.7

package/src/op/activities/sprite-config.ts

@@ -0,0 +1,246 @@
+/**
+ * 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.
+ */
+
+import { resolveSpritesEndpoint, defaultSpritesHttp, type SpritesHttp } from "./sprites";
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Network policy ──────────────────────────────────────────────────────────────
+
+/** One outbound rule. Ordered — specificity is positional, so order is significant. */
+export interface NetworkRule {
+  domain: string;
+  action: "allow" | "deny";
+}
+
+export interface SpriteApplyNetworkPolicyArgs {
+  id: string;
+  /** The complete desired ruleset (whole-object replace). */
+  rules: NetworkRule[];
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteApplyNetworkPolicyResult {
+  /** True when the live policy differed and was replaced; false when already converged. */
+  changed: boolean;
+}
+
+/**
+ * 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: NetworkRule[]): void {
+  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: NetworkRule[], b: NetworkRule[]): boolean {
+  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: string, id: string): string =>
+  `${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: SpriteApplyNetworkPolicyArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteApplyNetworkPolicyResult> {
+  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) as { rules?: NetworkRule[] } | undefined)?.rules ?? [];
+  if (networkRulesEqual(live, args.rules)) {
+    console.log(`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}`);
+  console.log(`policy: sprite/${args.id} applied ${args.rules.length} rules (${base})`);
+  return { changed: true };
+}
+
+// ── Services ─────────────────────────────────────────────────────────────────────
+
+/** A desired background service. Keyed by `name`; PUT is create-or-update. */
+export interface ServiceSpec {
+  name: string;
+  cmd: string;
+  args?: string[];
+  env?: Record<string, string>;
+  dir?: string;
+  /** Names of services that must start first. */
+  needs?: string[];
+  /** Route the Sprite's public URL to this port. */
+  http_port?: number;
+}
+
+export interface SpriteApplyServicesArgs {
+  id: string;
+  services: ServiceSpec[];
+  /** Start each service after applying (in dependency order). Default: false. */
+  start?: boolean;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteApplyServicesResult {
+  /** Names that were created or updated (converged services are skipped). */
+  applied: string[];
+  /** Names that were started (empty unless `start`). */
+  started: string[];
+}
+
+/**
+ * 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: ServiceSpec[]): string[] {
+  const byName = new Map<string, ServiceSpec>();
+  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: string[] = [];
+  const state = new Map<string, "visiting" | "done">();
+  const visit = (name: string, trail: string[]): void => {
+    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: Partial<ServiceSpec>, b: Partial<ServiceSpec>): boolean {
+  const norm = (s: Partial<ServiceSpec>): string =>
+    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: string, id: string): string =>
+  `${base}/v1/sprites/${encodeURIComponent(id)}/services`;
+const serviceUrl = (base: string, id: string, svc: string): string =>
+  `${servicesUrl(base, id)}/${encodeURIComponent(svc)}`;
+
+function serviceBody(s: ServiceSpec): Record<string, unknown> {
+  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: SpriteApplyServicesArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteApplyServicesResult> {
+  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<string, Partial<ServiceSpec>>();
+  if (Array.isArray(liveList)) {
+    for (const s of liveList as Array<Partial<ServiceSpec> & { name?: string }>) {
+      if (s.name) live.set(s.name, s);
+    }
+  }
+
+  const applied: string[] = [];
+  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);
+  }
+  console.log(`services: sprite/${args.id} applied ${applied.length}/${args.services.length} (${base})`);
+
+  const started: string[] = [];
+  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);
+    }
+    console.log(`services: sprite/${args.id} started ${started.length} in dependency order`);
+  }
+
+  return { applied, started };
+}

package/src/op/activities/sprite-fs.test.ts

@@ -0,0 +1,136 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import {
+  loadActivities,
+  runOpLocally,
+  phase,
+  spriteCreate,
+  spriteExec,
+  spriteWriteFile,
+  spriteReadFile,
+  type ActivityFn,
+  type ActivityProfile,
+  type OpConfig,
+} from "@intentius/chant/op";
+import { createSpritesFake } from "./sprites-fake";
+import { spriteCreate as createImpl } from "./sprites";
+import {
+  spriteWriteFile as writeImpl,
+  spriteReadFile as readImpl,
+  spriteListDir as listImpl,
+  spriteRemove as removeImpl,
+  spriteFsUrl,
+} from "./sprite-fs";
+
+// Filesystem activities (#848) end-to-end against the in-process fake (S7) — no
+// Docker, runs in CI. Direct-impl calls cover the return values; an Op-level
+// stage → process → collect proves they resolve by name and compose.
+
+const PROFILES: Record<string, ActivityProfile> = {
+  longInfra: { startToCloseTimeout: "5m", retry: { maximumAttempts: 3, initialInterval: "1ms", backoffCoefficient: 1 } },
+  fastIdempotent: { startToCloseTimeout: "5m", retry: { maximumAttempts: 2, initialInterval: "1ms", backoffCoefficient: 1 } },
+};
+
+let fake: { url: string; close(): Promise<void> };
+let activities: Map<string, ActivityFn>;
+let prevBaseUrl: string | undefined;
+
+beforeAll(async () => {
+  fake = await createSpritesFake();
+  prevBaseUrl = process.env.SPRITES_BASE_URL;
+  process.env.SPRITES_BASE_URL = fake.url;
+  activities = await loadActivities(["fly"]);
+});
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  await fake?.close();
+});
+
+async function inspect(id: string): Promise<{ fs: Record<string, string> }> {
+  const res = await fetch(`${fake.url}/v1/sprites/${id}`);
+  return (await res.json()) as { fs: Record<string, string> };
+}
+
+describe("spriteFsUrl (pure)", () => {
+  test("builds a query string, dropping unset params", () => {
+    expect(spriteFsUrl("http://h", "s 1", "write", { path: "/a", mkdir: true, mode: undefined, workingDir: "" })).toBe(
+      "http://h/v1/sprites/s%201/fs/write?path=%2Fa&mkdir=true",
+    );
+  });
+  test("no params → no query", () => {
+    expect(spriteFsUrl("http://h", "s", "read", {})).toBe("http://h/v1/sprites/s/fs/read");
+  });
+});
+
+describe("fs activities resolve by name", () => {
+  test("loadActivities([\"fly\"]) exposes the four fs activities", () => {
+    for (const fn of ["spriteWriteFile", "spriteReadFile", "spriteListDir", "spriteRemove"]) {
+      expect(typeof activities.get(fn)).toBe("function");
+    }
+  });
+});
+
+describe("write → read → list → remove round-trip", () => {
+  test("round-trips against the fake, remove is idempotent", async () => {
+    await createImpl({ name: "fs-1", endpoint: fake.url });
+
+    await writeImpl({ id: "fs-1", path: "/work/input", content: "hello", endpoint: fake.url });
+    expect((await readImpl({ id: "fs-1", path: "/work/input", endpoint: fake.url })).content).toBe("hello");
+
+    await writeImpl({ id: "fs-1", path: "/work/notes/a.txt", content: "x", endpoint: fake.url });
+    const list = await listImpl({ id: "fs-1", path: "/work", endpoint: fake.url });
+    expect(list).toEqual(
+      expect.arrayContaining([
+        { name: "notes", type: "dir" },
+        { name: "input", type: "file", size: 5 },
+      ]),
+    );
+
+    await removeImpl({ id: "fs-1", path: "/work/input", endpoint: fake.url });
+    await expect(readImpl({ id: "fs-1", path: "/work/input", endpoint: fake.url })).rejects.toThrow(/not found/);
+    // Idempotent: removing an already-gone path is a no-op (404 tolerated).
+    await expect(removeImpl({ id: "fs-1", path: "/work/input", endpoint: fake.url })).resolves.toBeDefined();
+  });
+
+  test("reading a missing file throws not-found", async () => {
+    await createImpl({ name: "fs-2", endpoint: fake.url });
+    await expect(readImpl({ id: "fs-2", path: "/nope", endpoint: fake.url })).rejects.toThrow(/not found/);
+  });
+
+  test("recursive remove clears a whole subtree", async () => {
+    await createImpl({ name: "fs-3", endpoint: fake.url });
+    await writeImpl({ id: "fs-3", path: "/d/a", content: "1", endpoint: fake.url });
+    await writeImpl({ id: "fs-3", path: "/d/sub/b", content: "2", endpoint: fake.url });
+    await removeImpl({ id: "fs-3", path: "/d", recursive: true, endpoint: fake.url });
+    expect(await listImpl({ id: "fs-3", path: "/d", endpoint: fake.url })).toEqual([]);
+  });
+});
+
+describe("Op-level stage → process → collect (the example flow)", () => {
+  test("write input, exec copies it, read output — runs green by-name", async () => {
+    const op: OpConfig = {
+      name: "fs-agent-task",
+      overview: "stage an input file, process it, collect the result",
+      taskQueue: "sprites",
+      phases: [
+        phase("Create", [spriteCreate({ name: "fs-op-1" })]),
+        phase("Stage", [spriteWriteFile({ id: "fs-op-1", path: "/work/input", content: "hello" })]),
+        phase("Run", [spriteExec({ id: "fs-op-1", cmd: "cat /work/input > /work/output" })]),
+        phase("Collect", [spriteReadFile({ id: "fs-op-1", path: "/work/output" })]),
+      ],
+    };
+    const result = await runOpLocally(op, activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(result.records.map((r) => r.fn)).toEqual([
+      "spriteCreate",
+      "spriteWriteFile",
+      "spriteExec",
+      "spriteReadFile",
+    ]);
+    expect(result.records.every((r) => r.status === "ok")).toBe(true);
+
+    const state = await inspect("fs-op-1");
+    expect(state.fs["/work/output"]).toBe("hello");
+  });
+});

package/src/op/activities/sprite-fs.ts

@@ -0,0 +1,217 @@
+/**
+ * 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 mirror `sprites.ts` — an explicit `endpoint` /
+ * `token` wins, then `SPRITES_BASE_URL` / `SPRITES_API_TOKEN`.
+ */
+
+import { resolveSpritesEndpoint } from "./sprites";
+
+function safeJson(text: string): unknown {
+  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: string,
+  id: string,
+  op: "read" | "write" | "list" | "delete",
+  params: Record<string, string | boolean | undefined>,
+): string {
+  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}` : ""}`;
+}
+
+// ── Raw HTTP client (raw string bodies, mirrors defaultSpritesHttp) ─────────────
+
+/**
+ * Injectable raw HTTP client — like `SpritesHttp` but the body is sent verbatim
+ * (a file's bytes as a string), not JSON-encoded, and the response `text` is the
+ * raw body. Tests inject a fake; the default hits `fetch`.
+ */
+export type SpritesRawHttp = (
+  method: string,
+  url: string,
+  body?: string,
+  headers?: Record<string, string>,
+  signal?: AbortSignal,
+) => Promise<{ status: number; text: string }>;
+
+/**
+ * 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
+ * defaults to `SPRITES_API_TOKEN` at call time. `fetchImpl` is injectable.
+ */
+export function defaultSpritesRawHttp(token?: string, fetchImpl: typeof fetch = fetch): SpritesRawHttp {
+  return async (method, url, body, headers, signal) => {
+    const h: Record<string, string> = { ...headers };
+    if (body !== undefined) h["content-type"] = "application/octet-stream";
+    const tok = token ?? process.env.SPRITES_API_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() };
+  };
+}
+
+// ── Activity contracts ──────────────────────────────────────────────────────────
+
+export interface SpriteWriteFileArgs {
+  /** Target sprite id (the `name` passed to `spriteCreate`). */
+  id: string;
+  /** Absolute path (or relative to `workingDir`) to write. */
+  path: string;
+  /** File contents. */
+  content: string;
+  /** Octal file mode, e.g. `"0644"`. */
+  mode?: string;
+  /** Create missing parent directories. */
+  mkdir?: boolean;
+  /** Base directory for a relative `path`. */
+  workingDir?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteReadFileArgs {
+  id: string;
+  path: string;
+  workingDir?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteReadFileResult {
+  content: string;
+}
+
+export interface SpriteListDirArgs {
+  id: string;
+  path: string;
+  workingDir?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+/** One directory entry. `type` is `file` or `dir`. */
+export interface SpriteDirEntry {
+  name: string;
+  type: "file" | "dir";
+  size?: number;
+}
+
+export interface SpriteRemoveArgs {
+  id: string;
+  path: string;
+  /** Remove a directory and its contents. */
+  recursive?: boolean;
+  /** Perform the delete as root. */
+  asRoot?: boolean;
+  workingDir?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+// ── 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: SpriteWriteFileArgs,
+  signal?: AbortSignal,
+  http: SpritesRawHttp = defaultSpritesRawHttp(args.token),
+): Promise<Record<string, never>> {
+  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}`);
+  }
+  console.log(`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: SpriteReadFileArgs,
+  signal?: AbortSignal,
+  http: SpritesRawHttp = defaultSpritesRawHttp(args.token),
+): Promise<SpriteReadFileResult> {
+  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: SpriteListDirArgs,
+  signal?: AbortSignal,
+  http: SpritesRawHttp = defaultSpritesRawHttp(args.token),
+): Promise<SpriteDirEntry[]> {
+  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 as SpriteDirEntry[];
+  const entries = (parsed as { entries?: unknown } | undefined)?.entries;
+  return Array.isArray(entries) ? (entries as SpriteDirEntry[]) : [];
+}
+
+/**
+ * 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: SpriteRemoveArgs,
+  signal?: AbortSignal,
+  http: SpritesRawHttp = defaultSpritesRawHttp(args.token),
+): Promise<Record<string, never>> {
+  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}`);
+  }
+  console.log(`removed: sprite/${args.id}:${args.path}`);
+  return {};
+}