@intentius/chant-lexicon-fly 0.89.0 → 0.90.0

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

@@ -1,6 +1,7 @@
 import { describe, test, expect } from "vitest";
 import {
   resolveSpritesEndpoint,
+  resolveSpritesToken,
   DEFAULT_SPRITES_BASE_URL,
   accumulateExecFrames,
   parseCheckpointNdjson,
@@ -13,6 +14,8 @@ import {
   spriteRestore,
   listCheckpoints,
   spriteDestroy,
+  spriteDelete,
+  spriteUrl,
   type SpritesHttp,
   type Checkpoint,
 } from "./sprites";
@@ -141,6 +144,50 @@ describe("resolveSpritesEndpoint (S3)", () => {
   test("default is real Sprites", () => {
     expect(resolveSpritesEndpoint({}, {} as NodeJS.ProcessEnv)).toBe(DEFAULT_SPRITES_BASE_URL);
   });
+
+  // #2711 — the studio and wisp call it SPRITES_API_URL.
+  test("SPRITES_API_URL alias when SPRITES_BASE_URL is unset", () => {
+    expect(resolveSpritesEndpoint({}, { SPRITES_API_URL: "http://alias:9000" } as NodeJS.ProcessEnv)).toBe(
+      "http://alias:9000",
+    );
+  });
+
+  test("SPRITES_BASE_URL wins over SPRITES_API_URL", () => {
+    expect(
+      resolveSpritesEndpoint(
+        {},
+        { SPRITES_BASE_URL: "http://base:1", SPRITES_API_URL: "http://alias:2" } as NodeJS.ProcessEnv,
+      ),
+    ).toBe("http://base:1");
+  });
+});
+
+describe("resolveSpritesToken (#2711)", () => {
+  test("explicit arg wins", () => {
+    expect(resolveSpritesToken("arg-token", { SPRITES_API_TOKEN: "env" } as NodeJS.ProcessEnv)).toBe("arg-token");
+  });
+
+  test("SPRITES_API_TOKEN env when no arg", () => {
+    expect(resolveSpritesToken(undefined, { SPRITES_API_TOKEN: "env-token" } as NodeJS.ProcessEnv)).toBe(
+      "env-token",
+    );
+  });
+
+  test("SPRITE_TOKEN alias when SPRITES_API_TOKEN is unset", () => {
+    expect(resolveSpritesToken(undefined, { SPRITE_TOKEN: "alias-token" } as NodeJS.ProcessEnv)).toBe(
+      "alias-token",
+    );
+  });
+
+  test("SPRITES_API_TOKEN wins over SPRITE_TOKEN", () => {
+    expect(
+      resolveSpritesToken(undefined, { SPRITES_API_TOKEN: "orig", SPRITE_TOKEN: "alias" } as NodeJS.ProcessEnv),
+    ).toBe("orig");
+  });
+
+  test("undefined when nothing is set", () => {
+    expect(resolveSpritesToken(undefined, {} as NodeJS.ProcessEnv)).toBeUndefined();
+  });
 });
 
 // ── Command tokenizing + exec WS url ──────────────────────────────────────────
@@ -263,6 +310,61 @@ describe("spriteDestroy", () => {
   });
 });
 
