@pplethai/cli 0.6.0 → 0.8.0

package/templates/golden-path/test/read-dataset.test.ts

@@ -0,0 +1,214 @@
+// readDataset (issue #270). The harness is the platform: tests see the URL,
+// the headers, the page, and the refusal a Builder would observe.
+
+import { describe, expect, it, vi } from "vitest";
+import { platformError } from "../src/call-service";
+import { readDataset } from "../src/read-dataset";
+import { makeHarness, serviceRefusal } from "./harness";
+
+const env = {
+  DEV_PERSONA: "none",
+  PPLE_SERVICES_URL: "https://services.test",
+  PPLE_APP_KEY: "app-key",
+};
+
+const SWEPT = "2026-11-01T00:00:00.000Z";
+
+describe("readDataset", () => {
+  it("sends the App Key, the user token and the query, and returns one page", async () => {
+    let seen: { authorization: string | null; userToken: string | null } | undefined;
+    const h = makeHarness(
+      {
+        services: (req) => {
+          seen = {
+            authorization: req.headers.get("authorization"),
+            userToken: req.headers.get("x-pple-user-token"),
+          };
+          return Response.json(
+            {
+              objects: [{ id: "branch-a", province: "เชียงใหม่" }],
+              next: "cursor-1",
+              sweptAt: SWEPT,
+              snapshot: 3,
+            },
+            { headers: { etag: '"3-abc"' } },
+          );
+        },
+      },
+      env,
+    );
+
+    const result = await readDataset(h.testEnv, "directory/branches", "offices", {
+      userToken: "user-token",
+      filter: { province: "เชียงใหม่", seats: { gte: 4, lt: 9 }, status: ["open", "closed"] },
+      sort: "-seats",
+      limit: 2,
+      fetchImpl: h.fetchImpl,
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      status: 200,
+      etag: '"3-abc"',
+      data: {
+        objects: [{ id: "branch-a", province: "เชียงใหม่" }],
+        next: "cursor-1",
+        sweptAt: SWEPT,
+        snapshot: 3,
+      },
+    });
+    expect(seen).toEqual({ authorization: "Bearer app-key", userToken: "user-token" });
+    const url = new URL(`https://services.test${h.calls.services[0]?.path ?? ""}`);
+    expect(url.pathname).toBe("/directory/branches/offices");
+    expect(url.searchParams.get("province")).toBe("เชียงใหม่");
+    expect(url.searchParams.get("seats[gte]")).toBe("4");
+    expect(url.searchParams.get("seats[lt]")).toBe("9");
+    expect(url.searchParams.getAll("status")).toEqual(["open", "closed"]);
+    expect(url.searchParams.get("sort")).toBe("-seats");
+    expect(url.searchParams.get("limit")).toBe("2");
+    expect(h.calls.services[0]?.method).toBe("GET");
+    expect(h.calls.services[0]?.headers).not.toHaveProperty("authorization");
+    expect(h.calls.services[0]?.headers).not.toHaveProperty("x-pple-user-token");
+  });
+
+  it("omits the user token unless one was given, and looks an object up by id", async () => {
+    let userToken: string | null = "unset";
+    const h = makeHarness(
+      {
+        services: (req) => {
+          userToken = req.headers.get("x-pple-user-token");
+          return Response.json({
+            object: { id: "branch-b", province: "กรุงเทพ" },
+            sweptAt: SWEPT,
+            snapshot: 3,
+          });
+        },
+      },
+      env,
+    );
+
+    const result = await readDataset(h.testEnv, "directory/branches", "offices", {
+      id: "branch-b",
+      fetchImpl: h.fetchImpl,
+    });
+
+    expect(userToken).toBeNull();
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toEqual({
+      object: { id: "branch-b", province: "กรุงเทพ" },
+      sweptAt: SWEPT,
+      snapshot: 3,
+    });
+    expect(h.calls.services[0]?.path).toBe("/directory/branches/offices/branch-b");
+  });
+
+  it("reads a singleton", async () => {
+    const h = makeHarness(
+      {
+        services: () => Response.json({ object: { title: "สรุปสาขา" }, sweptAt: SWEPT, snapshot: 1 }),
+      },
+      env,
+    );
+    const result = await readDataset(h.testEnv, "directory/branches", "summary", {
+      shape: "singleton",
+      fetchImpl: h.fetchImpl,
+    });
+    expect(result).toMatchObject({
+      ok: true,
+      data: { object: { title: "สรุปสาขา" }, sweptAt: SWEPT, snapshot: 1 },
+    });
+    expect(h.calls.services[0]?.path).toBe("/directory/branches/summary");
+  });
+
+  it("reads platform refusals from x-pple-error", async () => {
+    const codes = [
+      ["not_found", 404],
+      ["invalid_query", 400],
+      ["level_not_met", 403],
+      ["not_granted", 403],
+      ["user_token_invalid", 401],
+      ["no_mock", 404],
+    ] as const;
+    let next = serviceRefusal("not_found", 404);
+    const h = makeHarness({ services: () => next }, env);
+
+    for (const [code, status] of codes) {
+      next = serviceRefusal(code, status);
+      const result = await readDataset(h.testEnv, "directory/branches", "offices", {
+        userToken: "t",
+        fetchImpl: h.fetchImpl,
+      });
+      expect(result).toEqual({ ok: false, status, error: code });
+      const header = serviceRefusal(code, status);
+      if (code === "no_mock") expect(platformError(header)).toBeNull();
+      else expect(platformError(header)).toBe(code);
+    }
+  });
+
+  it("follows next and restarts when the snapshot changes", async () => {
+    const pages: { path: string }[] = [];
+    const h = makeHarness(
+      {
+        services: (req) => {
+          const url = new URL(req.url);
+          pages.push({ path: url.pathname + url.search });
+          const cursor = url.searchParams.get("next");
+          if (cursor === null && pages.length === 1) {
+            return Response.json({ objects: [{ id: "a" }], next: "old", sweptAt: SWEPT, snapshot: 1 });
+          }
+          if (cursor === "old") {
+            return Response.json({ objects: [{ id: "b" }], next: null, sweptAt: SWEPT, snapshot: 2 });
+          }
+          if (cursor === null) {
+            return Response.json({ objects: [{ id: "a2" }], next: "new", sweptAt: SWEPT, snapshot: 2 });
+          }
+          return Response.json({ objects: [{ id: "b2" }], next: null, sweptAt: SWEPT, snapshot: 2 });
+        },
+      },
+      env,
+    );
+
+    const result = await readDataset(h.testEnv, "directory/branches", "offices", {
+      limit: 1,
+      follow: true,
+      fetchImpl: h.fetchImpl,
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+      data: {
+        objects: [{ id: "a2" }, { id: "b2" }],
+        next: null,
+        snapshot: 2,
+        sweptAt: SWEPT,
+      },
+    });
+    expect(pages.map((page) => new URL(`https://services.test${page.path}`).searchParams.get("next"))).toEqual([
+      null,
+      "old",
+      null,
+      "new",
+    ]);
+  });
+
+  it("uses the injected fetch under vitest, including when a persona is set", async () => {
+    const fetchImpl = vi.fn<typeof fetch>(async () =>
+      Response.json({ objects: [], next: null, sweptAt: null, snapshot: null }),
+    );
+    const result = await readDataset(
+      { ...env, DEV_PERSONA: "hq-staff", DEV_REGISTRY_ERROR: "not_granted" },
+      "directory/branches",
+      "offices",
+      { fetchImpl },
+    );
+    expect(result).toMatchObject({ ok: true, data: { objects: [], next: null, sweptAt: null } });
+    expect(fetchImpl).toHaveBeenCalledOnce();
+    expect(String(fetchImpl.mock.calls[0]?.[0])).toBe("https://services.test/directory/branches/offices");
+
+    await expect(readDataset(env, "directory/branches", "offices")).rejects.toThrow(/injected fetch/);
+    await expect(
+      readDataset({ DEV_PERSONA: "none" }, "directory/branches", "offices", { fetchImpl }),
+    ).rejects.toThrow(/PPLE_SERVICES_URL/);
+  });
+});

