@pplethai/cli 0.6.0 → 0.8.0

package/templates/golden-path/src/dev-call-service.ts

@@ -0,0 +1,391 @@
+// Offline Consumer calls (ADR-0026). Active only where `import.meta.env.DEV`
+// is true and `DEV_PERSONA` is not `"none"` — `vite dev`, not vitest and not
+// the production build. `callService` reaches this module only from that
+// branch, so `vite build` drops it the same way it drops the Persona bypass
+// (ADR-0011).
+//
+// The overlay is `.pple/registry/<provider>/<name>/`, written by the CLI.
+// Vite's `import.meta.glob` skips a dot-folder unless the dot sits in the
+// pattern's fixed base, so the glob below keeps `.pple/registry` in that
+// base. CI has no overlay; tests pass a fixture glob to `answerFromOverlay`
+// and never read `.pple/`.
+//
+// Offline the app is granted, at least Beta, and the entry is listed.
+// Platform refusals come only from `DEV_REGISTRY_ERROR`. `getLegalIdentity`
+// does not use this module: its built-in Persona answer stays in front of
+// `callService`.
+
+import type { PlatformErrorCode } from "./call-service";
+import { DEV_PERSONAS, DEFAULT_DEV_PERSONA, resolveDevPersona } from "./dev-personas";
+
+/** Statuses for every platform code. Keyed by the union, so a new code fails typecheck here. */
+const PLATFORM_ERROR_STATUS: Record<PlatformErrorCode, number> = {
+  invalid_app_key: 401,
+  not_listed: 404,
+  not_granted: 403,
+  needs_beta: 403,
+  user_token_invalid: 401,
+  identity_unavailable: 503,
+  provider_unavailable: 502,
+  provider_timeout: 504,
+  method_not_allowed: 405,
+  not_found: 404,
+  invalid_query: 400,
+  level_not_met: 403,
+};
+
+const MOCK_HEADER = "x-pple-mock";
+const ERROR_HEADER = "x-pple-error";
+
+/** Statuses that must not carry a body. A mock that sets one still answers. */
+const NULL_BODY = new Set([101, 204, 205, 304]);
+
+export interface MockCase {
+  method?: string;
+  path?: string;
+  persona?: string | readonly string[];
+  status?: number;
+  headers?: Readonly<Record<string, string>>;
+  body?: unknown;
+}
+
+export interface OverlayCall {
+  entry: string;
+  /** Path tail `callService` received, query included. The query is not matched. */
+  path: string;
+  method?: string;
+  userToken?: string;
+  /** Active Persona name. A name the Builder added matches only unscoped cases. */
+  persona: string;
+  devRegistryError?: string;
+}
+
+interface IndexedEntry {
+  userToken: "required" | "none" | null;
+  cases: unknown[];
+}
+
+/**
+ * The first case that matches, or null. `method` and `persona` are optional
+ * on a case and then match anything. An omitted `path` matches any path — a
+ * root route has to say `"/"` or it would match every tail. `"/"` is the
+ * empty tail. `:param` is one segment. A final `*` segment matches one or
+ * more remaining segments. The query is ignored.
+ */
+export function matchMockCase(
+  cases: readonly unknown[],
+  method: string,
+  path: string,
+  persona: string,
+): MockCase | null {
+  for (const item of cases) {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) continue;
+    const record = item as Record<string, unknown>;
+    if (!methodMatches("method" in record ? record.method : undefined, method)) continue;
+    if (!pathMatches("path" in record ? record.path : undefined, path)) continue;
+    if (!personaMatches("persona" in record ? record.persona : undefined, persona)) continue;
+    return record as MockCase;
+  }
+  return null;
+}
+
+/**
+ * The response a Builder observes for one offline call. `files` is an
+ * `import.meta.glob` result (path → raw text), either the overlay or a
+ * fixture.
+ */
+export function answerFromOverlay(
+  files: Readonly<Record<string, unknown>>,
+  call: OverlayCall,
+): Response {
+  const forced = forcedError(call.devRegistryError, call.entry);
+  if (forced) return platformRefusal(forced);
+
+  const entry = indexOverlay(files).get(call.entry);
+  if (!entry) return noMock(missingEntryMessage(call.entry));
+
+  if (entry.userToken === "required" && !hasToken(call.userToken)) {
+    return platformRefusal("user_token_invalid");
+  }
+
+  const method = call.method?.trim() || "GET";
+  const matched = matchMockCase(entry.cases, method, call.path, call.persona);
+  if (!matched) return noMock(missingRouteMessage(call.entry, method, call.path));
+  return mockResponse(call.entry, matched);
+}
+
+/** `npm run dev` entry. Reads the overlay glob and the active Persona. */
+export function answerOfflineCall(
+  env: { DEV_PERSONA?: string; DEV_REGISTRY_ERROR?: string },
+  entry: string,
+  path: string,
+  init: RequestInit = {},
+  options: { userToken?: string } = {},
+): Response {
+  return answerFromOverlay(overlayFiles(), {
+    entry,
+    path,
+    method: init.method,
+    userToken: options.userToken,
+    persona: activePersonaName(env.DEV_PERSONA),
+    devRegistryError: env.DEV_REGISTRY_ERROR,
+  });
+}
+
+function overlayFiles(): Record<string, unknown> {
+  // Production inlines DEV as false and drops the glob, including any
+  // overlay files that happen to be on disk at build time. The dot-folder
+  // is in the fixed base (ADR-0026).
+  if (!import.meta.env.DEV) return {};
+  return import.meta.glob("../.pple/registry/**/*", {
+    eager: true,
+    query: "?raw",
+    import: "default",
+  });
+}
+
+function activePersonaName(configured: string | undefined): string {
+  const key = configured?.trim() || DEFAULT_DEV_PERSONA;
+  if (Object.hasOwn(DEV_PERSONAS, key)) return key;
+  // Unknown names warn and sign in as the default, same as the rest of local dev.
+  resolveDevPersona(configured);
+  return DEFAULT_DEV_PERSONA;
+}
+
+function indexOverlay(files: Readonly<Record<string, unknown>>): Map<string, IndexedEntry> {
+  const found = new Map<string, { entryMd?: string; responses?: string }>();
+  for (const [file, value] of Object.entries(files)) {
+    const text = asText(value);
+    if (text === null) continue;
+    const path = file.split("?")[0]?.replaceAll("\\", "/") ?? file;
+    const entryMd = path.match(/(?:^|\/)([^/]+)\/([^/]+)\/entry\.md$/);
+    if (entryMd?.[1] && entryMd[2]) {
+      const id = `${entryMd[1]}/${entryMd[2]}`;
+      const row = found.get(id) ?? {};
+      row.entryMd = text;
+      found.set(id, row);
+      continue;
+    }
+    const responses = path.match(/(?:^|\/)([^/]+)\/([^/]+)\/mocks\/responses\.json$/);
+    if (responses?.[1] && responses[2]) {
+      const id = `${responses[1]}/${responses[2]}`;
+      const row = found.get(id) ?? {};
+      row.responses = text;
+      found.set(id, row);
+    }
+  }
+
+  const entries = new Map<string, IndexedEntry>();
+  for (const [id, row] of found) {
+    entries.set(id, {
+      userToken: row.entryMd ? declaredUserToken(row.entryMd) : null,
+      cases: row.responses ? parseCases(id, row.responses) : [],
+    });
+  }
+  return entries;
+}
+
+function asText(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  if (value !== null && typeof value === "object" && "default" in value) {
+    const inner = (value as { default: unknown }).default;
+    if (typeof inner === "string") return inner;
+  }
+  return null;
+}
+
+function declaredUserToken(entryMd: string): "required" | "none" | null {
+  const fence = entryMd.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  const front = fence?.[1];
+  if (!front) return null;
+  for (const line of front.split(/\r?\n/)) {
+    const match = /^userToken:\s*(.*?)\s*$/.exec(line);
+    if (!match) continue;
+    const value = (match[1] ?? "").replace(/^["']|["']$/g, "");
+    if (value === "required" || value === "none") return value;
+    return null;
+  }
+  return null;
+}
+
+function parseCases(entry: string, text: string): unknown[] {
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    if (Array.isArray(parsed)) return parsed;
+  } catch {
+    // Fall through to the warning. A broken file is "no case matched".
+  }
+  console.warn(
+    `callService could not read .pple/registry/${entry}/mocks/responses.json. Run pple registry to refresh it.`,
+  );
+  return [];
+}
+
+function hasToken(userToken: string | undefined): boolean {
+  return userToken !== undefined && userToken.trim() !== "";
+}
+
+/**
+ * A per-entry `<provider>/<name>=<code>` wins over a bare `<code>`. An
+ * unknown code is ignored, so a bad per-entry rule falls through to the
+ * global one. Checked before the missing-token refusal: `not_granted` and
+ * `needs_beta` are answers the platform gives before it looks at the token.
+ */
+export function forcedError(spec: string | undefined, entry: string): PlatformErrorCode | null {
+  if (spec === undefined || spec.trim() === "") return null;
+  const rules: { entry: string | null; code: string }[] = [];
+  for (const part of spec.split(",")) {
+    const item = part.trim();
+    if (item === "") continue;
+    const eq = item.indexOf("=");
+    if (eq === -1) {
+      rules.push({ entry: null, code: item });
+      continue;
+    }
+    const id = item.slice(0, eq).trim();
+    const code = item.slice(eq + 1).trim();
+    if (id === "" || code === "") {
+      console.warn(`DEV_REGISTRY_ERROR ignores "${item}".`);
+      continue;
+    }
+    rules.push({ entry: id, code });
+  }
+
+  const known = rules.filter((rule) => {
+    if (isPlatformCode(rule.code)) return true;
+    console.warn(`DEV_REGISTRY_ERROR ignores unknown code "${rule.code}".`);
+    return false;
+  });
+  const specific = known.find((rule) => rule.entry === entry);
+  if (specific) return specific.code as PlatformErrorCode;
+  const global = known.find((rule) => rule.entry === null);
+  return global ? (global.code as PlatformErrorCode) : null;
+}
+
+function isPlatformCode(code: string): code is PlatformErrorCode {
+  return Object.prototype.hasOwnProperty.call(PLATFORM_ERROR_STATUS, code);
+}
+
+export function platformRefusal(code: PlatformErrorCode): Response {
+  return Response.json(
+    { error: code },
+    { status: PLATFORM_ERROR_STATUS[code], headers: { [ERROR_HEADER]: code } },
+  );
+}
+
+function noMock(message: string): Response {
+  return Response.json(
+    { error: "no_mock", message },
+    { status: 404, headers: { [ERROR_HEADER]: "no_mock" } },
+  );
+}
+
+function missingEntryMessage(entry: string): string {
+  return `ไม่มี ${entry} ใน .pple/registry/ — รัน pple registry เพื่อดึงข้อมูลจำลอง`;
+}
+
+function missingRouteMessage(entry: string, method: string, path: string): string {
+  const tail = path === "" ? "/" : path;
+  return `${entry} ไม่มีข้อมูลจำลองสำหรับ ${method.toUpperCase()} ${tail} — รัน pple registry เพื่อรีเฟรช`;
+}
+
+function mockResponse(entry: string, matched: MockCase): Response {
+  const headers = new Headers();
+  const raw = matched.headers;
+  if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+    for (const [name, value] of Object.entries(raw)) {
+      if (typeof value !== "string") continue;
+      if (name.toLowerCase().startsWith("x-pple-")) continue;
+      headers.set(name, value);
+    }
+  }
+  headers.set(MOCK_HEADER, entry);
+
+  const status = httpStatus(matched.status);
+  if (NULL_BODY.has(status)) return new Response(null, { status, headers });
+
+  const body = matched.body;
+  if (body === undefined) return new Response(null, { status, headers });
+  // A string is text (issue #230). Every other JSON value is a JSON body.
+  if (typeof body === "string") {
+    if (!headers.has("content-type")) headers.set("content-type", "text/plain;charset=UTF-8");
+    return new Response(body, { status, headers });
+  }
+  if (!headers.has("content-type")) headers.set("content-type", "application/json");
+  return new Response(JSON.stringify(body), { status, headers });
+}
+
+function httpStatus(value: unknown): number {
+  if (typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599) {
+    return value;
+  }
+  return 200;
+}
+
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]);
+const LITERAL_SEGMENT = /^[A-Za-z0-9._~-]+$/;
+const PARAM_SEGMENT = /^:[A-Za-z_][A-Za-z0-9_-]*$/;
+
+function methodMatches(pattern: unknown, method: string): boolean {
+  if (pattern === undefined) return true;
+  if (typeof pattern !== "string" || !METHODS.has(pattern.toUpperCase())) return false;
+  return pattern.toUpperCase() === method.toUpperCase();
+}
+
+function personaMatches(pattern: unknown, persona: string): boolean {
+  if (pattern === undefined) return true;
+  if (typeof pattern === "string") return pattern === persona;
+  if (!Array.isArray(pattern) || pattern.length === 0) return false;
+  if (!pattern.every((item) => typeof item === "string" && item !== "")) return false;
+  return pattern.includes(persona);
+}
+
+function pathMatches(pattern: unknown, requestPath: string): boolean {
+  if (pattern === undefined) return true;
+  if (typeof pattern !== "string") return false;
+  const wanted = patternSegments(pattern);
+  if (wanted === null) return false;
+  const got = requestSegments(requestPath);
+  const wildcard = wanted.at(-1) === "*";
+  const fixed = wildcard ? wanted.slice(0, -1) : wanted;
+  if (wildcard ? got.length <= fixed.length : got.length !== fixed.length) return false;
+  for (let i = 0; i < fixed.length; i++) {
+    const want = fixed[i];
+    const have = got[i];
+    if (want === undefined || have === undefined || have === "") return false;
+    if (want.startsWith(":")) continue;
+    if (want !== have) return false;
+  }
+  return !wildcard || got.slice(fixed.length).every((segment) => segment !== "");
+}
+
+/** Same path language as the entry validator. `"/"` is the empty tail. Null means the pattern is not that language. */
+function patternSegments(path: string): string[] | null {
+  if (path === "/") return [];
+  if (path.includes("?") || path.includes("#") || path.includes("\\") || path.includes(" ")) return null;
+  const body = path.startsWith("/") ? path.slice(1) : path;
+  if (body === "" || body.endsWith("/")) return null;
+  const segments = body.split("/");
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (segment === undefined || segment === "") return null;
+    if (segment === "*") {
+      if (i !== segments.length - 1) return null;
+      continue;
+    }
+    if (segment.includes("*")) return null;
+    if (segment.startsWith(":")) {
+      if (!PARAM_SEGMENT.test(segment)) return null;
+      continue;
+    }
+    if (!LITERAL_SEGMENT.test(segment)) return null;
+  }
+  return segments;
+}
+
+function requestSegments(path: string): string[] {
+  const head = path.split("?")[0]?.split("#")[0] ?? "";
+  if (head === "" || head === "/") return [];
+  const body = head.startsWith("/") ? head.slice(1) : head;
+  return body.split("/");
+}

