@intentius/chant-lexicon-fly 0.94.0 → 0.95.0

package/src/op/activities/sprite-box-services.test.ts

@@ -0,0 +1,318 @@
+/**
+ * #2880 — a box's services declared in its box block, observed, restarted
+ * and applied through sprite-env with `box: true`.
+ *
+ * The workspace here has one box member, `box/`, whose block declares `app`,
+ * `hud` (needing `app`) and an optional `site`. `sprite-env` is a stand-in
+ * with a sprite's command line: `services list` prints JSON in the shape a
+ * sprite's does (`[{ name, cmd, needs, http_port, state: { status } }]`),
+ * `create` refuses a name it has and a `needs` it doesn't, and every call is
+ * appended to a log the tests read. A small HTTP server answers each
+ * service's health URL with 200 while the service runs.
+ */
+
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { ConvergeOp, eq, loadActivities, run, runOpLocally, when, type ActivityFn, type OpConfig, type ResourceSymptom } from "@intentius/chant/op";
+import { convergeTick } from "@intentius/chant/op/activities";
+import { readConvergeLedger } from "@intentius/chant/lifecycle/converge-ledger";
+import { spriteApplyServices, listedServiceDiffers, parseServiceDefinitions, spriteEnvCreateArgs } from "./sprite-config";
+import { spriteServiceRestart, spriteServicesObserve } from "./sprite-service-converge";
+import { expandServiceCommand } from "./box-services";
+import { spriteServicesObserve as observeStep, spriteServiceRestart as restartStep } from "../builders";
+
+let root: string;
+let boxDir: string;
+let state: string;
+let calls: string;
+let server: Server;
+let port = 0;
+const saved = { PATH: process.env.PATH, cwd: process.cwd(), STATE: process.env.FAKE_SPRITE_STATE, RESOURCE: process.env.CHANT_CONVERGE_RESOURCE, BOX_HOME: process.env.BOX_HOME };
+
+const SPRITE_ENV = `#!/usr/bin/env node
+const { appendFileSync, readdirSync, readFileSync, writeFileSync, existsSync, rmSync } = require("node:fs");
+const { join } = require("node:path");
+const dir = process.env.FAKE_SPRITE_STATE;
+const argv = process.argv.slice(2);
+appendFileSync(join(dir, "..", "calls"), argv.join(" ") + "\\n");
+const [group, verb, name, ...rest] = argv;
+if (group !== "services") process.exit(2);
+const file = (n) => join(dir, n + ".json");
+const read = (n) => JSON.parse(readFileSync(file(n), "utf8"));
+const fail = (m) => { console.error("sprite-env: " + m); process.exit(1); };
+if (verb === "list") {
+  const out = readdirSync(dir).filter((f) => f.endsWith(".json")).sort().map((f) => {
+    const s = JSON.parse(readFileSync(join(dir, f), "utf8"));
+    return { name: s.name, cmd: s.cmd, args: [], needs: s.needs, http_port: s.httpPort, state: { name: s.name, status: s.status } };
+  });
+  console.log(JSON.stringify(out));
+} else if (verb === "create") {
+  if (existsSync(file(name))) fail("service " + name + " already exists");
+  const s = { name, cmd: null, needs: [], httpPort: 0, status: "running" };
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--no-stream") continue;
+    const v = rest[++i];
+    if (a === "--cmd") s.cmd = v;
+    else if (a === "--needs") s.needs = v.split(",");
+    else if (a === "--http-port") s.httpPort = Number(v);
+    else if (a === "--duration") s.duration = v;
+    else fail("unknown option " + a);
+  }
+  for (const n of s.needs) if (!existsSync(file(n))) fail("service " + name + " needs " + n + ", which does not exist");
+  writeFileSync(file(name), JSON.stringify(s));
+} else if (verb === "delete") {
+  if (!existsSync(file(name))) fail("no service " + name);
+  rmSync(file(name));
+} else if (["restart", "start", "stop"].includes(verb)) {
+  if (!existsSync(file(name))) fail("no service " + name);
+  const s = read(name);
+  s.status = verb === "stop" ? "stopped" : "running";
+  writeFileSync(file(name), JSON.stringify(s));
+} else process.exit(2);
+`;
+
+// chant run <op>, as far as a converge dispatch goes: the restart the dispatched Op runs.
+const CHANT = `#!/bin/sh
+echo "$2 $CHANT_CONVERGE_RESOURCE" >> "$FAKE_SPRITE_STATE/../dispatched"
+exec sprite-env services restart "$CHANT_CONVERGE_RESOURCE"
+`;
+
+const health = (name: string) => `http://127.0.0.1:${port}/${name}`;
+
+function declare(services: unknown[]): void {
+  writeFileSync(
+    join(root, "chant.workspace.json"),
+    JSON.stringify(
+      {
+        name: "acme",
+        schema: 1,
+        members: [{ name: "box", dir: "box", kind: "other", because: "the box's steward and its Ops", box: { services } }],
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+const SERVICES = () => [
+  { name: "app", cmd: "${BOX_HOME}/run-app.sh", duration: "3s", health: health("app") },
+  { name: "hud", cmd: "${BOX_HOME}/run-daemon.sh", needs: ["app"], httpPort: 8080, duration: "3s", health: health("hud") },
+  { name: "site", cmd: "${BOX_HOME}/run-site.sh", health: health("site"), optional: true },
+];
+
+const listed = () => new Map(JSON.parse(spawnSync("sprite-env", ["services", "list"], { encoding: "utf8" }).stdout).map((s: { name: string }) => [s.name, s]));
+const takeCalls = (): string[] => {
+  const text = existsSync(calls) ? readFileSync(calls, "utf8") : "";
+  rmSync(calls, { force: true });
+  return text.split("\n").filter((l) => l && l !== "services list");
+};
+const setStatus = (name: string, status: string) => {
+  const f = join(state, `${name}.json`);
+  writeFileSync(f, JSON.stringify({ ...JSON.parse(readFileSync(f, "utf8")), status }));
+};
+
+function git(...args: string[]): void {
+  const r = spawnSync("git", args, { cwd: root, encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+}
+
+beforeAll(async () => {
+  root = mkdtempSync(join(tmpdir(), "chant-box-services-"));
+  boxDir = join(root, "box");
+  const bin = join(root, ".bin");
+  state = join(root, ".state", "services");
+  calls = join(root, ".state", "calls");
+  mkdirSync(bin, { recursive: true });
+  mkdirSync(state, { recursive: true });
+  mkdirSync(boxDir, { recursive: true });
+  writeFileSync(join(bin, "sprite-env"), SPRITE_ENV);
+  writeFileSync(join(bin, "chant"), CHANT);
+  chmodSync(join(bin, "sprite-env"), 0o755);
+  chmodSync(join(bin, "chant"), 0o755);
+  server = createServer((req, res) => {
+    const name = (req.url ?? "/").slice(1);
+    const f = join(state, `${name}.json`);
+    const up = existsSync(f) && JSON.parse(readFileSync(f, "utf8")).status === "running";
+    res.writeHead(up ? 200 : 503).end(up ? "ok" : "down");
+  });
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  port = (server.address() as AddressInfo).port;
+  process.env.PATH = `${bin}:${process.env.PATH}`;
+  process.env.FAKE_SPRITE_STATE = state;
+  process.env.BOX_HOME = "/home/sprite/box";
+  git("init", "-q", "-b", "main");
+  git("config", "user.email", "box@example.com");
+  git("config", "user.name", "Box Test");
+  git("config", "commit.gpgsign", "false");
+  writeFileSync(join(boxDir, "chant.config.json"), "{}\n");
+  writeFileSync(join(root, ".gitignore"), ".bin\n.state\n");
+  declare(SERVICES());
+  git("add", "-A");
+  git("commit", "-q", "-m", "c0");
+  process.chdir(boxDir);
+});
+
+afterAll(async () => {
+  process.chdir(saved.cwd);
+  for (const [k, v] of [["PATH", saved.PATH], ["FAKE_SPRITE_STATE", saved.STATE], ["CHANT_CONVERGE_RESOURCE", saved.RESOURCE], ["BOX_HOME", saved.BOX_HOME]] as const) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  await new Promise<void>((r) => server.close(() => r()));
+  rmSync(root, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  declare(SERVICES());
+  rmSync(calls, { force: true });
+});
+
+describe("the sprite-env listing and create line (#2880)", () => {
+  test("parses a sprite's JSON and the kit stand-in's table, with each definition", () => {
+    expect(parseServiceDefinitions(JSON.stringify([{ name: "door", cmd: "/x/run-door.sh", args: [], needs: ["hud"], http_port: 8080, state: { status: "running" } }]))).toEqual([
+      { name: "door", status: "running", cmd: "/x/run-door.sh", needs: ["hud"], httpPort: 8080 },
+    ]);
+    expect(parseServiceDefinitions(JSON.stringify([{ name: "a", cmd: "node", args: ["a.js"], needs: null, state: { status: "stopped" } }]))).toEqual([
+      { name: "a", status: "stopped", cmd: "node a.js", needs: [] },
+    ]);
+    expect(parseServiceDefinitions("app\trunning\t-\t-\t/x/run-app.sh\ndoor\tstarting\thud\t8080\t/x/run-door.sh\nold\tstopped\n")).toEqual([
+      { name: "app", status: "running", needs: [], httpPort: null, cmd: "/x/run-app.sh" },
+      { name: "door", status: "starting", needs: ["hud"], httpPort: 8080, cmd: "/x/run-door.sh" },
+      { name: "old", status: "stopped" },
+    ]);
+  });
+
+  test("a difference in cmd, needs or httpPort is named, a field the listing lacks is not compared", () => {
+    const declared = { name: "door", cmd: "${H}/d.sh", needs: ["hud"], httpPort: 8080, duration: null, health: null, optional: false };
+    expect(listedServiceDiffers({ name: "door", status: "running", cmd: "/h/d.sh", needs: ["hud"], httpPort: 8080 }, declared, "/h/d.sh")).toBeNull();
+    expect(listedServiceDiffers({ name: "door", status: "running", cmd: "/h/old.sh", needs: ["hud"], httpPort: 8080 }, declared, "/h/d.sh")).toMatch(/^cmd/);
+    expect(listedServiceDiffers({ name: "door", status: "running", cmd: "/h/d.sh", needs: [], httpPort: 8080 }, declared, "/h/d.sh")).toMatch(/^needs/);
+    expect(listedServiceDiffers({ name: "door", status: "running", cmd: "/h/d.sh", needs: ["hud"], httpPort: null }, declared, "/h/d.sh")).toMatch(/^httpPort/);
+    expect(listedServiceDiffers({ name: "door", status: "running" }, declared, "/h/d.sh")).toBeNull();
+    expect(spriteEnvCreateArgs({ ...declared, duration: "2s" }, "/h/d.sh")).toEqual(["services", "create", "door", "--cmd", "/h/d.sh", "--needs", "hud", "--http-port", "8080", "--duration", "2s", "--no-stream"]);
+  });
+
+  test("${VAR} expands from the environment, and an unset one fails naming it", () => {
+    expect(expandServiceCommand("app", "${HOME}/box/run.sh --port ${PORT}", { HOME: "/home/sprite", PORT: "5173" })).toBe("/home/sprite/box/run.sh --port 5173");
+    expect(() => expandServiceCommand("app", "${NOPE}/run.sh", {})).toThrow("service app's cmd names ${NOPE}, which is not set in this process's environment");
+  });
+});
+
+describe("spriteApplyServices({ box: true }) through sprite-env (#2880)", () => {
+  test("creates the declared services in dependency order, a second run changes nothing, and a changed cmd replaces that one service", async () => {
+    // Declared hud first, so the order is the needs', not the file's.
+    declare([SERVICES()[1], SERVICES()[0], SERVICES()[2]]);
+    const first = await spriteApplyServices({ box: true, start: true });
+    expect(first.services).toEqual([{ name: "app", action: "created" }, { name: "hud", action: "created" }]);
+    expect(first).toMatchObject({ applied: ["app", "hud"], started: [] });
+    expect(takeCalls()).toEqual([
+      "services create app --cmd /home/sprite/box/run-app.sh --duration 3s --no-stream",
+      "services create hud --cmd /home/sprite/box/run-daemon.sh --needs app --http-port 8080 --duration 3s --no-stream",
+    ]);
+
+    const second = await spriteApplyServices({ box: true, start: true });
+    expect(second.services).toEqual([{ name: "app", action: "left" }, { name: "hud", action: "left" }]);
+    expect(second.applied).toEqual([]);
+    expect(takeCalls()).toEqual([]);
+
+    declare([SERVICES()[0], { ...SERVICES()[1], cmd: "${BOX_HOME}/run-hud.sh" }, SERVICES()[2]]);
+    const third = await spriteApplyServices({ box: true, start: true });
+    expect(third.services).toEqual([{ name: "app", action: "left" }, { name: "hud", action: "replaced" }]);
+    expect(takeCalls()).toEqual(["services delete hud", "services create hud --cmd /home/sprite/box/run-hud.sh --needs app --http-port 8080 --duration 3s --no-stream"]);
+    expect((listed().get("hud") as { cmd: string }).cmd).toBe("/home/sprite/box/run-hud.sh");
+  });
+
+  test("start starts a defined service that is stopped; without start it is left", async () => {
+    await spriteApplyServices({ box: true });
+    setStatus("app", "stopped");
+    takeCalls();
+    expect((await spriteApplyServices({ box: true })).services).toEqual([{ name: "app", action: "left" }, { name: "hud", action: "left" }]);
+    const started = await spriteApplyServices({ box: true, start: true });
+    expect(started.services).toEqual([{ name: "app", action: "started" }, { name: "hud", action: "left" }]);
+    expect(started.started).toEqual(["app"]);
+    expect(takeCalls()).toEqual(["services start app"]);
+  });
+
+  test("an optional service is applied only when only names it, and restart restarts the named ones already converged", async () => {
+    await spriteApplyServices({ box: true });
+    expect(listed().has("site")).toBe(false);
+    takeCalls();
+    expect((await spriteApplyServices({ box: true, only: ["site"], start: true, restart: true })).services).toEqual([{ name: "site", action: "created" }]);
+    expect((await spriteApplyServices({ box: true, only: ["site"], start: true, restart: true })).services).toEqual([{ name: "site", action: "restarted" }]);
+    expect(takeCalls()).toEqual(["services create site --cmd /home/sprite/box/run-site.sh --no-stream", "services restart site"]);
+    await expect(spriteApplyServices({ box: true, only: ["api"] })).rejects.toThrow("only names api, which the box block does not declare; declared: app, hud, site");
+  });
+
+  test("an unset variable fails before anything changes, and the forms it refuses", async () => {
+    rmSync(join(state, "app.json"), { force: true });
+    delete process.env.BOX_HOME;
+    try {
+      await expect(spriteApplyServices({ box: true })).rejects.toThrow("${BOX_HOME}, which is not set");
+    } finally {
+      process.env.BOX_HOME = "/home/sprite/box";
+    }
+    expect(takeCalls()).toEqual([]);
+    await expect(spriteApplyServices({})).rejects.toThrow(/pass box: true/);
+    await expect(spriteApplyServices({ id: "box-1", box: true })).rejects.toThrow(/drop the id/);
+  });
+});
+
+describe("a ConvergeOp over the box block's services (#2880)", () => {
+  test("observe with box: true records a stopped declared service drifted, and the restart Op with box: true restarts it and waits for its health", async () => {
+    for (const f of ["app", "hud", "site"]) rmSync(join(state, `${f}.json`), { force: true });
+    await spriteApplyServices({ box: true });
+    const activities = await loadActivities(["fly"]);
+    const run$ = new Map<string, ActivityFn>([...activities, ["convergeTick", convergeTick as unknown as ActivityFn]]);
+
+    // The observer reads the block: site is optional and not defined, so it is skipped.
+    expect(await spriteServicesObserve({ box: true, probes: 1 })).toEqual({
+      resources: [
+        { name: "app", status: "in-sync", detail: expect.stringContaining("answers 200") },
+        { name: "hud", status: "in-sync", detail: expect.stringContaining("answers 200") },
+      ],
+      skipped: ["site"],
+    });
+    await expect(spriteServicesObserve({ box: true, services: [{ name: "app" }] })).rejects.toThrow(/takes no services or servicesFile beside it/);
+
+    const { op } = ConvergeOp({
+      name: "box-converge",
+      env: "box",
+      dial: "apply",
+      observe: observeStep({ box: true, probes: 1 }),
+      rules: [
+        when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), { id: "restart-drifted", why: "A declared service that stopped is restarted." }),
+      ],
+    });
+    const config = (op as unknown as { props: OpConfig }).props;
+    setStatus("app", "stopped");
+    const tick = await runOpLocally(config, run$, {}, undefined, { cwd: boxDir, ledger: { cwd: boxDir } });
+    expect(tick.status).toBe("ok");
+    const ticks = (await readConvergeLedger("box", { cwd: boxDir })).records;
+    expect(ticks.at(-1)).toMatchObject({
+      firedRuleIds: ["restart-drifted"],
+      outcomes: [{ ruleId: "restart-drifted", action: "ran", op: "restart-service", resource: "app" }],
+      resources: [{ name: "app", status: "drifted", detail: "stopped" }, { name: "hud", status: "in-sync" }],
+    });
+
+    // The Op the rule dispatches: spriteServiceRestart reads app's health URL from the block.
+    setStatus("app", "stopped");
+    takeCalls();
+    const restart: OpConfig = { name: "restart-service", phases: [{ name: "Restart", steps: [restartStep({ box: true, waitMs: 2000 })] }] } as unknown as OpConfig;
+    process.env.CHANT_CONVERGE_RESOURCE = "app";
+    try {
+      const ran = await runOpLocally(restart, run$, {}, undefined, { cwd: boxDir, ledger: { cwd: boxDir } });
+      expect(ran.status).toBe("ok");
+      await expect(spriteServiceRestart({ box: true, waitMs: 2000 })).resolves.toEqual({ name: "app", healthy: true });
+    } finally {
+      delete process.env.CHANT_CONVERGE_RESOURCE;
+    }
+    expect(takeCalls()).toEqual(["services restart app", "services restart app"]);
+    expect((listed().get("app") as { state: { status: string } }).state.status).toBe("running");
+  });
+});

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

@@ -15,10 +15,21 @@
  * 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 { expandServiceCommand, inStartOrder, boxServices, type BoxServiceDeclaration } from "./box-services";
+import { findSpriteEnv } from "./sprite-service-converge";
 import { resolveSpritesEndpoint, defaultSpritesHttp, type SpritesHttp } from "./sprites";
 
+const execFileAsync = promisify(execFile);
+
 function safeJson(text: string): unknown {
   try {
     return JSON.parse(text);
@@ -116,19 +127,42 @@ export interface ServiceSpec {
 }
 
 export interface SpriteApplyServicesArgs {
-  id: string;
-  services: ServiceSpec[];
-  /** Start each service after applying (in dependency order). Default: false. */
+  /** The sprite, for the Sprites API. Without it, the step runs inside the sprite and applies the box block's services through `sprite-env` (#2880). */
+  id?: string;
+  /** The services, for the Sprites API. Required with `id`. */
+  services?: ServiceSpec[];
+  /** Without `id`: apply the services of the box block of the workspace member whose directory holds the working directory (#2880). Required without `id`. */
+  box?: boolean;
+  /** Without `id`: apply only these declared services, in dependency order. An `optional` service is applied only when named here. */
+  only?: string[];
+  /**
+   * Start services after applying, in dependency order. With `id`, every
+   * service; without, every applied one that is not running (a created or
+   * replaced one is started by its create). Default: false.
+   */
   start?: boolean;
+  /** Without `id`: restart each applied service that was already converged. Default: false. */
+  restart?: boolean;
+  /** Without `id`: the `sprite-env` binary. Default: the one on PATH, else /.sprite/bin/sprite-env. */
+  spriteEnv?: string;
   endpoint?: string;
   token?: string;
 }
 
+/** What an apply through sprite-env did to one service (#2880). */
+export type ServiceApplyAction = "created" | "replaced" | "restarted" | "started" | "left";
+
 export interface SpriteApplyServicesResult {
   /** Names that were created or updated (converged services are skipped). */
   applied: string[];
   /** Names that were started (empty unless `start`). */
   started: string[];
+  /**
+   * Without `id`: each service applied, in the order it was applied, with
+   * what the apply did to it (#2880). `left` is a converged service that was
+   * not restarted or started.
+   */
+  services?: { name: string; action: ServiceApplyAction }[];
 }
 
 /**
@@ -204,7 +238,20 @@ function serviceBody(s: ServiceSpec): Record<string, unknown> {
 export async function spriteApplyServices(
   args: SpriteApplyServicesArgs,
   signal?: AbortSignal,
-  http: SpritesHttp = defaultSpritesHttp(args.token),
+  http?: SpritesHttp,
+): Promise<SpriteApplyServicesResult> {
+  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: SpriteApplyServicesArgs & { id: string; services: ServiceSpec[] },
+  signal: AbortSignal | undefined,
+  http: SpritesHttp,
 ): Promise<SpriteApplyServicesResult> {
   const startOrder = validateServices(args.services);
   const base = resolveSpritesEndpoint(args);
@@ -244,3 +291,166 @@ export async function spriteApplyServices(
 
   return { applied, started };
 }
+
+// ── Services through sprite-env (#2880) ─────────────────────────────────────
+
+/** A service as `sprite-env services list` reports it. A field the listing does not carry is undefined. */
+export interface ListedService {
+  name: string;
+  status: string | null;
+  cmd?: string;
+  needs?: string[];
+  httpPort?: number | null;
+}
+
+/**
+ * `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: string): ListedService[] {
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    const parsed = JSON.parse(trimmed) as unknown;
+    const list = Array.isArray(parsed) ? parsed : ((parsed as { services?: unknown }).services ?? []);
+    const out: ListedService[] = [];
+    for (const s of list as Record<string, unknown>[]) {
+      if (typeof s?.name !== "string") continue;
+      const state = s.state as { status?: unknown } | undefined;
+      const status = typeof state?.status === "string" ? state.status : typeof s.status === "string" ? s.status : null;
+      const args = Array.isArray(s.args) ? (s.args as unknown[]).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 as unknown[]).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: ListedService[] = [];
+  for (const line of trimmed.split("\n")) {
+    const cols = line.split("\t");
+    const name = cols[0]?.trim();
+    if (!name) continue;
+    const listed: ListedService = { 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: ListedService, declared: BoxServiceDeclaration, cmd: string): string | null {
+  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. Pure. */
+export function spriteEnvCreateArgs(s: BoxServiceDeclaration, cmd: string): string[] {
+  return [
+    "services",
+    "create",
+    s.name,
+    "--cmd",
+    cmd,
+    ...(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: SpriteApplyServicesArgs, signal?: AbortSignal): Promise<SpriteApplyServicesResult> {
+  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, expandServiceCommand(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: string[]): Promise<string> => {
+    try {
+      return (await execFileAsync(bin, argv, { signal, timeout: 120_000, maxBuffer: 16 * 1024 * 1024 })).stdout;
+    } catch (err) {
+      const e = err as { stderr?: string; message?: string };
+      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]));
+
+  const services: { name: string; action: ServiceApplyAction }[] = [];
+  for (const s of targets) {
+    const cmd = commands.get(s.name)!;
+    const cur = live.get(s.name);
+    if (!cur) {
+      await spriteEnv(spriteEnvCreateArgs(s, cmd));
+      console.log(`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, cmd));
+      console.log(`services: replaced ${s.name} (${why})`);
+      services.push({ name: s.name, action: "replaced" });
+      continue;
+    }
+    if (args.restart) {
+      await spriteEnv(["services", "restart", s.name]);
+      console.log(`services: restarted ${s.name}`);
+      services.push({ name: s.name, action: "restarted" });
+      continue;
+    }
+    services.push({ name: s.name, action: "left" });
+  }
+
+  const started: string[] = [];
+  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]);
+      console.log(`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);
+  console.log(`services: applied ${applied.length}/${targets.length} through sprite-env, started ${started.length}`);
+  return { applied, started, services };
+}

package/src/op/activities/sprite-service-converge.ts

@@ -20,12 +20,18 @@
  * sprite and call `sprite-env services` (found on PATH or in /.sprite/bin,
  * or at `spriteEnv`). With an `id`, they go through the Sprites API
  * (`spriteServiceList`, `spriteServiceStop` and `spriteServiceStart`).
+ *
+ * The declared services come from `services`, from a `servicesFile`, or,
+ * with `box: true`, from the `services` of the box block of the workspace
+ * member whose directory holds the working directory (#2880), the list
+ * `chant workspace status --json` prints as `members[].box.services`.
  */
 
 import { execFile } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
+import { boxServices } from "./box-services";
 import { spriteServiceList, spriteServiceStart, spriteServiceStop } from "./sprite-services";
 import type { SpritesHttp } from "./sprites";
 import { defaultSpritesHttp } from "./sprites";
@@ -62,6 +68,12 @@ export interface SpriteServicesObserveArgs extends Via {
   services?: DeclaredSpriteService[];
   /** A JSON file of `{ services: [...] }`, relative to the working directory, read on each tick. */
   servicesFile?: string;
+  /**
+   * Read the services from the box block of the workspace member whose
+   * directory holds the working directory, on each tick (#2880), in place of
+   * `services` and `servicesFile`.
+   */
+  box?: boolean;
   /** Health probes before a service counts as drifted. Default 3. */
   probes?: number;
   /** Time between probes, ms. Default 1000. */
@@ -77,10 +89,12 @@ export interface SpriteServicesObserveResult {
 export interface SpriteServiceRestartArgs extends Via {
   /** The service. Default: the resource a ConvergeOp dispatched this run for (`CHANT_CONVERGE_RESOURCE`). */
   name?: string;
-  /** Its health URL. Default: the one `services` or `servicesFile` declares for it. */
+  /** Its health URL. Default: the one `services`, `servicesFile` or the box block (`box: true`) declares for it. */
   health?: string;
   services?: DeclaredSpriteService[];
   servicesFile?: string;
+  /** Read the declared services from the box block of the member the step runs in (#2880), in place of `services` and `servicesFile`. */
+  box?: boolean;
   /** How long to wait for the health URL after the restart, ms. Default 60000. */
   waitMs?: number;
 }
@@ -107,6 +121,20 @@ export function declaredServices(args: { services?: DeclaredSpriteService[]; ser
   return out;
 }
 
+/**
+ * The declared services: with `box: true`, the box block's (#2880), and
+ * otherwise those of {@link declaredServices}. `box` in place of the other
+ * two, never beside them.
+ */
+export async function resolveDeclaredServices(
+  args: { services?: DeclaredSpriteService[]; servicesFile?: string; box?: boolean },
+  cwd = process.cwd(),
+): Promise<DeclaredSpriteService[]> {
+  if (!args.box) return declaredServices(args, cwd);
+  if (args.services || args.servicesFile) throw new Error("box: true reads the services from the box block, so it takes no services or servicesFile beside it");
+  return (await boxServices(cwd)).map((s) => ({ name: s.name, ...(s.health ? { health: s.health } : {}), ...(s.optional ? { optional: true } : {}) }));
+}
+
 /** The sprite-env binary, or null when there is none. */
 export function findSpriteEnv(explicit?: string, env: NodeJS.ProcessEnv = process.env): string | null {
   if (explicit) return explicit;
@@ -181,7 +209,7 @@ export async function spriteServicesObserve(
   signal?: AbortSignal,
   http?: SpritesHttp,
 ): Promise<SpriteServicesObserveResult> {
-  const declared = declaredServices(args);
+  const declared = await resolveDeclaredServices(args);
   const probes = Math.max(1, args.probes ?? 3);
   const interval = args.probeIntervalMs ?? 1000;
   let states: Map<string, string | null>;
@@ -245,7 +273,7 @@ export async function spriteServiceRestart(
   if (!name) {
     throw new Error(`spriteServiceRestart: no service named: pass \`name\`, or run the Op from a ConvergeOp rule, which sets ${CONVERGE_RESOURCE_ENV}`);
   }
-  const health = args.health ?? (args.services || args.servicesFile ? declaredServices(args).find((s) => s.name === name)?.health : undefined);
+  const health = args.health ?? (args.services || args.servicesFile || args.box ? (await resolveDeclaredServices(args)).find((s) => s.name === name)?.health : undefined);
 
   if (args.id) {
     const client = http ?? defaultSpritesHttp(args.token);