@intentius/chant-lexicon-fly 0.93.0 → 0.95.0

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

@@ -1,7 +1,7 @@
 /**
  * Sprite Services activities (#2711) — imperative create/get/list/start/stop/
- * delete/logs over a Sprite's background services, the surface a box's door,
- * hud and chud run as long-lived services through (`sprite-env services`
+ * delete/logs over a Sprite's background services, the surface a box's door
+ * and hud run as long-lived services through (`sprite-env services`
  * inside the sprite, `/v1/sprites/{id}/services/...` outside). Shared by the
  * Sprites API, wisp (arugula-salad/wisp) and spritzer 0.6.0's container mode
  * (INTENTIUS/spritzer#22).

package/src/op/activities/sprites.ts

@@ -630,7 +630,7 @@ export interface SpriteUrlResult {
  * nothing until now exposed it on its own (for a later phase that only has
  * the sprite `id`) or waited on it. `GET /v1/sprites/{id}` for the URL; with
  * `path` set, polls `GET {url}{path}` until `status` (default any 2xx) or
- * `timeoutMs` runs out — the box's door/hud/chud services take a moment to
+ * `timeoutMs` runs out — the box's door/hud services take a moment to
  * bind their `http_port` after `spriteServiceStart`.
  */
 export async function spriteUrl(

package/src/op/activity-contracts.test.ts

@@ -13,7 +13,7 @@ import {
 } from "@intentius/chant/op";
 import * as contracts from "./activity-contracts";
 import * as activities from "./activities";
-import { spriteServicesObserve, spriteServiceRestart } from "./builders";
+import { spriteApplyServices, spriteServicesObserve, spriteServiceRestart } from "./builders";
 
 const CONTRACTS: Map<string, ActivityContract> = new Map(
   Object.values(contracts).filter(isActivityContract).map((c) => [c.name, c]),
@@ -29,7 +29,7 @@ describe("fly activity contracts (#2843)", () => {
       expect(typeof (activities as unknown as Record<string, unknown>)[c.name], `${c.name} is not an exported activity`).toBe("function");
       expect(c.returns, `${c.name} declares no return schema`).toBeDefined();
     }
-    expect([...CONTRACTS.keys()].sort()).toEqual(["spriteServiceRestart", "spriteServicesObserve"]);
+    expect([...CONTRACTS.keys()].sort()).toEqual(["spriteApplyServices", "spriteServiceRestart", "spriteServicesObserve"]);
   });
 
   test("a ConvergeOp observing spriteServicesObserve passes OPS012 and OPS013 (the guide's example)", () => {
@@ -63,9 +63,26 @@ describe("fly activity contracts (#2843)", () => {
     expect(issues.some((i) => i.message.includes("servicefile"))).toBe(true);
   });
 
+  test("the box forms validate: observe and restart with box: true, and an apply with box, only, start and restart (#2880)", () => {
+    const { op: converge } = ConvergeOp({
+      name: "converge",
+      env: "box",
+      observe: spriteServicesObserve({ box: true }),
+      rules: [when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), { id: "restart-drifted", why: "restart it" })],
+    });
+    expect(validateActivitySteps(converge.props as never, CONTRACTS)).toEqual([]);
+    expect(validateStepOutputRefs(converge.props as never, CONTRACTS)).toEqual([]);
+    expect(validateActivitySteps(op([spriteServiceRestart({ box: true })]), CONTRACTS)).toEqual([]);
+    expect(validateActivitySteps(op([spriteApplyServices({ box: true, only: ["site"], start: true, restart: true })]), CONTRACTS)).toEqual([]);
+    expect(validateActivitySteps(op([spriteApplyServices({ id: "box-1", services: [{ name: "app", cmd: "node app.js", needs: [] }], start: true })]), CONTRACTS)).toEqual([]);
+    const issues = validateActivitySteps(op([{ kind: "activity", fn: "spriteApplyServices", args: { box: true, onlyy: ["site"] } }]), CONTRACTS);
+    expect(issues.some((i) => i.message.includes("onlyy"))).toBe(true);
+  });
+
   test("loadActivityContracts finds them at @intentius/chant-lexicon-fly/op/activity-contracts", async () => {
     const loaded = await loadActivityContracts(["fly"]);
     expect(loaded.get("spriteServicesObserve")?.returns).toBeDefined();
     expect(loaded.get("spriteServiceRestart")?.returns).toBeDefined();
+    expect(loaded.get("spriteApplyServices")?.returns).toBeDefined();
   });
 });

