@intentius/chant-lexicon-fly 0.18.6 → 0.18.8

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

@@ -0,0 +1,159 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { loadActivities, type ActivityFn } from "@intentius/chant/op";
+import { createSpritesFake } from "./sprites-fake";
+import { spriteCreate as createImpl } from "./sprites";
+import {
+  spriteApplyNetworkPolicy,
+  spriteApplyServices,
+  validateNetworkRules,
+  networkRulesEqual,
+  validateServices,
+  serviceConfigEqual,
+  type NetworkRule,
+  type ServiceSpec,
+} from "./sprite-config";
+
+// Config reconcile (#849) — pure validators + end-to-end against the in-process
+// fake (S7), no Docker. Network policy is a whole-object replace; services are
+// additive + update, started in dependency order.
+
+let fake: { url: string; close(): Promise<void> };
+let prevBaseUrl: string | undefined;
+
+beforeAll(async () => {
+  fake = await createSpritesFake();
+  prevBaseUrl = process.env.SPRITES_BASE_URL;
+  process.env.SPRITES_BASE_URL = fake.url;
+});
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  await fake?.close();
+});
+
+async function inspect(id: string): Promise<{
+  netPolicy: NetworkRule[];
+  services: Record<string, { name: string; needs?: string[]; state: { status: string } }>;
+}> {
+  const res = await fetch(`${fake.url}/v1/sprites/${id}`);
+  return (await res.json()) as never;
+}
+
+describe("network policy validators (pure)", () => {
+  test("validateNetworkRules rejects a bad action / empty domain", () => {
+    expect(() => validateNetworkRules([{ domain: "", action: "allow" }])).toThrow(/missing domain/);
+    expect(() => validateNetworkRules([{ domain: "x", action: "nope" as never }])).toThrow(/allow.*deny/);
+    expect(() => validateNetworkRules([{ domain: "github.com", action: "allow" }])).not.toThrow();
+  });
+  test("networkRulesEqual is order-sensitive", () => {
+    const a: NetworkRule[] = [{ domain: "a", action: "allow" }, { domain: "b", action: "deny" }];
+    expect(networkRulesEqual(a, [...a])).toBe(true);
+    expect(networkRulesEqual(a, [a[1], a[0]])).toBe(false);
+    expect(networkRulesEqual(a, [a[0]])).toBe(false);
+  });
+});
+
+describe("service validators (pure)", () => {
+  test("validateServices returns a dependency-first order", () => {
+    const svcs: ServiceSpec[] = [
+      { name: "web", cmd: "run-web", needs: ["db"] },
+      { name: "db", cmd: "run-db" },
+    ];
+    expect(validateServices(svcs)).toEqual(["db", "web"]);
+  });
+  test("rejects a dangling needs and a cycle and a duplicate", () => {
+    expect(() => validateServices([{ name: "web", cmd: "x", needs: ["db"] }])).toThrow(/not defined/);
+    expect(() =>
+      validateServices([
+        { name: "a", cmd: "x", needs: ["b"] },
+        { name: "b", cmd: "x", needs: ["a"] },
+      ]),
+    ).toThrow(/cycle/);
+    expect(() =>
+      validateServices([
+        { name: "a", cmd: "x" },
+        { name: "a", cmd: "y" },
+      ]),
+    ).toThrow(/duplicate/);
+  });
+  test("serviceConfigEqual ignores undefined-vs-empty noise", () => {
+    expect(serviceConfigEqual({ cmd: "x" }, { cmd: "x", args: [], env: {} })).toBe(true);
+    expect(serviceConfigEqual({ cmd: "x", http_port: 80 }, { cmd: "x" })).toBe(false);
+  });
+});
+
+describe("spriteApplyNetworkPolicy reconcile", () => {
+  test("applies once, converges on re-apply, replaces on change", async () => {
+    await createImpl({ name: "np-1", endpoint: fake.url });
+    const rules: NetworkRule[] = [
+      { domain: "*.github.com", action: "allow" },
+      { domain: "*", action: "deny" },
+    ];
+    expect((await spriteApplyNetworkPolicy({ id: "np-1", rules, endpoint: fake.url })).changed).toBe(true);
+    expect((await inspect("np-1")).netPolicy).toEqual(rules);
+
+    // Idempotent: same ruleset → no change.
+    expect((await spriteApplyNetworkPolicy({ id: "np-1", rules, endpoint: fake.url })).changed).toBe(false);
+
+    // Changed ruleset → replaced.
+    const tighter: NetworkRule[] = [{ domain: "github.com", action: "allow" }, { domain: "*", action: "deny" }];
+    expect((await spriteApplyNetworkPolicy({ id: "np-1", rules: tighter, endpoint: fake.url })).changed).toBe(true);
+    expect((await inspect("np-1")).netPolicy).toEqual(tighter);
+  });
+
+  test("invalid rules throw before any HTTP", async () => {
+    await expect(
+      spriteApplyNetworkPolicy({ id: "np-1", rules: [{ domain: "", action: "allow" }], endpoint: fake.url }),
+    ).rejects.toThrow(/missing domain/);
+  });
+});
+
+describe("spriteApplyServices reconcile", () => {
+  test("creates services, starts them in dependency order, converges on re-apply", async () => {
+    await createImpl({ name: "svc-1", endpoint: fake.url });
+    const services: ServiceSpec[] = [
+      { name: "web", cmd: "run-web", needs: ["db"], http_port: 8080 },
+      { name: "db", cmd: "run-db" },
+    ];
+    const r1 = await spriteApplyServices({ id: "svc-1", services, start: true, endpoint: fake.url });
+    expect(new Set(r1.applied)).toEqual(new Set(["web", "db"]));
+    // Started dependency-first.
+    expect(r1.started).toEqual(["db", "web"]);
+
+    const state = await inspect("svc-1");
+    expect(Object.keys(state.services).sort()).toEqual(["db", "web"]);
+    expect(state.services.web.state.status).toBe("running");
+
+    // Re-apply unchanged → nothing applied.
+    const r2 = await spriteApplyServices({ id: "svc-1", services, endpoint: fake.url });
+    expect(r2.applied).toEqual([]);
+
+    // Change one → only it is re-applied.
+    const changed = services.map((s) => (s.name === "web" ? { ...s, http_port: 9090 } : s));
+    const r3 = await spriteApplyServices({ id: "svc-1", services: changed, endpoint: fake.url });
+    expect(r3.applied).toEqual(["web"]);
+  });
+
+  test("a dependency cycle throws before any HTTP", async () => {
+    await createImpl({ name: "svc-2", endpoint: fake.url });
+    await expect(
+      spriteApplyServices({
+        id: "svc-2",
+        services: [
+          { name: "a", cmd: "x", needs: ["b"] },
+          { name: "b", cmd: "x", needs: ["a"] },
+        ],
+        endpoint: fake.url,
+      }),
+    ).rejects.toThrow(/cycle/);
+  });
+});
+
+describe("config activities resolve by name", () => {
+  test("loadActivities([\"fly\"]) exposes the reconcile activities", async () => {
+    const activities: Map<string, ActivityFn> = await loadActivities(["fly"]);
+    expect(typeof activities.get("spriteApplyNetworkPolicy")).toBe("function");
+    expect(typeof activities.get("spriteApplyServices")).toBe("function");
+  });
+});

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