package/templates/golden-path/src/dev-personas.ts

@@ -5,22 +5,53 @@
 // works against a persona works against a real PPLE ID user in production.
 //
 // This whole module is compiled out of the deployed Worker: it is only reached
-// from the `import.meta.env.DEV` branch in src/auth.ts, which `vite build`
-// eliminates (docs/adr/0011). Nothing here can run in production.
+// from `import.meta.env.DEV` branches (the Persona bypass in src/auth.ts, the
+// offline Legal Identity answer, offline callService, offline readDataset,
+// and the registry dev wrapper), which
+// `vite build` eliminates (docs/adr/0011). Nothing here can run in production.
 //
 // The rule your app code must follow (docs/adr/0012): gate authorization on
 // `effective`, use `actor` for audit/display only, and honor
 // `effective.isDelegated`.
-import type { Identity } from "../shared/api";
+import type { Identity, KycStatus } from "../shared/api";
 
 export const DEFAULT_DEV_PERSONA = "hq-staff";
 
+/** An active member: verified through membership, not a national-ID check. */
+function memberKyc(verifiedAt: string): KycStatus {
+  return { status: "verified", verified: true, verifiedAt, source: "membership" };
+}
+
+/** `YYYY-MM-DD` from the same day as this Persona's KYC date. */
+function activeMembership(memberSince: string): Identity["actor"]["membership"] {
+  return { memberSince };
+}
+
+/** A person acting as themselves: effective.sub is their own actor sub. */
+function own(sub: string): Identity["effective"] {
+  return {
+    isDelegated: false,
+    sub,
+    activeRole: "",
+    eligibleRoles: [],
+    provinces: [],
+    extraRoles: [],
+  };
+}
+
 export const DEV_PERSONAS: Record<string, Identity> = {
   // Party HQ staff: every province in scope, no special capabilities. Default.
   "hq-staff": {
-    actor: { sub: "dev-hq-staff", name: "Local Dev (HQ)", mobile: "0800000001" },
+    actor: {
+      sub: "dev-hq-staff",
+      name: "Local Dev (HQ)",
+      mobile: "0800000001",
+      kyc: memberKyc("2024-01-01T00:00:00.000Z"),
+      membership: activeMembership("2024-01-01"),
+    },
     effective: {
       isDelegated: false,
+      sub: "dev-hq-staff",
       activeRole: "hq",
       eligibleRoles: ["hq"],
       provinces: ["all"],
@@ -34,9 +65,12 @@ export const DEV_PERSONAS: Record<string, Identity> = {
       sub: "dev-province-coordinator",
       name: "Local Dev (จังหวัด)",
       mobile: "0800000002",
+      kyc: memberKyc("2024-02-01T00:00:00.000Z"),
+      membership: activeMembership("2024-02-01"),
     },
     effective: {
       isDelegated: false,
+      sub: "dev-province-coordinator",
       activeRole: "province",
       eligibleRoles: ["province"],
       provinces: ["เชียงใหม่"],
@@ -50,9 +84,12 @@ export const DEV_PERSONAS: Record<string, Identity> = {
       sub: "dev-platform-admin",
       name: "Local Dev (Admin)",
       mobile: "0800000003",
+      kyc: memberKyc("2024-03-01T00:00:00.000Z"),
+      membership: activeMembership("2024-03-01"),
     },
     effective: {
       isDelegated: false,
+      sub: "dev-platform-admin",
       activeRole: "hq",
       eligibleRoles: ["hq"],
       provinces: ["all"],
@@ -60,18 +97,79 @@ export const DEV_PERSONAS: Record<string, Identity> = {
     },
   },
 
-  // A delegate acting for a supervisor: effective.* are the SUPERVISOR's role
-  // and scope, actor.* is the delegate human, and isDelegated is true.
+  // A delegate acting for the province coordinator: effective.* are the
+  // SUPERVISOR's role, scope, and sub. actor.* is the delegate human, and
+  // isDelegated is true. KYC Status is the delegate's own.
   delegate: {
-    actor: { sub: "dev-delegate", name: "Local Dev (ผู้รับมอบ)", mobile: "0800000004" },
+    actor: {
+      sub: "dev-delegate",
+      name: "Local Dev (ผู้รับมอบ)",
+      mobile: "0800000004",
+      kyc: memberKyc("2024-04-01T00:00:00.000Z"),
+      membership: activeMembership("2024-04-01"),
+    },
     effective: {
       isDelegated: true,
+      sub: "dev-province-coordinator",
       activeRole: "province",
       eligibleRoles: ["province"],
       provinces: ["เชียงใหม่"],
       extraRoles: [],
     },
   },
+
+  // No KYC Status at all.
+  unverified: {
+    actor: {
+      sub: "dev-unverified",
+      name: "Local Dev (ยังไม่ยืนยัน)",
+      mobile: "0800000005",
+      kyc: { status: "none", verified: false, verifiedAt: null, source: null },
+      membership: null,
+    },
+    effective: own("dev-unverified"),
+  },
+
+  // Submitted a national ID and waiting on review.
+  "kyc-pending": {
+    actor: {
+      sub: "dev-kyc-pending",
+      name: "Local Dev (รอตรวจ)",
+      mobile: "0800000006",
+      kyc: { status: "pending_review", verified: false, verifiedAt: null, source: null },
+      membership: null,
+    },
+    effective: own("dev-kyc-pending"),
+  },
+
+  // Verified with a national ID, and not a party member.
+  "kyc-verified-nonmember": {
+    actor: {
+      sub: "dev-kyc-verified",
+      name: "Local Dev (ยืนยันด้วยบัตร)",
+      mobile: "0800000007",
+      kyc: {
+        status: "verified",
+        verified: true,
+        verifiedAt: "2024-05-01T00:00:00.000Z",
+        source: "kyc",
+      },
+      membership: null,
+    },
+    effective: own("dev-kyc-verified"),
+  },
+
+  // A party member with no Role. member and internal differ offline (ADR-0028).
+  member: {
+    actor: {
+      sub: "dev-member",
+      name: "Local Dev (สมาชิก)",
+      mobile: "0800000008",
+      kyc: memberKyc("2024-06-01T00:00:00.000Z"),
+      membership: activeMembership("2024-06-01"),
+    },
+    effective: own("dev-member"),
+  },
 };
 
 /** Resolve the configured persona; an unknown name warns and falls back to the