package/templates/golden-path/test/service-call.test.ts

@@ -0,0 +1,166 @@
+// serviceCall (ADR-0024). The Identity header is base64url of the UTF-8 JSON,
+// so a Thai name round-trips. encodeIdentityHeader is the one encoder the
+// dev wrapper and callRegistry share; serviceCall undoes it.
+
+import { describe, expect, it } from "vitest";
+import type { Identity } from "../shared/api";
+import { encodeIdentityHeader } from "../src/identity-header";
+import worker from "../src/index";
+import { serviceCall } from "../src/registry";
+
+const IDENTITY: Identity = {
+  actor: {
+    sub: "u-delegate",
+    name: "ชื่อนกทดสอบ",
+    mobile: "0810000014",
+    kyc: {
+      status: "verified",
+      verified: true,
+      verifiedAt: "2024-04-01T00:00:00.000Z",
+      source: "membership",
+    },
+    membership: { memberSince: "2020-05-01" },
+  },
+  effective: {
+    isDelegated: true,
+    sub: "347513243977122153",
+    activeRole: "province",
+    eligibleRoles: ["province"],
+    provinces: ["เชียงใหม่"],
+    extraRoles: ["exco", "province_co"],
+  },
+};
+
+describe("serviceCall", () => {
+  it("round-trips the shared encoder, including a Thai name", () => {
+    const encoded = encodeIdentityHeader(IDENTITY);
+    expect(encoded).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(encoded).not.toContain("ชื่อ");
+
+    const call = serviceCall(
+      new Request("https://provider.invalid/offices", {
+        headers: {
+          "x-pple-consumer": "brave-purple-lion",
+          "x-pple-entry": "calm-amber-fox/branch-list",
+          "x-pple-identity": encoded,
+          "x-pple-user-token": "raw-token-must-not-surface",
+          authorization: "Bearer raw-token-must-not-surface",
+        },
+      }),
+    );
+
+    expect(call).toEqual({
+      consumer: "brave-purple-lion",
+      entry: "calm-amber-fox/branch-list",
+      identity: IDENTITY,
+    });
+    expect(JSON.stringify(call)).not.toContain("raw-token-must-not-surface");
+  });
+
+  it("round-trips a null effective sub", () => {
+    const identity: Identity = {
+      ...IDENTITY,
+      effective: { ...IDENTITY.effective, sub: null },
+    };
+    const call = serviceCall(
+      new Request("https://provider.invalid/", {
+        headers: {
+          "x-pple-consumer": "brave-purple-lion",
+          "x-pple-entry": "calm-amber-fox/branch-list",
+          "x-pple-identity": encodeIdentityHeader(identity),
+        },
+      }),
+    );
+    expect(call?.identity).toEqual(identity);
+  });
+
+  it("treats an Identity header with no effective sub as no Identity", () => {
+    const effective = {
+      isDelegated: IDENTITY.effective.isDelegated,
+      activeRole: IDENTITY.effective.activeRole,
+      eligibleRoles: IDENTITY.effective.eligibleRoles,
+      provinces: IDENTITY.effective.provinces,
+      extraRoles: IDENTITY.effective.extraRoles,
+    };
+    const call = serviceCall(
+      new Request("https://provider.invalid/", {
+        headers: {
+          "x-pple-consumer": "brave-purple-lion",
+          "x-pple-entry": "calm-amber-fox/branch-list",
+          "x-pple-identity": encodeIdentityHeader({ actor: IDENTITY.actor, effective } as Identity),
+        },
+      }),
+    );
+    expect(call?.identity).toBeNull();
+  });
+
+  it("treats an Identity header with no membership as no Identity", () => {
+    const stale = {
+      actor: {
+        sub: IDENTITY.actor.sub,
+        name: IDENTITY.actor.name,
+        mobile: IDENTITY.actor.mobile,
+        kyc: IDENTITY.actor.kyc,
+      },
+      effective: IDENTITY.effective,
+    };
+    const call = serviceCall(
+      new Request("https://provider.invalid/", {
+        headers: {
+          "x-pple-consumer": "brave-purple-lion",
+          "x-pple-entry": "calm-amber-fox/branch-list",
+          "x-pple-identity": encodeIdentityHeader(stale as Identity),
+        },
+      }),
+    );
+    expect(call?.identity).toBeNull();
+  });
+
+  it("returns the call with no Identity when the entry declares userToken none", () => {
+    expect(
+      serviceCall(
+        new Request("https://provider.invalid/", {
+          headers: {
+            "x-pple-consumer": "brave-purple-lion",
+            "x-pple-entry": "calm-amber-fox/branch-list",
+            "x-pple-user-token": "still-not-a-fact",
+          },
+        }),
+      ),
+    ).toEqual({
+      consumer: "brave-purple-lion",
+      entry: "calm-amber-fox/branch-list",
+      identity: null,
+    });
+  });
+
+  it("returns null when the request is not a platform registry call", () => {
+    expect(serviceCall(new Request("https://app.example/api/notes"))).toBeNull();
+    expect(
+      serviceCall(new Request("https://app.example/api/notes", { headers: { "x-pple-consumer": "only-one" } })),
+    ).toBeNull();
+  });
+
+  it("treats an identity header that is not the encoding as no Identity", () => {
+    expect(
+      serviceCall(
+        new Request("https://provider.invalid/", {
+          headers: {
+            "x-pple-consumer": "brave-purple-lion",
+            "x-pple-entry": "calm-amber-fox/branch-list",
+            "x-pple-identity": "not-json",
+          },
+        }),
+      ),
+    ).toEqual({
+      consumer: "brave-purple-lion",
+      entry: "calm-amber-fox/branch-list",
+      identity: null,
+    });
+  });
+
+  it("puts a registry slot on the Worker default export", () => {
+    expect(worker.registry).toEqual({});
+    expect(typeof worker.fetch).toBe("function");
+  });
+});

