@intentius/chant-lexicon-fly 0.18.7 → 0.18.9

package/dist/op/activities/emulator-images.d.ts

@@ -16,5 +16,5 @@
 /** Pinned mudflaps (Fly Machines / flaps emulator) image. */
 export declare const MUDFLAPS_IMAGE = "ghcr.io/intentius/mudflaps:0.4.0";
 /** Pinned spritzer (Fly Sprites emulator) image. */
-export declare const SPRITZER_IMAGE = "ghcr.io/intentius/spritzer:0.3.1";
+export declare const SPRITZER_IMAGE = "ghcr.io/intentius/spritzer:0.4.0";
 //# sourceMappingURL=emulator-images.d.ts.map

package/dist/op/activities/sprites-contract.d.ts

@@ -5,8 +5,8 @@
  * the fly resource surface generates + drift-checks against. The Sprites API
  * (api.sprites.dev) ships no such spec at any conventional path, so there is
  * nothing to diff automatically. This module is the manual stand-in: the exact
- * endpoint set the fly sprite activities (./sprites.ts) depend on, maintained by
- * hand from https://docs.sprites.dev.
+ * endpoint set the fly sprite activities (lifecycle, filesystem, config, tasks)
+ * depend on, maintained by hand from https://docs.sprites.dev.
  *
  * It anchors two fidelity checks:
  *   1. Coverage — every endpoint here must be served by the pinned spritzer
@@ -23,15 +23,19 @@
 /** One endpoint the fly sprite activities call. */
 export interface SpritesEndpoint {
     /** HTTP method, or "WS" for the control-WebSocket exec channel. */
-    method: "GET" | "POST" | "DELETE" | "WS";
+    method: "GET" | "POST" | "PUT" | "DELETE" | "WS";
     /** Path template under the Sprites base, e.g. `/v1/sprites/{id}/checkpoint`. */
     path: string;
-    /** The fly activity that calls it (./sprites.ts export). */
+    /** The fly activity that calls it (an activity module export). */
     activity: string;
 }
 /**
- * The Sprites endpoints ./sprites.ts depends on. Keep in sync with the activity
- * implementations — the unit test asserts every sprite activity is represented.
+ * The Sprites endpoints the fly sprite activities depend on, across the lifecycle
+ * (./sprites.ts), filesystem (./sprite-fs.ts), config reconcile
+ * (./sprite-config.ts), and keep-alive tasks (./sprite-tasks.ts) modules. Keep in
+ * sync with the activity implementations — the unit test asserts every sprite
+ * activity is represented, and the coverage test asserts the pinned spritzer
+ * serves each one.
  */
 export declare const SPRITES_CONTRACT: readonly SpritesEndpoint[];
 /**

package/dist/op/activities/sprites-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sprites-contract.d.ts","sourceRoot":"","sources":["../../../src/op/activities/sprites-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IACzC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAO7C,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAItE;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,CAAC,CAE1C"}
+{"version":3,"file":"sprites-contract.d.ts","sourceRoot":"","sources":["../../../src/op/activities/sprites-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAC;IACjD,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAwB7C,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAItE;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,CAAC,CAE1C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fly",
-  "version": "0.18.7",
+  "version": "0.18.9",
   "type": "module",
   "files": [
     "src/",
@@ -57,7 +57,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.18.7"
+    "@intentius/chant": "^0.18.9"
   },
   "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",

package/src/op/activities/emulator-images.ts

@@ -18,4 +18,4 @@
 export const MUDFLAPS_IMAGE = "ghcr.io/intentius/mudflaps:0.4.0";
 
 /** Pinned spritzer (Fly Sprites emulator) image. */
-export const SPRITZER_IMAGE = "ghcr.io/intentius/spritzer:0.3.1";
+export const SPRITZER_IMAGE = "ghcr.io/intentius/spritzer:0.4.0";

package/src/op/activities/sprite-config.docker.integration.test.ts