package/src/op/activity-contracts.ts

@@ -12,12 +12,14 @@
  * needs its return schema; without one, every project declaring such a
  * ConvergeOp failed `chant build` and `chant lint`. `spriteServiceRestart` is
  * the step of the Op such a ConvergeOp's rule runs, and its result is what a
- * later step would read. The other Sprites activities have no contract yet,
+ * later step would read. `spriteApplyServices` is covered for its box form
+ * (#2880): `box`, `only`, `start` and `restart`, and the per-service actions
+ * its result names. The other Sprites activities have no contract yet,
  * which OPS012 skips rather than flags.
  *
  * Each `args` schema mirrors the `*Args` interface in
- * `./activities/sprite-service-converge.ts` and each `returns` schema the
- * `*Result`. Authored with `z.strictObject(...)`, so a misspelled key fails
+ * `./activities/sprite-service-converge.ts` or `./activities/sprite-config.ts`
+ * and each `returns` schema the `*Result`. Authored with `z.strictObject(...)`, so a misspelled key fails
  * the build instead of vanishing.
  */
 
@@ -44,6 +46,7 @@ export const spriteServicesObserveContract = activityContract(
     ...via,
     services: z.array(declaredService).optional(),
     servicesFile: z.string().optional(),
+    box: z.boolean().optional(),
     probes: z.number().optional(),
     probeIntervalMs: z.number().optional(),
   }),
@@ -61,7 +64,38 @@ export const spriteServiceRestartContract = activityContract(
     health: z.string().optional(),
     services: z.array(declaredService).optional(),
     servicesFile: z.string().optional(),
+    box: z.boolean().optional(),
     waitMs: z.number().optional(),
   }),
   z.object({ name: z.string(), healthy: z.boolean().nullable() }),
 );
+
+const serviceSpec = z.strictObject({
+  name: z.string(),
+  cmd: z.string(),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  dir: z.string().optional(),
+  needs: z.array(z.string()).optional(),
+  http_port: z.number().optional(),
+});
+
+export const spriteApplyServicesContract = activityContract(
+  "spriteApplyServices",
+  z.strictObject({
+    id: z.string().optional(),
+    services: z.array(serviceSpec).optional(),
+    box: z.boolean().optional(),
+    only: z.array(z.string()).optional(),
+    start: z.boolean().optional(),
+    restart: z.boolean().optional(),
+    spriteEnv: z.string().optional(),
+    endpoint: z.string().optional(),
+    token: z.string().optional(),
+  }),
+  z.object({
+    applied: z.array(z.string()),
+    started: z.array(z.string()),
+    services: z.array(z.object({ name: z.string(), action: z.enum(["created", "replaced", "restarted", "started", "left"]) })).optional(),
+  }),
+);

package/src/op/builders.ts