package/templates/golden-path/vite.config.ts

@@ -2,13 +2,14 @@ import { fileURLToPath } from "node:url";
 import { cloudflare } from "@cloudflare/vite-plugin";
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
+import { overlayMtimePlugin } from "./overlay-mtime.mjs";
 
 // The Cloudflare plugin reads wrangler.jsonc, runs the Worker in the real
 // Workers runtime during `vite dev`, and builds a deployable bundle with
 // `vite build`. `vite dev` serves the React app and the /api/* Worker from a
 // single origin, so no CORS or proxy config is needed.
 export default defineConfig({
-  plugins: [react(), cloudflare()],
+  plugins: [overlayMtimePlugin(), react(), cloudflare()],
   resolve: {
     alias: [
       // @pplethai/components ships a "development" export condition pointing at

package/templates/golden-path/vitest.config.ts

@@ -4,6 +4,7 @@ import {
   readD1Migrations,
 } from "@cloudflare/vitest-pool-workers";
 import { defineConfig } from "vitest/config";
+import { overlayMtimePlugin } from "./overlay-mtime.mjs";
 
 // Runs the smoke tests inside the real Workers runtime (workerd) with local
 // D1 and R2, so the tests exercise the same code paths as production. The D1
@@ -12,6 +13,7 @@ export default defineConfig(async () => {
   const migrations = await readD1Migrations(path.join(__dirname, "migrations"));
   return {
     plugins: [
+      overlayMtimePlugin(),
       cloudflareTest({
         wrangler: { configPath: "./wrangler.jsonc" },
         miniflare: {