+describe("spriteDelete (#2711)", () => {
+  test("is spriteDestroy under another name — same DELETE, same idempotence", async () => {
+    expect(spriteDelete).toBe(spriteDestroy);
+    const { http, calls } = recorder(() => ({ status: 200, text: "{}" }));
+    await spriteDelete({ id: "task-1", endpoint: "http://x" }, undefined, http);
+    expect(calls[0].method).toBe("DELETE");
+    expect(calls[0].url).toBe("http://x/v1/sprites/task-1");
+  });
+});
+
+describe("spriteUrl (#2711)", () => {
+  test("GETs /v1/sprites/{id} and returns its url", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: JSON.stringify({ url: "http://h/s/task-1" }) }));
+    const res = await spriteUrl({ id: "task-1", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual({ url: "http://h/s/task-1" });
+    expect(calls[0].method).toBe("GET");
+    expect(calls[0].url).toBe("http://x/v1/sprites/task-1");
+  });
+
+  test("throws when the sprite has no url", async () => {
+    const { http } = recorder(() => ({ status: 200, text: "{}" }));
+    await expect(spriteUrl({ id: "task-1", endpoint: "http://x" }, undefined, http)).rejects.toThrow(/no url/);
+  });
+
+  test("with a path: returns immediately once the check answers 2xx", async () => {
+    let checks = 0;
+    const { http, calls } = recorder((method, url) => {
+      if (method === "GET" && url === "http://x/v1/sprites/task-1") {
+        return { status: 200, text: JSON.stringify({ url: "http://h/s/task-1" }) };
+      }
+      checks += 1;
+      return { status: checks < 2 ? 503 : 200, text: "" };
+    });
+    const res = await spriteUrl(
+      { id: "task-1", endpoint: "http://x", path: "/", intervalMs: 1 },
+      undefined,
+      http,
+    );
+    expect(res).toEqual({ url: "http://h/s/task-1" });
+    expect(checks).toBe(2); // one 503, then 200
+    expect(calls.at(-1)?.url).toBe("http://h/s/task-1/");
+  });
+
+  test("with a path: throws once timeoutMs elapses without a match", async () => {
+    const { http } = recorder((method, url) =>
+      url === "http://x/v1/sprites/task-1"
+        ? { status: 200, text: JSON.stringify({ url: "http://h/s/task-1" }) }
+        : { status: 503, text: "nothing is answering" },
+    );
+    await expect(
+      spriteUrl({ id: "task-1", endpoint: "http://x", path: "/", timeoutMs: 5, intervalMs: 1 }, undefined, http),
+    ).rejects.toThrow(/did not answer/);
+  });
+});
+
 // ── Bearer header on the default client ───────────────────────────────────────
 
 describe("defaultSpritesHttp bearer header", () => {

package/src/op/activities/sprites.ts

@@ -20,6 +20,13 @@
  * S3: endpoint override via `SPRITES_BASE_URL` (an explicit `endpoint` arg wins,
  * then the env, then the real Sprites base), so the same Op targets real Sprites
  * or the in-process fake with no code change.
+ *
+ * #2711: the studio and wisp's own docs call these `SPRITES_API_URL` and
+ * `SPRITE_TOKEN` rather than `SPRITES_BASE_URL`/`SPRITES_API_TOKEN`. Both
+ * pairs are accepted — `resolveSpritesEndpoint`/`resolveSpritesToken` read the
+ * alias when the original name is unset, with the original always winning
+ * when both are present, so an existing deployment is never surprised by the
+ * alias taking over.
  */
 
 // `ws` is loaded inside spriteExec, not at the top. It is a CommonJS package
@@ -27,6 +34,8 @@
 // ESM, where that require throws. The top-level import put it on the path of
 // every project that imports the lexicon and needs the run fallback (#2613).
 
+import { sleep } from "@intentius/chant/op";
+
 export const DEFAULT_SPRITES_BASE_URL = "https://api.sprites.dev";
 
 // ── Pure helpers (unit-testable without http/ws) ──────────────────────────────
@@ -41,15 +50,27 @@ export function resolveSpritesEndpoint(
   args: { endpoint?: string } = {},
   env: NodeJS.ProcessEnv = process.env,
 ): string {
-  const base = args.endpoint || env.SPRITES_BASE_URL || DEFAULT_SPRITES_BASE_URL;
+  const base = args.endpoint || env.SPRITES_BASE_URL || env.SPRITES_API_URL || DEFAULT_SPRITES_BASE_URL;
   return base.replace(/\/$/, "");
 }
 
+/**
+ * Resolve the bearer token (#2711): an explicit `token` arg wins, then
+ * `SPRITES_API_TOKEN`, then its alias `SPRITE_TOKEN`. Pure — mirrors
+ * `resolveSpritesEndpoint`.
+ */
+export function resolveSpritesToken(
+  token: string | undefined = undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  return token ?? env.SPRITES_API_TOKEN ?? env.SPRITE_TOKEN;
+}
+
 const spritesUrl = (base: string): string => `${base}/v1/sprites`;
-const spriteUrl = (base: string, id: string): string => `${spritesUrl(base)}/${encodeURIComponent(id)}`;
+const spriteResourceUrl = (base: string, id: string): string => `${spritesUrl(base)}/${encodeURIComponent(id)}`;
 // Create uses REST JSON; exec is the control WebSocket below; checkpoints are NDJSON.
-const spriteCheckpointUrl = (base: string, id: string): string => `${spriteUrl(base, id)}/checkpoint`;
-const spriteCheckpointsUrl = (base: string, id: string): string => `${spriteUrl(base, id)}/checkpoints`;
+const spriteCheckpointUrl = (base: string, id: string): string => `${spriteResourceUrl(base, id)}/checkpoint`;
+const spriteCheckpointsUrl = (base: string, id: string): string => `${spriteResourceUrl(base, id)}/checkpoints`;
 const spriteCheckpointRestoreUrl = (base: string, id: string, cp: string): string =>
   `${spriteCheckpointsUrl(base, id)}/${encodeURIComponent(cp)}/restore`;
 
@@ -354,7 +375,7 @@ export function defaultSpritesHttp(token?: string, fetchImpl: typeof fetch = fet
   return async (method, url, body, headers, signal) => {
     const h: Record<string, string> = { ...headers };
     if (body !== undefined) h["content-type"] = "application/json";
-    const tok = token ?? process.env.SPRITES_API_TOKEN;
+    const tok = resolveSpritesToken(token);
     if (tok) h["authorization"] = `Bearer ${tok}`;
     const res = await fetchImpl(url, {
       method,
@@ -393,7 +414,7 @@ export async function spriteCreate(
 export async function spriteExec(args: SpriteExecArgs, signal?: AbortSignal): Promise<SpriteExecResult> {
   const base = resolveSpritesEndpoint(args);
   const url = spriteExecWsUrl(base, args.id, args.cmd);
-  const token = args.token ?? process.env.SPRITES_API_TOKEN;
+  const token = resolveSpritesToken(args.token);
   const headers: Record<string, string> = {};
   if (token) headers.Authorization = `Bearer ${token}`;
   const { default: WebSocket } = await import("ws");
@@ -522,10 +543,90 @@ export async function spriteDestroy(
   http: SpritesHttp = defaultSpritesHttp(args.token),
 ): Promise<Record<string, never>> {
   const base = resolveSpritesEndpoint(args);
-  const res = await http("DELETE", spriteUrl(base, args.id), undefined, undefined, signal);
+  const res = await http("DELETE", spriteResourceUrl(base, args.id), undefined, undefined, signal);
   if (res.status >= 300 && res.status !== 404) {
     throw new Error(`sprite ${args.id} destroy failed (${res.status}): ${res.text}`);
   }
   console.log(`destroyed: sprite/${args.id} (${base})`);
   return {};
 }
+
+/**
+ * Delete the sprite (#2711) — the same idempotent `DELETE /v1/sprites/{id}` as
+ * `spriteDestroy`, under the name spritzer, wisp and the other lexicons'
+ * delete activities (`awsDelete`, `gcpDelete`, `azDelete`) use. A literal
+ * alias, not a reimplementation, so the two names can never drift: an Op
+ * authored against either resolves to the same call. `spriteDestroy` stays —
+ * it is the name every existing Op, example and the `op-verb-class` registry
+ * already depend on.
+ */
+export const spriteDelete = spriteDestroy;
+export type SpriteDeleteArgs = SpriteDestroyArgs;
+
+export interface SpriteUrlArgs {
+  /** Target sprite id. */
+  id: string;
+  /**
+   * Wait until this path on the sprite's URL answers, instead of returning
+   * the URL immediately. Unset (default): no wait, just resolve the URL.
+   */
+  path?: string;
+  /** Expected status while waiting. Default: any 2xx. */
+  status?: number;
+  /** Max time to wait for `path` to answer, ms. Default: `10000`. */
+  timeoutMs?: number;
+  /** Delay between polls, ms. Default: `500`. */
+  intervalMs?: number;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteUrlResult {
+  url: string;
+}
+
+/**
+ * Resolve the sprite's URL (#2711) — `spriteCreate` returns it too, but
+ * 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
+ * bind their `http_port` after `spriteServiceStart`.
+ */
+export async function spriteUrl(
+  args: SpriteUrlArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteUrlResult> {
+  const base = resolveSpritesEndpoint(args);
+  const res = await http("GET", spriteResourceUrl(base, args.id), undefined, undefined, signal);
+  if (res.status >= 300) throw new Error(`sprite ${args.id} url lookup failed (${res.status}): ${res.text}`);
+  const url = (safeJson(res.text) as { url?: string } | undefined)?.url;
+  if (!url) throw new Error(`sprite ${args.id} has no url`);
+
+  if (args.path !== undefined) {
+    const timeoutMs = args.timeoutMs ?? 10_000;
+    const intervalMs = args.intervalMs ?? 500;
+    const target = `${url}${args.path}`;
+    const deadline = Date.now() + timeoutMs;
+    let lastErr = "";
+    for (;;) {
+      if (signal?.aborted) throw new Error(`sprite ${args.id} url wait aborted`);
+      try {
+        const check = await http("GET", target, undefined, undefined, signal);
+        const ok = args.status !== undefined ? check.status === args.status : check.status >= 200 && check.status < 300;
+        if (ok) {
+          console.log(`url: sprite/${args.id} answers on ${target} (${check.status})`);
+          return { url };
+        }
+        lastErr = `status ${check.status} (want ${args.status ?? "2xx"})`;
+      } catch (e) {
+        lastErr = e instanceof Error ? e.message : String(e);
+      }
+      if (Date.now() >= deadline) throw new Error(`sprite ${args.id} url ${target} did not answer: ${lastErr}`);
+      await sleep(intervalMs, signal);
+    }
+  }
+
+  return { url };
+}

package/src/op/builders.ts

@@ -28,9 +28,18 @@
 
 import { activity, type NamedActivityStep, type WithStepRefs } from "@intentius/chant/op";
 import type { ActivityStep } from "@intentius/chant/op";
-import type { SpriteCreateArgs, SpriteExecArgs, SpriteCheckpointArgs, SpriteRestoreArgs, ListCheckpointsArgs, SpriteDestroyArgs } from "./activities/sprites";
+import type { SpriteCreateArgs, SpriteExecArgs, SpriteCheckpointArgs, SpriteRestoreArgs, ListCheckpointsArgs, SpriteDestroyArgs, SpriteDeleteArgs, SpriteUrlArgs } from "./activities/sprites";
 import type { SpriteWriteFileArgs, SpriteReadFileArgs, SpriteListDirArgs, SpriteRemoveArgs } from "./activities/sprite-fs";
 import type { SpriteApplyNetworkPolicyArgs, SpriteApplyServicesArgs } from "./activities/sprite-config";
+import type {
+  SpriteServiceCreateArgs,
+  SpriteServiceGetArgs,
+  SpriteServiceListArgs,
+  SpriteServiceStartArgs,
+  SpriteServiceStopArgs,
+  SpriteServiceDeleteArgs,
+  SpriteServiceLogsArgs,
+} from "./activities/sprite-services";
 import type { SpriteTaskCreateArgs, SpriteTaskRefreshArgs, SpriteTaskReleaseArgs } from "./activities/sprite-tasks";
 import type { SpritesUpArgs, SpritesDownArgs } from "./activities/sprites-emulator";
 
@@ -75,6 +84,10 @@ export const spriteRestore = spriteStep<SpriteRestoreArgs>("spriteRestore", "lon
 export const listCheckpoints = spriteStep<ListCheckpointsArgs>("listCheckpoints", "fastIdempotent");
 /** Destroy a sprite — the fully typed twin of core's `spriteDestroy`. Defaults to the `fastIdempotent` profile. */
 export const spriteDestroy = spriteStep<SpriteDestroyArgs>("spriteDestroy", "fastIdempotent");
+/** Delete a sprite (#2711; alias of `spriteDestroy`). Defaults to the `fastIdempotent` profile. */
+export const spriteDelete = spriteStep<SpriteDeleteArgs>("spriteDelete", "fastIdempotent");
+/** Resolve a sprite's URL, optionally waiting until a path on it answers (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteUrl = spriteStep<SpriteUrlArgs>("spriteUrl", "fastIdempotent");
 /** Write a file into a sprite — the fully typed twin of core's `spriteWriteFile`. Defaults to the `fastIdempotent` profile. */
 export const spriteWriteFile = spriteStep<SpriteWriteFileArgs>("spriteWriteFile", "fastIdempotent");
 /** Read a file from a sprite — the fully typed twin of core's `spriteReadFile`. Defaults to the `fastIdempotent` profile. */
@@ -87,6 +100,20 @@ export const spriteRemove = spriteStep<SpriteRemoveArgs>("spriteRemove", "fastId
 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. */
 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");
+/** Get one background service's definition and live state (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceGet = spriteStep<SpriteServiceGetArgs>("spriteServiceGet", "fastIdempotent");
+/** List a sprite's background services (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceList = spriteStep<SpriteServiceListArgs>("spriteServiceList", "fastIdempotent");
+/** Start a stopped background service (#2711). Defaults to the `longInfra` profile (the NDJSON round trip). */
+export const spriteServiceStart = spriteStep<SpriteServiceStartArgs>("spriteServiceStart", "longInfra");
+/** Stop a running background service (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceStop = spriteStep<SpriteServiceStopArgs>("spriteServiceStop", "fastIdempotent");
+/** Delete a background service, idempotent (#2711). Defaults to the `fastIdempotent` profile. */
+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");
 /** 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. */

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

@@ -78,7 +78,7 @@ When the `Run` phase's command exits non-zero, `spriteExec` throws, the phase fa
 
 ## Targeting the emulator or real Sprites
 
-The activities resolve their endpoint in this order: an explicit `endpoint` arg, then `SPRITES_BASE_URL`, then the real Sprites base. The same Op targets an emulator or real Sprites with no code change. The default `fetch` client adds `Authorization: Bearer ${SPRITES_API_TOKEN}` when a token is set; the emulator ignores it.
+The activities resolve their endpoint in this order: an explicit `endpoint` arg, then `SPRITES_BASE_URL`, then its alias `SPRITES_API_URL` (the name the studio and wisp's own docs use), then the real Sprites base. The same Op targets an emulator or real Sprites with no code change. The default `fetch` client adds `Authorization: Bearer <token>` when a token is set — `SPRITES_API_TOKEN`, or its alias `SPRITE_TOKEN` — the emulator ignores it. Either alias is read only when the original name is unset, so an existing deployment using `SPRITES_BASE_URL`/`SPRITES_API_TOKEN` is unaffected.
 
 ```bash
 # Point at a self-hosted or in-process emulator.
@@ -105,9 +105,11 @@ 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 |
+| 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.
+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.
 
 ## Where it fits