@@ -0,0 +1,246 @@
+/**
+ * Sprite config reconcile activities (#849) — the two pieces of genuine
+ * desired-state a Sprite carries: its outbound network policy and its background
+ * services. Unlike the sprite itself (an Op primitive with no reconcilable
+ * create body), these are set after create and persist across cold boots, so
+ * chant reconciles typed config against the live Sprite — the `flyApply`
+ * plan→CRUD pattern scoped to one Sprite, not a declarable resource.
+ *
+ * Both use the JSON `SpritesHttp` client from `sprites.ts`; endpoint + bearer
+ * resolution is shared. Validation is pure and runs before any HTTP (invalid
+ * rules / a `needs` cycle throw up front), so a bad config fails the step
+ * cleanly rather than half-applying.
+ *
+ * Scope (v1): network policy is a whole-object replace (converges by
+ * 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.
+ */
+
+import { resolveSpritesEndpoint, defaultSpritesHttp, type SpritesHttp } from "./sprites";
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Network policy ──────────────────────────────────────────────────────────────
+
+/** One outbound rule. Ordered — specificity is positional, so order is significant. */
+export interface NetworkRule {
+  domain: string;
+  action: "allow" | "deny";
+}
+
+export interface SpriteApplyNetworkPolicyArgs {
+  id: string;
+  /** The complete desired ruleset (whole-object replace). */
+  rules: NetworkRule[];
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteApplyNetworkPolicyResult {
+  /** True when the live policy differed and was replaced; false when already converged. */
+  changed: boolean;
+}
+
+/**
+ * Validate a ruleset: every rule needs a non-empty `domain` and an `allow`/`deny`
+ * `action`. Pure; throws on the first offender.
+ */
+export function validateNetworkRules(rules: NetworkRule[]): void {
+  rules.forEach((r, i) => {
+    if (!r || typeof r.domain !== "string" || r.domain.trim() === "") {
+      throw new Error(`network rule ${i}: missing domain`);
+    }
+    if (r.action !== "allow" && r.action !== "deny") {
+      throw new Error(`network rule ${i} (${r.domain}): action must be "allow" or "deny", got ${JSON.stringify(r.action)}`);
+    }
+  });
+}
+
+/** Order-sensitive equality of two rulesets (position is significant). Pure. */
+export function networkRulesEqual(a: NetworkRule[], b: NetworkRule[]): boolean {
+  if (a.length !== b.length) return false;
+  return a.every((r, i) => r.domain === b[i].domain && r.action === b[i].action);
+}
+
+const policyUrl = (base: string, id: string): string =>
+  `${base}/v1/sprites/${encodeURIComponent(id)}/policy/network`;
+
+/**
+ * Reconcile a Sprite's outbound network policy. GET the live ruleset, and POST
+ * the desired set only when it differs (`GET`/`POST /policy/network`). Returns
+ * whether a change was applied.
+ */
+export async function spriteApplyNetworkPolicy(
+  args: SpriteApplyNetworkPolicyArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteApplyNetworkPolicyResult> {
+  validateNetworkRules(args.rules);
+  const base = resolveSpritesEndpoint(args);
+  const url = policyUrl(base, args.id);
+
+  const cur = await http("GET", url, undefined, undefined, signal);
+  if (cur.status >= 300) throw new Error(`sprite ${args.id} get policy failed (${cur.status}): ${cur.text}`);
+  const live = (safeJson(cur.text) as { rules?: NetworkRule[] } | undefined)?.rules ?? [];
+  if (networkRulesEqual(live, args.rules)) {
+    console.log(`policy: sprite/${args.id} already converged (${args.rules.length} rules)`);
+    return { changed: false };
+  }
+
+  const res = await http("POST", url, { rules: args.rules }, undefined, signal);
+  if (res.status >= 300) throw new Error(`sprite ${args.id} set policy failed (${res.status}): ${res.text}`);
+  console.log(`policy: sprite/${args.id} applied ${args.rules.length} rules (${base})`);
+  return { changed: true };
+}
+
+// ── Services ─────────────────────────────────────────────────────────────────────
+
+/** A desired background service. Keyed by `name`; PUT is create-or-update. */
+export interface ServiceSpec {
+  name: string;
+  cmd: string;
+  args?: string[];
+  env?: Record<string, string>;
+  dir?: string;
+  /** Names of services that must start first. */
+  needs?: string[];
+  /** Route the Sprite's public URL to this port. */
+  http_port?: number;
+}
+
+export interface SpriteApplyServicesArgs {
+  id: string;
+  services: ServiceSpec[];
+  /** Start each service after applying (in dependency order). Default: false. */
+  start?: boolean;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteApplyServicesResult {
+  /** Names that were created or updated (converged services are skipped). */
+  applied: string[];
+  /** Names that were started (empty unless `start`). */
+  started: string[];
+}
+
+/**
+ * Validate a service set: names are unique, every `needs` target exists, and the
+ * dependency graph is acyclic. Pure; throws on the first violation. Returns the
+ * names in a valid start order (dependencies first).
+ */
+export function validateServices(services: ServiceSpec[]): string[] {
+  const byName = new Map<string, ServiceSpec>();
+  for (const s of services) {
+    if (!s.name) throw new Error("service: missing name");
+    if (byName.has(s.name)) throw new Error(`service ${s.name}: duplicate name`);
+    byName.set(s.name, s);
+  }
+  for (const s of services) {
+    for (const dep of s.needs ?? []) {
+      if (!byName.has(dep)) throw new Error(`service ${s.name}: needs "${dep}" which is not defined`);
+    }
+  }
+  // Topological order via DFS; a back-edge is a cycle.
+  const order: string[] = [];
+  const state = new Map<string, "visiting" | "done">();
+  const visit = (name: string, trail: string[]): void => {
+    const st = state.get(name);
+    if (st === "done") return;
+    if (st === "visiting") throw new Error(`service dependency cycle: ${[...trail, name].join(" -> ")}`);
+    state.set(name, "visiting");
+    for (const dep of byName.get(name)!.needs ?? []) visit(dep, [...trail, name]);
+    state.set(name, "done");
+    order.push(name);
+  };
+  for (const s of services) visit(s.name, []);
+  return order;
+}
+
+/** Comparable service config (the fields the reconcile diffs on). Pure. */
+export function serviceConfigEqual(a: Partial<ServiceSpec>, b: Partial<ServiceSpec>): boolean {
+  const norm = (s: Partial<ServiceSpec>): string =>
+    JSON.stringify({
+      cmd: s.cmd ?? "",
+      args: s.args ?? [],
+      env: s.env ?? {},
+      dir: s.dir ?? "",
+      needs: s.needs ?? [],
+      http_port: s.http_port ?? null,
+    });
+  return norm(a) === norm(b);
+}
+
+const servicesUrl = (base: string, id: string): string =>
+  `${base}/v1/sprites/${encodeURIComponent(id)}/services`;
+const serviceUrl = (base: string, id: string, svc: string): string =>
+  `${servicesUrl(base, id)}/${encodeURIComponent(svc)}`;
+
+function serviceBody(s: ServiceSpec): Record<string, unknown> {
+  return {
+    cmd: s.cmd,
+    ...(s.args ? { args: s.args } : {}),
+    ...(s.env ? { env: s.env } : {}),
+    ...(s.dir ? { dir: s.dir } : {}),
+    ...(s.needs ? { needs: s.needs } : {}),
+    ...(s.http_port !== undefined ? { http_port: s.http_port } : {}),
+  };
+}
+
+/**
+ * Reconcile a Sprite's background services (additive + update). Lists the live
+ * services, then `PUT`s each desired service that is new or changed
+ * (create-or-update by name); when `start` is set, `POST .../start`s them in
+ * dependency order. Converged services are skipped. Owned-only prune is out of
+ * scope (no delete in the Services REST surface).
+ */
+export async function spriteApplyServices(
+  args: SpriteApplyServicesArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteApplyServicesResult> {
+  const startOrder = validateServices(args.services);
+  const base = resolveSpritesEndpoint(args);
+  const byName = new Map(args.services.map((s) => [s.name, s]));
+
+  // Live services, keyed by name, for the create-vs-update diff.
+  const listRes = await http("GET", servicesUrl(base, args.id), undefined, undefined, signal);
+  if (listRes.status >= 300) throw new Error(`sprite ${args.id} list services failed (${listRes.status}): ${listRes.text}`);
+  const liveList = safeJson(listRes.text);
+  const live = new Map<string, Partial<ServiceSpec>>();
+  if (Array.isArray(liveList)) {
+    for (const s of liveList as Array<Partial<ServiceSpec> & { name?: string }>) {
+      if (s.name) live.set(s.name, s);
+    }
+  }
+
+  const applied: string[] = [];
+  for (const s of args.services) {
+    const cur = live.get(s.name);
+    if (cur && serviceConfigEqual(cur, s)) continue; // already converged
+    const res = await http("PUT", serviceUrl(base, args.id, s.name), serviceBody(s), undefined, signal);
+    if (res.status >= 300) throw new Error(`sprite ${args.id} apply service ${s.name} failed (${res.status}): ${res.text}`);
+    applied.push(s.name);
+  }
+  console.log(`services: sprite/${args.id} applied ${applied.length}/${args.services.length} (${base})`);
+
+  const started: string[] = [];
+  if (args.start) {
+    for (const name of startOrder) {
+      if (!byName.has(name)) continue;
+      const res = await http("POST", `${serviceUrl(base, args.id, name)}/start`, undefined, undefined, signal);
+      if (res.status >= 300) throw new Error(`sprite ${args.id} start service ${name} failed (${res.status}): ${res.text}`);
+      started.push(name);
+    }
+    console.log(`services: sprite/${args.id} started ${started.length} in dependency order`);
+  }
+
+  return { applied, started };
+}

package/src/op/activities/sprite-fs.test.ts

@@ -0,0 +1,136 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import {
+  loadActivities,
+  runOpLocally,
+  phase,
+  spriteCreate,
+  spriteExec,
+  spriteWriteFile,
+  spriteReadFile,
+  type ActivityFn,
+  type ActivityProfile,
+  type OpConfig,
+} from "@intentius/chant/op";
+import { createSpritesFake } from "./sprites-fake";
+import { spriteCreate as createImpl } from "./sprites";
+import {
+  spriteWriteFile as writeImpl,
+  spriteReadFile as readImpl,
+  spriteListDir as listImpl,
+  spriteRemove as removeImpl,
+  spriteFsUrl,
+} from "./sprite-fs";
+
+// Filesystem activities (#848) end-to-end against the in-process fake (S7) — no
+// Docker, runs in CI. Direct-impl calls cover the return values; an Op-level
+// stage → process → collect proves they resolve by name and compose.
+
+const PROFILES: Record<string, ActivityProfile> = {
+  longInfra: { startToCloseTimeout: "5m", retry: { maximumAttempts: 3, initialInterval: "1ms", backoffCoefficient: 1 } },
+  fastIdempotent: { startToCloseTimeout: "5m", retry: { maximumAttempts: 2, initialInterval: "1ms", backoffCoefficient: 1 } },
+};
+
+let fake: { url: string; close(): Promise<void> };
+let activities: Map<string, ActivityFn>;
+let prevBaseUrl: string | undefined;
+
+beforeAll(async () => {
+  fake = await createSpritesFake();
+  prevBaseUrl = process.env.SPRITES_BASE_URL;
+  process.env.SPRITES_BASE_URL = fake.url;
+  activities = await loadActivities(["fly"]);
+});
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  await fake?.close();
+});
+
+async function inspect(id: string): Promise<{ fs: Record<string, string> }> {
+  const res = await fetch(`${fake.url}/v1/sprites/${id}`);
+  return (await res.json()) as { fs: Record<string, string> };
+}
+
+describe("spriteFsUrl (pure)", () => {
+  test("builds a query string, dropping unset params", () => {
+    expect(spriteFsUrl("http://h", "s 1", "write", { path: "/a", mkdir: true, mode: undefined, workingDir: "" })).toBe(
+      "http://h/v1/sprites/s%201/fs/write?path=%2Fa&mkdir=true",
+    );
+  });
+  test("no params → no query", () => {
+    expect(spriteFsUrl("http://h", "s", "read", {})).toBe("http://h/v1/sprites/s/fs/read");
+  });
+});
+
+describe("fs activities resolve by name", () => {
+  test("loadActivities([\"fly\"]) exposes the four fs activities", () => {
+    for (const fn of ["spriteWriteFile", "spriteReadFile", "spriteListDir", "spriteRemove"]) {
+      expect(typeof activities.get(fn)).toBe("function");
+    }
+  });
+});
+
+describe("write → read → list → remove round-trip", () => {
+  test("round-trips against the fake, remove is idempotent", async () => {
+    await createImpl({ name: "fs-1", endpoint: fake.url });
+
+    await writeImpl({ id: "fs-1", path: "/work/input", content: "hello", endpoint: fake.url });
+    expect((await readImpl({ id: "fs-1", path: "/work/input", endpoint: fake.url })).content).toBe("hello");
+
+    await writeImpl({ id: "fs-1", path: "/work/notes/a.txt", content: "x", endpoint: fake.url });
+    const list = await listImpl({ id: "fs-1", path: "/work", endpoint: fake.url });
+    expect(list).toEqual(
+      expect.arrayContaining([
+        { name: "notes", type: "dir" },
+        { name: "input", type: "file", size: 5 },
+      ]),
+    );
+
+    await removeImpl({ id: "fs-1", path: "/work/input", endpoint: fake.url });
+    await expect(readImpl({ id: "fs-1", path: "/work/input", endpoint: fake.url })).rejects.toThrow(/not found/);
+    // Idempotent: removing an already-gone path is a no-op (404 tolerated).
+    await expect(removeImpl({ id: "fs-1", path: "/work/input", endpoint: fake.url })).resolves.toBeDefined();
+  });
+
+  test("reading a missing file throws not-found", async () => {
+    await createImpl({ name: "fs-2", endpoint: fake.url });
+    await expect(readImpl({ id: "fs-2", path: "/nope", endpoint: fake.url })).rejects.toThrow(/not found/);
+  });
+
+  test("recursive remove clears a whole subtree", async () => {
+    await createImpl({ name: "fs-3", endpoint: fake.url });
+    await writeImpl({ id: "fs-3", path: "/d/a", content: "1", endpoint: fake.url });
+    await writeImpl({ id: "fs-3", path: "/d/sub/b", content: "2", endpoint: fake.url });
+    await removeImpl({ id: "fs-3", path: "/d", recursive: true, endpoint: fake.url });
+    expect(await listImpl({ id: "fs-3", path: "/d", endpoint: fake.url })).toEqual([]);
+  });
+});
+
+describe("Op-level stage → process → collect (the example flow)", () => {
+  test("write input, exec copies it, read output — runs green by-name", async () => {
+    const op: OpConfig = {
+      name: "fs-agent-task",
+      overview: "stage an input file, process it, collect the result",
+      taskQueue: "sprites",
+      phases: [
+        phase("Create", [spriteCreate({ name: "fs-op-1" })]),
+        phase("Stage", [spriteWriteFile({ id: "fs-op-1", path: "/work/input", content: "hello" })]),
+        phase("Run", [spriteExec({ id: "fs-op-1", cmd: "cat /work/input > /work/output" })]),
+        phase("Collect", [spriteReadFile({ id: "fs-op-1", path: "/work/output" })]),
+      ],
+    };
+    const result = await runOpLocally(op, activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(result.records.map((r) => r.fn)).toEqual([
+      "spriteCreate",
+      "spriteWriteFile",
+      "spriteExec",
+      "spriteReadFile",
+    ]);
+    expect(result.records.every((r) => r.status === "ok")).toBe(true);
+
+    const state = await inspect("fs-op-1");
+    expect(state.fs["/work/output"]).toBe("hello");
+  });
+});