@intentius/chant-lexicon-fly 0.91.0 → 0.93.0

package/src/op/activities/sprites.test.ts

@@ -214,6 +214,26 @@ describe("spriteExecWsUrl", () => {
   test("https → wss", () => {
     expect(spriteExecWsUrl("https://api.sprites.dev", "s", "ls").startsWith("wss://api.sprites.dev/")).toBe(true);
   });
+
+  test("dir → a single dir param (#2765)", () => {
+    const url = new URL(spriteExecWsUrl("http://x", "task-1", "pwd", { dir: "/work" }));
+    expect(url.searchParams.get("dir")).toBe("/work");
+  });
+
+  test("no dir → no dir param (#2765)", () => {
+    const url = new URL(spriteExecWsUrl("http://x", "task-1", "pwd"));
+    expect(url.searchParams.has("dir")).toBe(false);
+  });
+
+  test("env → repeated KEY=VALUE params, matching wisp's optsFromValues (#2765)", () => {
+    const url = new URL(spriteExecWsUrl("http://x", "task-1", "env", { env: { FOO: "1", BAR: "two" } }));
+    expect(url.searchParams.getAll("env")).toEqual(["FOO=1", "BAR=two"]);
+  });
+
+  test("no env → no env params (#2765)", () => {
+    const url = new URL(spriteExecWsUrl("http://x", "task-1", "echo hi"));
+    expect(url.searchParams.has("env")).toBe(false);
+  });
 });
 
 // ── Activity request shapes (injected SpritesHttp; no real sockets) ───────────

package/src/op/activities/sprites.ts

@@ -179,10 +179,19 @@ export function splitCommand(cmd: string): string[] {
 }
 
 /**
- * Build the `wss://.../exec?cmd=...&path=...&stdin=false&cc=true` URL for a
- * command (http→ws, https→wss). Pure.
+ * Build the `wss://.../exec?cmd=...&path=...&stdin=false&cc=true[&dir=...][&env=K=V]*`
+ * URL for a command (http→ws, https→wss). `dir` and `env` (#2765) are sent the
+ * way wisp's and spritzer's real exec API take them: `dir` is a single query
+ * param, and each `env` entry is its own repeated `env=KEY=VALUE` param — see
+ * wisp's `optsFromValues` (`Dir: q.Get("dir")`, `Env: q["env"]`) and spritzer's
+ * container-mode wrapping (`--dir`/`--env` per `real.go`). Pure.
  */