@@ -0,0 +1,98 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { spritesUp, spritesDown } from "./sprites-emulator";
+import { spriteCreate } from "./sprites";
+import { spriteWriteFile, spriteReadFile, spriteListDir, spriteRemove } from "./sprite-fs";
+import { spriteApplyNetworkPolicy, spriteApplyServices } from "./sprite-config";
+import { spriteTaskCreate, spriteTaskRelease } from "./sprite-tasks";
+
+// The filesystem / config-reconcile / keep-alive activities driven against the
+// REAL spritzer image (ghcr.io/intentius/spritzer), booted via `spritesUp` — the
+// twin of the lifecycle docker test. Proves the image serves these endpoints
+// with the same wire shape the in-process fake does. Docker required;
+// deterministically skipped in CI unless SPRITES_DOCKER=1.
+
+const CONTAINER = "chant-spritzer-config-it";
+const PORT = 4294;
+
+let available = false;
+let endpoint = "";
+
+async function inspect(id: string): Promise<{
+  fs: Record<string, string>;
+  netPolicy: Array<{ domain: string; action: string }>;
+  services: Record<string, { state: { status: string } }>;
+  tasks: Record<string, unknown>;
+}> {
+  const res = await fetch(`${endpoint}/v1/sprites/${id}`);
+  return (await res.json()) as never;
+}
+
+beforeAll(async () => {
+  if (process.env.CI && !process.env.SPRITES_DOCKER) {
+    available = false;
+    return;
+  }
+  try {
+    const up = await spritesUp({ name: CONTAINER, port: PORT, timeoutMs: 30_000 });
+    endpoint = up.endpoint;
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 60_000);
+
+afterAll(async () => {
+  if (available) await spritesDown({ name: CONTAINER });
+});
+
+describe("fs / config / tasks activities against real spritzer", () => {
+  test("filesystem round-trips (write → read → list → remove)", async (ctx) => {
+    if (!available) ctx.skip();
+    await spriteCreate({ name: "d-fs", endpoint });
+    await spriteWriteFile({ id: "d-fs", path: "/work/input", content: "hello", endpoint });
+    expect((await spriteReadFile({ id: "d-fs", path: "/work/input", endpoint })).content).toBe("hello");
+    await spriteWriteFile({ id: "d-fs", path: "/work/notes/a", content: "x", endpoint });
+    const list = await spriteListDir({ id: "d-fs", path: "/work", endpoint });
+    expect(list.map((e) => e.name).sort()).toEqual(["input", "notes"]);
+    await spriteRemove({ id: "d-fs", path: "/work/input", endpoint });
+    await expect(spriteReadFile({ id: "d-fs", path: "/work/input", endpoint })).rejects.toThrow(/not found/);
+  });
+
+  test("network policy reconcile converges", async (ctx) => {
+    if (!available) ctx.skip();
+    await spriteCreate({ name: "d-np", endpoint });
+    const rules = [
+      { domain: "api.anthropic.com", action: "allow" as const },
+      { domain: "*", action: "deny" as const },
+    ];
+    expect((await spriteApplyNetworkPolicy({ id: "d-np", rules, endpoint })).changed).toBe(true);
+    expect((await spriteApplyNetworkPolicy({ id: "d-np", rules, endpoint })).changed).toBe(false);
+    expect((await inspect("d-np")).netPolicy).toEqual(rules);
+  });
+
+  test("services reconcile creates + starts in dependency order", async (ctx) => {
+    if (!available) ctx.skip();
+    await spriteCreate({ name: "d-svc", endpoint });
+    const r = await spriteApplyServices({
+      id: "d-svc",
+      start: true,
+      endpoint,
+      services: [
+        { name: "web", cmd: "run-web", needs: ["db"], http_port: 8080 },
+        { name: "db", cmd: "run-db" },
+      ],
+    });
+    expect(r.started).toEqual(["db", "web"]);
+    expect((await inspect("d-svc")).services.web.state.status).toBe("running");
+  });
+
+  test("keep-alive task holds then releases (idempotent)", async (ctx) => {
+    if (!available) ctx.skip();
+    await spriteCreate({ name: "d-task", endpoint });
+    await spriteTaskCreate({ id: "d-task", name: "session", expire: "5m", endpoint });
+    expect(Object.keys((await inspect("d-task")).tasks)).toEqual(["session"]);
+    await spriteTaskRelease({ id: "d-task", name: "session", endpoint });
+    expect(Object.keys((await inspect("d-task")).tasks)).toEqual([]);
+    await expect(spriteTaskRelease({ id: "d-task", name: "session", endpoint })).resolves.toBeDefined();
+  });
+});

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

@@ -7,15 +7,29 @@ import { SPRITES_CONTRACT, normalizeEndpoint, contractKeys } from "./sprites-con
 describe("SPRITES_CONTRACT", () => {
   test("covers every sprite activity that calls the Sprites API", () => {
     const activities = new Set(SPRITES_CONTRACT.map((e) => e.activity));
-    // The six ./sprites.ts activities that make an HTTP/WS call.
+    // Every activity across the lifecycle, filesystem, config-reconcile, and
+    // keep-alive modules that makes an HTTP/WS call.
     expect(activities).toEqual(
       new Set([
+        // lifecycle (./sprites.ts)
         "spriteCreate",
         "spriteExec",
         "spriteCheckpoint",
         "listCheckpoints",
         "spriteRestore",
         "spriteDestroy",
+        // filesystem (./sprite-fs.ts)
+        "spriteWriteFile",
+        "spriteReadFile",
+        "spriteListDir",
+        "spriteRemove",
+        // config reconcile (./sprite-config.ts)
+        "spriteApplyNetworkPolicy",
+        "spriteApplyServices",
+        // keep-alive tasks (./sprite-tasks.ts)
+        "spriteTaskCreate",
+        "spriteTaskRefresh",
+        "spriteTaskRelease",
       ]),
     );
   });
@@ -23,7 +37,7 @@ describe("SPRITES_CONTRACT", () => {
   test("every entry has a v1 path and a known method", () => {
     for (const e of SPRITES_CONTRACT) {
       expect(e.path.startsWith("/v1/sprites")).toBe(true);
-      expect(["GET", "POST", "DELETE", "WS"]).toContain(e.method);
+      expect(["GET", "POST", "PUT", "DELETE", "WS"]).toContain(e.method);
     }
   });
 
@@ -43,18 +57,22 @@ describe("SPRITES_CONTRACT", () => {
     expect(keys.size).toBe(SPRITES_CONTRACT.length);
   });
 
-  test("every contract path segment appears in the sprites.ts source (drift anchor)", () => {
+  test("every contract path segment appears in the activity source (drift anchor)", () => {
     // Anchors the hand-authored contract to the activity implementations: if an
     // activity's endpoint path changes, a segment goes missing here and the
-    // contract must be updated in the same change.
-    const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "sprites.ts"), "utf-8");
+    // contract must be updated in the same change. Scans every module that owns
+    // contract endpoints, not just the lifecycle one.
+    const dir = dirname(fileURLToPath(import.meta.url));
+    const src = ["sprites.ts", "sprite-fs.ts", "sprite-config.ts", "sprite-tasks.ts"]
+      .map((f) => readFileSync(join(dir, f), "utf-8"))
+      .join("\n");
     const segments = new Set(
       SPRITES_CONTRACT.flatMap((e) =>
         e.path.split("/").filter((s) => s.length > 0 && !s.startsWith("{")),
       ),
     );
     for (const seg of segments) {
-      expect(src, `path segment "${seg}" from the contract is absent from sprites.ts`).toContain(seg);
+      expect(src, `path segment "${seg}" from the contract is absent from the activity source`).toContain(seg);
     }
   });
 });

package/src/op/activities/sprites-contract.ts

@@ -5,8 +5,8 @@
  * the fly resource surface generates + drift-checks against. The Sprites API
  * (api.sprites.dev) ships no such spec at any conventional path, so there is
  * nothing to diff automatically. This module is the manual stand-in: the exact
- * endpoint set the fly sprite activities (./sprites.ts) depend on, maintained by
- * hand from https://docs.sprites.dev.
+ * endpoint set the fly sprite activities (lifecycle, filesystem, config, tasks)
+ * depend on, maintained by hand from https://docs.sprites.dev.
  *
  * It anchors two fidelity checks:
  *   1. Coverage — every endpoint here must be served by the pinned spritzer
@@ -24,24 +24,45 @@
 /** One endpoint the fly sprite activities call. */
 export interface SpritesEndpoint {
   /** HTTP method, or "WS" for the control-WebSocket exec channel. */
-  method: "GET" | "POST" | "DELETE" | "WS";
+  method: "GET" | "POST" | "PUT" | "DELETE" | "WS";
   /** Path template under the Sprites base, e.g. `/v1/sprites/{id}/checkpoint`. */
   path: string;
-  /** The fly activity that calls it (./sprites.ts export). */
+  /** The fly activity that calls it (an activity module export). */
   activity: string;
 }
 
 /**
- * The Sprites endpoints ./sprites.ts depends on. Keep in sync with the activity
- * implementations — the unit test asserts every sprite activity is represented.
+ * The Sprites endpoints the fly sprite activities depend on, across the lifecycle
+ * (./sprites.ts), filesystem (./sprite-fs.ts), config reconcile
+ * (./sprite-config.ts), and keep-alive tasks (./sprite-tasks.ts) modules. Keep in
+ * sync with the activity implementations — the unit test asserts every sprite
+ * activity is represented, and the coverage test asserts the pinned spritzer
+ * serves each one.
  */
 export const SPRITES_CONTRACT: readonly SpritesEndpoint[] = [
+  // Lifecycle (./sprites.ts)
   { method: "POST", path: "/v1/sprites", activity: "spriteCreate" },
   { method: "WS", path: "/v1/sprites/{id}/exec", activity: "spriteExec" },
   { method: "POST", path: "/v1/sprites/{id}/checkpoint", activity: "spriteCheckpoint" },
   { method: "GET", path: "/v1/sprites/{id}/checkpoints", activity: "listCheckpoints" },
   { method: "POST", path: "/v1/sprites/{id}/checkpoints/{cp}/restore", activity: "spriteRestore" },
   { method: "DELETE", path: "/v1/sprites/{id}", activity: "spriteDestroy" },
+  // Filesystem (./sprite-fs.ts)
+  { method: "PUT", path: "/v1/sprites/{id}/fs/write", activity: "spriteWriteFile" },
+  { method: "GET", path: "/v1/sprites/{id}/fs/read", activity: "spriteReadFile" },
+  { method: "GET", path: "/v1/sprites/{id}/fs/list", activity: "spriteListDir" },
+  { method: "DELETE", path: "/v1/sprites/{id}/fs/delete", activity: "spriteRemove" },
+  // Network policy (./sprite-config.ts)
+  { method: "GET", path: "/v1/sprites/{id}/policy/network", activity: "spriteApplyNetworkPolicy" },
+  { method: "POST", path: "/v1/sprites/{id}/policy/network", activity: "spriteApplyNetworkPolicy" },
+  // Services (./sprite-config.ts)
+  { method: "GET", path: "/v1/sprites/{id}/services", activity: "spriteApplyServices" },
+  { method: "PUT", path: "/v1/sprites/{id}/services/{svc}", activity: "spriteApplyServices" },
+  { method: "POST", path: "/v1/sprites/{id}/services/{svc}/start", activity: "spriteApplyServices" },
+  // Keep-alive tasks (./sprite-tasks.ts)
+  { method: "POST", path: "/v1/sprites/{id}/tasks", activity: "spriteTaskCreate" },
+  { method: "PUT", path: "/v1/sprites/{id}/tasks/{name}", activity: "spriteTaskRefresh" },
+  { method: "DELETE", path: "/v1/sprites/{id}/tasks/{name}", activity: "spriteTaskRelease" },
 ] as const;
 
 /**