@@ -108,7 +108,13 @@ export const spriteListDir = spriteStep<SpriteListDirArgs>("spriteListDir", "fas
 export const spriteRemove = spriteStep<SpriteRemoveArgs>("spriteRemove", "fastIdempotent");
 /** Reconcile a sprite's outbound network policy — the fully typed twin of core's `spriteApplyNetworkPolicy`. Defaults to the `fastIdempotent` profile. */
 export const spriteApplyNetworkPolicy = spriteStep<SpriteApplyNetworkPolicyArgs>("spriteApplyNetworkPolicy", "fastIdempotent");
-/** Reconcile a sprite's background services — the fully typed twin of core's `spriteApplyServices`. Defaults to the `fastIdempotent` profile. */
+/**
+ * Reconcile a sprite's background services — the fully typed twin of core's
+ * `spriteApplyServices`. With an `id`, through the Sprites API; without one,
+ * inside the sprite through sprite-env, applying the box block's services
+ * (`box: true`, with `only`, `start` and `restart`, #2880). Defaults to the
+ * `fastIdempotent` profile.
+ */
 export const spriteApplyServices = spriteStep<SpriteApplyServicesArgs>("spriteApplyServices", "fastIdempotent");
 /** Create-and-start one background service (#2711) — the single-service primitive underneath `spriteApplyServices`. Defaults to the `longInfra` profile (the create+start NDJSON round trip). */
 export const spriteServiceCreate = spriteStep<SpriteServiceCreateArgs>("spriteServiceCreate", "longInfra");

package/src/skills/chant-fly-sprites.md

@@ -104,13 +104,13 @@ The same lexicon ships more Sprite primitives, all imported from `@intentius/cha
 | Family | Activities | Use |
 |--------|-----------|-----|
 | Filesystem (#848) | `spriteWriteFile` / `spriteReadFile` / `spriteListDir` / `spriteRemove` | stage an input file and read a result out without shelling `spriteExec` + `cat` |
-| Config reconcile (#849) | `spriteApplyNetworkPolicy` / `spriteApplyServices` | reconcile a Sprite's egress allowlist and background services against typed config (validated before any HTTP; a whole-object replace for policy, create-or-update by name for services) |
-| Services (#2711) | `spriteServiceCreate` / `spriteServiceGet` / `spriteServiceList` / `spriteServiceStart` / `spriteServiceStop` / `spriteServiceDelete` / `spriteServiceLogs` | the single-service primitives underneath `spriteApplyServices` — create-and-start one long-lived service (a box's door, hud or chud), inspect or list what's running, stop/start or delete one by name, read its log tail |
-| Converge (#2778) | `spriteServicesObserve` / `spriteServiceRestart` | keep a box's declared services running with a `ConvergeOp`: the observer step gives one verdict per service (`in-sync`, `drifted`, `unknown`) from the supervisor and each health URL, and the restart is the step of the Op a rule dispatches for the drifted service. Inside the sprite they call `sprite-env services`; with a sprite `id` they use the API |
+| Config reconcile (#849) | `spriteApplyNetworkPolicy` / `spriteApplyServices` | reconcile a Sprite's egress allowlist and background services against typed config (validated before any HTTP; a whole-object replace for policy, create-or-update by name for services). Without an `id`, `spriteApplyServices({ box: true })` runs inside the sprite and applies the box block's `services` through `sprite-env services` (#2880): it creates the missing ones and deletes and creates the changed ones, in dependency order, with `only`, `start` and `restart` |
+| Services (#2711) | `spriteServiceCreate` / `spriteServiceGet` / `spriteServiceList` / `spriteServiceStart` / `spriteServiceStop` / `spriteServiceDelete` / `spriteServiceLogs` | the single-service primitives underneath `spriteApplyServices` — create-and-start one long-lived service (a box's door or hud), inspect or list what's running, stop/start or delete one by name, read its log tail |
+| Converge (#2778) | `spriteServicesObserve` / `spriteServiceRestart` | keep a box's declared services running with a `ConvergeOp`: the observer step gives one verdict per service (`in-sync`, `drifted`, `unknown`) from the supervisor and each health URL, and the restart is the step of the Op a rule dispatches for the drifted service. Inside the sprite they call `sprite-env services`; with a sprite `id` they use the API. The services come from `services`, a `servicesFile`, or with `box: true` the box block's `services` in `chant.workspace.json` (#2880) |
 | Sprite URL / delete (#2711) | `spriteUrl` / `spriteDelete` | resolve a Sprite's URL, optionally waiting until a path on it answers; delete the Sprite (`spriteDelete` is `spriteDestroy` under the name spritzer/wisp and the other lexicons' delete activities use — same call, either name) |
 | Keep-alive (#847) | `spriteTaskCreate` / `spriteTaskRefresh` / `spriteTaskRelease` | hold a Sprite active for a session so it will not pause; a session past the 1-hour task cap refreshes on an interval |
 
-These are still runtime-orchestration primitives, not declarable resources — a Sprite has no desired-state create body to reconcile. Services created directly with `spriteServiceCreate` are what a box's `spritzer` preset provisions door/hud/chud on (arugula-salad/studio#27) — the same wire surface as `sprite-env services` inside the sprite, spritzer 0.6.0's container mode, and wisp.
+These are still runtime-orchestration primitives, not declarable resources — a Sprite has no desired-state create body to reconcile. Services created directly with `spriteServiceCreate` are what a box's `spritzer` preset provisions door/hud on (arugula-salad/studio#27) — the same wire surface as `sprite-env services` inside the sprite, spritzer 0.6.0's container mode, and wisp.
 
 ## Where it fits