-export function spriteExecWsUrl(base: string, id: string, cmd: string): string {
+export function spriteExecWsUrl(
+  base: string,
+  id: string,
+  cmd: string,
+  opts: { env?: Record<string, string>; dir?: string } = {},
+): string {
   const wsBase = base.replace(/^http(s?):\/\//i, (_m, s: string) => `ws${s}://`);
   const argv = splitCommand(cmd);
   const params = new URLSearchParams();
@@ -190,6 +199,10 @@ export function spriteExecWsUrl(base: string, id: string, cmd: string): string {
   params.set("path", argv[0] ?? "");
   params.set("stdin", "false");
   params.set("cc", "true");
+  if (opts.dir) params.set("dir", opts.dir);
+  if (opts.env) {
+    for (const [k, v] of Object.entries(opts.env)) params.append("env", `${k}=${v}`);
+  }
   return `${wsBase}/v1/sprites/${encodeURIComponent(id)}/exec?${params.toString()}`;
 }
 
@@ -281,8 +294,16 @@ export interface SpriteExecArgs {
   id: string;
   /** Command to run inside the sprite (tokenized into argv, quotes respected). */
   cmd: string;
-  /** Per-exec timeout in ms. */
+  /**
+   * Per-exec timeout in ms (#2765). When it elapses before the command exits,
+   * the exec WebSocket is aborted and the activity throws a timeout error —
+   * previously declared and never enforced.
+   */
   timeoutMs?: number;
+  /** Extra environment variables for the command, on top of the sprite's own (#2765). */
+  env?: Record<string, string>;
+  /** Working directory to run the command in (#2765). */
+  dir?: string;
   endpoint?: string;
   token?: string;
 }
@@ -405,15 +426,20 @@ export async function spriteCreate(
 
 /**
  * Run a command in the sprite over the control WebSocket (non-PTY stream
- * framing, per superfly/sprites-go). Connects to `wss://.../exec`, sends a
- * single `[4]` (stdin EOF), accumulates stdout/stderr frames, and reads the
- * exit code from the `[3]` frame. A non-zero exit is a failed activity (it
- * throws) so a risky step fails its phase and triggers `onFailure`
- * compensation (S5).
+ * framing, per superfly/sprites-go). Connects to `wss://.../exec` (`dir`/`env`
+ * riding on the URL — #2765), sends a single `[4]` (stdin EOF), accumulates
+ * stdout/stderr frames, and reads the exit code from the `[3]` frame. A
+ * non-zero exit is a failed activity (it throws) so a risky step fails its
+ * phase and triggers `onFailure` compensation (S5).
+ *
+ * `timeoutMs` (#2765) bounds the whole exec: a timer set at connect time
+ * terminates the WebSocket and rejects with a timeout error once it elapses
+ * without the command finishing. Previously declared on `SpriteExecArgs` and
+ * never read.
  */
 export async function spriteExec(args: SpriteExecArgs, signal?: AbortSignal): Promise<SpriteExecResult> {
   const base = resolveSpritesEndpoint(args);
-  const url = spriteExecWsUrl(base, args.id, args.cmd);
+  const url = spriteExecWsUrl(base, args.id, args.cmd, { env: args.env, dir: args.dir });
   const token = resolveSpritesToken(args.token);
   const headers: Record<string, string> = {};
   if (token) headers.Authorization = `Bearer ${token}`;
@@ -423,10 +449,12 @@ export async function spriteExec(args: SpriteExecArgs, signal?: AbortSignal): Pr
     const frames: Uint8Array[] = [];
     const ws = new WebSocket(url, { headers });
     let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
     const finish = (fn: () => void): void => {
       if (settled) return;
       settled = true;
       if (signal) signal.removeEventListener("abort", onAbort);
+      if (timer !== undefined) clearTimeout(timer);
       fn();
     };
     const onAbort = (): void => {
@@ -441,6 +469,18 @@ export async function spriteExec(args: SpriteExecArgs, signal?: AbortSignal): Pr
       if (signal.aborted) return onAbort();
       signal.addEventListener("abort", onAbort);
     }
+    if (args.timeoutMs !== undefined) {
+      timer = setTimeout(() => {
+        try {
+          ws.terminate();
+        } catch {
+          /* already closed */
+        }
+        finish(() =>
+          reject(new Error(`sprite ${args.id} exec "${args.cmd}" timed out after ${args.timeoutMs}ms`)),
+        );
+      }, args.timeoutMs);
+    }
     ws.on("open", () => {
       // No stdin: signal EOF immediately (belt and braces with stdin=false).
       ws.send(Uint8Array.of(STREAM_STDIN_EOF));

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

@@ -0,0 +1,71 @@
+import { describe, test, expect } from "vitest";
+import {
+  ConvergeOp,
+  eq,
+  isActivityContract,
+  loadActivityContracts,
+  run,
+  validateActivitySteps,
+  validateStepOutputRefs,
+  when,
+  type ActivityContract,
+  type ResourceSymptom,
+} from "@intentius/chant/op";
+import * as contracts from "./activity-contracts";
+import * as activities from "./activities";
+import { spriteServicesObserve, spriteServiceRestart } from "./builders";
+
+const CONTRACTS: Map<string, ActivityContract> = new Map(
+  Object.values(contracts).filter(isActivityContract).map((c) => [c.name, c]),
+);
+
+const op = (steps: unknown[]) => ({ name: "restart-service", phases: [{ name: "Phase", steps: steps as never[] }] });
+
+describe("fly activity contracts (#2843)", () => {
+  test("the module exports nothing but contracts, each for an exported activity, each with a return schema", () => {
+    for (const [key, value] of Object.entries(contracts)) {
+      expect(isActivityContract(value), `${key} is not an ActivityContract`).toBe(true);
+      const c = value as ActivityContract;
+      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"]);
+  });
+
+  test("a ConvergeOp observing spriteServicesObserve passes OPS012 and OPS013 (the guide's example)", () => {
+    const { op: converge } = ConvergeOp({
+      name: "converge",
+      env: "box",
+      dial: "apply",
+      schedule: "* * * * *",
+      observe: spriteServicesObserve({ servicesFile: "services.json" }),
+      rules: [when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), { id: "restart-drifted", why: "restart it" })],
+    });
+    const config = converge.props as never;
+    expect(validateActivitySteps(config, CONTRACTS)).toEqual([]);
+    expect(validateStepOutputRefs(config, CONTRACTS)).toEqual([]);
+  });
+
+  test("without the contracts, the same Op fails OPS013 (the bug)", () => {
+    const { op: converge } = ConvergeOp({
+      name: "converge",
+      env: "box",
+      observe: spriteServicesObserve({ servicesFile: "services.json" }),
+      rules: [when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), { id: "restart-drifted", why: "restart it" })],
+    });
+    const issues = validateStepOutputRefs(converge.props as never, new Map());
+    expect(issues.some((i) => i.message.includes("spriteServicesObserve"))).toBe(true);
+  });
+
+  test("the restart step's args validate, and a misspelled key is an error", () => {
+    expect(validateActivitySteps(op([spriteServiceRestart({ servicesFile: "services.json", waitMs: 30_000 })]), CONTRACTS)).toEqual([]);
+    const issues = validateActivitySteps(op([{ kind: "activity", fn: "spriteServiceRestart", args: { servicefile: "services.json" } }]), CONTRACTS);
+    expect(issues.some((i) => i.message.includes("servicefile"))).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();
+  });
+});

package/src/op/activity-contracts.ts

@@ -0,0 +1,67 @@
+/**
+ * Activity contracts for this lexicon's `op/activities` (chant #2101, #2843).
+ *
+ * Resolved by convention at `@intentius/chant-lexicon-fly/op/activity-contracts`:
+ * `loadActivityContracts` (`packages/core/src/op/activity-contract-registry.ts`)
+ * merges what it finds here into the map core's OPS012 and OPS013 validate
+ * every Op step against.
+ *
+ * Only the activities a step's output is referenced from are covered.
+ * `spriteServicesObserve` is the observer of a `ConvergeOp({ observe })`
+ * (#2778), whose Converge step reads the observer's whole output, so OPS013
+ * 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,
+ * 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
+ * the build instead of vanishing.
+ */
+
+import { z } from "zod";
+import { activityContract } from "@intentius/chant/op";
+
+const declaredService = z.strictObject({
+  name: z.string(),
+  health: z.string().optional(),
+  optional: z.boolean().optional(),
+});
+
+/** `Via`: the sprite for the Sprites API, or `sprite-env` inside the sprite. */
+const via = {
+  id: z.string().optional(),
+  spriteEnv: z.string().optional(),
+  endpoint: z.string().optional(),
+  token: z.string().optional(),
+};
+
+export const spriteServicesObserveContract = activityContract(
+  "spriteServicesObserve",
+  z.strictObject({
+    ...via,
+    services: z.array(declaredService).optional(),
+    servicesFile: z.string().optional(),
+    probes: z.number().optional(),
+    probeIntervalMs: z.number().optional(),
+  }),
+  z.object({
+    resources: z.array(z.object({ name: z.string(), status: z.enum(["in-sync", "drifted", "unknown"]), detail: z.string() })),
+    skipped: z.array(z.string()),
+  }),
+);
+
+export const spriteServiceRestartContract = activityContract(
+  "spriteServiceRestart",
+  z.strictObject({
+    ...via,
+    name: z.string().optional(),
+    health: z.string().optional(),
+    services: z.array(declaredService).optional(),
+    servicesFile: z.string().optional(),
+    waitMs: z.number().optional(),
+  }),
+  z.object({ name: z.string(), healthy: z.boolean().nullable() }),
+);

package/src/op/builders.ts

@@ -40,6 +40,7 @@ import type {
   SpriteServiceDeleteArgs,
   SpriteServiceLogsArgs,
 } from "./activities/sprite-services";
+import type { SpriteServicesObserveArgs, SpriteServiceRestartArgs } from "./activities/sprite-service-converge";
 import type { SpriteTaskCreateArgs, SpriteTaskRefreshArgs, SpriteTaskReleaseArgs } from "./activities/sprite-tasks";
 import type { SpritesUpArgs, SpritesDownArgs } from "./activities/sprites-emulator";
 import type {
@@ -49,6 +50,8 @@ import type {
   FlyMachineVerifyArgs,
   FlyMachineRestoreArgs,
 } from "./activities/machine-release";
+import type { FlyReleaseArgs } from "./activities/fly-release-step";
+import type { FlyRollbackArgs } from "./activities/fly-rollback-step";
 
 type StepOpts = { profile?: ActivityStep["profile"] };
 
@@ -121,6 +124,19 @@ export const spriteServiceStop = spriteStep<SpriteServiceStopArgs>("spriteServic
 export const spriteServiceDelete = spriteStep<SpriteServiceDeleteArgs>("spriteServiceDelete", "fastIdempotent");
 /** Read a background service's log tail (#2711). Defaults to the `fastIdempotent` profile. */
 export const spriteServiceLogs = spriteStep<SpriteServiceLogsArgs>("spriteServiceLogs", "fastIdempotent");
+/**
+ * Observe a box's declared services for a ConvergeOp (#2778): one verdict per
+ * service, `in-sync`, `drifted` or `unknown`, from the supervisor's list and
+ * each service's health URL. Pass it as `ConvergeOp({ observe })`. Defaults
+ * to the `fastIdempotent` profile.
+ */
+export const spriteServicesObserve = spriteStep<SpriteServicesObserveArgs>("spriteServicesObserve", "fastIdempotent");
+/**
+ * Restart one service through its supervisor and wait for its health URL
+ * (#2778). Without `name`, the service is the one a ConvergeOp rule
+ * dispatched the run for. Defaults to the `longInfra` profile.
+ */
+export const spriteServiceRestart = spriteStep<SpriteServiceRestartArgs>("spriteServiceRestart", "longInfra");
 /** Create a keep-alive task — the fully typed twin of core's `spriteTaskCreate`. Defaults to the `fastIdempotent` profile. */
 export const spriteTaskCreate = spriteStep<SpriteTaskCreateArgs>("spriteTaskCreate", "fastIdempotent");
 /** Refresh a keep-alive task's expiry — the fully typed twin of core's `spriteTaskRefresh`. Defaults to the `fastIdempotent` profile. */
@@ -152,3 +168,19 @@ export const flyMachineStop = spriteStep<FlyMachineStateArgs>("flyMachineStop",
 export const flyMachineVerify = spriteStep<FlyMachineVerifyArgs>("flyMachineVerify", "longInfra");
 /** Put a recorded Machine config back (restore, rollback). Defaults to the `longInfra` profile. */
 export const flyMachineRestore = spriteStep<FlyMachineRestoreArgs>("flyMachineRestore", "longInfra");
+/**
+ * Ship a release to a Fly Machine from an Op (#2782): the `fly-release`
+ * capability's steps (upload and start, each migration once per environment,
+ * verify, restore on failure), for the environment `environment` names. With `source`
+ * it puts an approved source tree on the Machine. Defaults to the `longInfra`
+ * profile.
+ */
+export const flyRelease = spriteStep<FlyReleaseArgs>("flyRelease", "longInfra");
+/**
+ * Put an earlier release back on a Fly Machine from an Op (#2800): the
+ * `fly-rollback` capability's restore of the Machine config recorded for `to`
+ * in `environment`, then its verify. With `source` the archive is checked
+ * against its digest, and the recorded config against the archive's tree,
+ * before the Machine changes. Defaults to the `longInfra` profile.
+ */
+export const flyRollback = spriteStep<FlyRollbackArgs>("flyRollback", "longInfra");

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

@@ -86,3 +86,70 @@ The step's output carries `uri` and `digest`, so `chant run --components web --e
 Each release's Machine config is kept on `chant/lifecycle` at `<env>/fly/<app>/<machine>/<digest>.json`. `fly-rollback` puts back the config of the release the serving one replaced (or the digest given as `to`), checks it, and outputs that digest so the ledger records it again. `fly-release`'s own saga compensation does the same.
 
 The steps are also Op activities, for an Op that composes them itself: `flyMachineRelease`, `flyMachineExec`, `flyMachineRestart`, `flyMachineStop`, `flyMachineVerify` and `flyMachineRestore`. Wrap a migration's `flyMachineExec` in `effect()` so it fires once.
+
+### A source tree instead of an image
+
+An app with no image of its own ships as its files on the declared runtime image. Give `fly-release` a `source` in place of `image`: an archive made by core's `sourceArchive` step (`git archive` of one directory of a commit, the same bytes for the same commit), the sha256 it must have, the directory it holds, where the files go (default `/srv/app`) and the command that starts the app there. The archive is read only once its bytes hash to that digest, before the Machine changes, so the Machine never gets a tree nobody approved. The files go into the Machine's config, up to 1 MiB base64. A larger app needs an image.
+
+An Op runs the same steps with the `flyRelease` activity, which takes the environment it ships to as `environment` (`env` stays the Machine's env vars). A release Op gates on the plan core's `releasePlan` writes and records the release with `releaseRecord`:
+
+```ts
+import { Op, phase, gate, build, sourceArchive, releasePlan, releaseRecord } from "@intentius/chant/op";
+import { flyRelease } from "@intentius/chant-lexicon-fly";
+
+const archive = sourceArchive("../app", { id: "archive" });
+const plan = releasePlan({ id: "plan", component: "app", env: "fly", gitSha: archive.out.commit, content: { artifact: { digest: archive.out.digest } } });
+
+export default Op({
+  name: "release",
+  overview: "Ship the app member to Fly once its plan is approved",
+  phases: [
+    phase("Build", [archive, build(".", { script: "build:fly" })]),
+    phase("Plan", [plan]),
+    phase("Gate", [gate("ship", { plan: plan.out.digest })]),
+    phase("Ship", [
+      flyRelease({
+        environment: "fly",
+        plan: "dist/fly.json",
+        digest: plan.out.digest,
+        gitSha: archive.out.commit,
+        source: { archive: archive.out.archive, digest: archive.out.digest, dir: archive.out.dir, start: "node server.js" },
+      }),
+    ]),
+    phase("Record", [releaseRecord({ plan: plan.out.file, digest: plan.out.digest, approval: { op: "release", gate: "ship" } })]),
+  ],
+});
+```
+
+The Machine's metadata names the plan's digest, and so does the ledger record, so `chant components status fly --live` reconciles them. Running the Op again for the same commit plans the same digest, leaves the Machine as it is, and records nothing twice.
+
+### Rolling a source release back
+
+A rollback Op takes the site back to the release it served before the latest one. Core's `releaseRollbackPlan` reads the release ledger, reads the earlier release's plan back, archives the same directory of the same commit again, and refuses unless the archive hashes to the digest that plan recorded. The gate binds to the rollback plan's digest. `flyRollback` puts back the Machine config `flyRelease` recorded for that release. It checks the archive against its digest before any flaps call, and checks that the recorded config carries exactly that tree. `releaseRollbackRecord` appends the restored release with `restores`, the actor and the approver:
+
+```ts
+import { Op, phase, gate, build, releaseRollbackPlan, releaseRollbackRecord } from "@intentius/chant/op";
+import { flyRollback } from "@intentius/chant-lexicon-fly";
+
+const plan = releaseRollbackPlan({ id: "plan", component: "app", env: "fly" });
+
+export default Op({
+  name: "rollback",
+  overview: "Put the previous release back on Fly once the rollback plan is approved",
+  phases: [
+    phase("Plan", [plan, build(".", { script: "build:fly" })]),
+    phase("Gate", [gate("rollback", { plan: plan.out.digest })]),
+    phase("Roll back", [
+      flyRollback({
+        environment: "fly",
+        plan: "dist/fly.json",
+        to: plan.out.to,
+        source: { archive: plan.out.archive, digest: plan.out.archiveDigest, dir: plan.out.dir },
+      }),
+    ]),
+    phase("Record", [releaseRollbackRecord({ plan: plan.out.file, digest: plan.out.digest, approval: { op: "rollback", gate: "rollback" } })]),
+  ],
+});
+```
+
+A rollback's own ledger record is not counted as a release, so running the Op again plans the same rollback, leaves the Machine as it is and records nothing. `to: "sha256:..."` on `releaseRollbackPlan` picks another release. Migrations are not undone.

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

@@ -17,7 +17,7 @@ Each activity is a direct REST call over an injectable HTTP client, imported fro
 | Activity | What it does |
 |----------|--------------|
 | `spriteCreate` | Create a sandbox. The caller-chosen `name` becomes the sprite `id` that every later activity keys on |
-| `spriteExec` | Run a command inside the sprite. A non-zero exit throws, so the phase fails and any `onFailure` compensation runs |
+| `spriteExec` | Run a command inside the sprite, with optional `env`, `dir` and `timeoutMs` (#2765). A non-zero exit or a `timeoutMs` overrun throws, so the phase fails and any `onFailure` compensation runs |
 | `spriteCheckpoint` | Snapshot the sprite under a caller-chosen `label` |
 | `spriteRestore` | Rewind the sprite to a labeled checkpoint |
 | `spriteDestroy` | Destroy the sprite (idempotent; an already-gone sprite is a no-op) |
@@ -106,6 +106,7 @@ The same lexicon ships more Sprite primitives, all imported from `@intentius/cha
 | 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 |
 | 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 |