@pplethai/cli 0.3.0 → 0.4.0

package/dist/commands/init.js

@@ -49,7 +49,32 @@ export async function init(deps, options) {
     if (await hasLocalChanges(deps, targetDir)) {
         await recordChanges(deps, targetDir, "เริ่มจากเทมเพลตมาตรฐานของ PPLE", access);
     }
-    report(deps, app, targetDir);
+    // Install dependencies and bring the local database up before handing over,
+    // so the Builder (or their agent) can `npm run dev` straight away. Done after
+    // the scaffold commit so node_modules/.wrangler stay out of it.
+    const setupOk = await setupWorkspace(deps, targetDir);
+    report(deps, app, targetDir, setupOk);
+}
+/**
+ * Install packages and apply local migrations. Non-fatal by design: the app
+ * already exists and is committed, so a flaky network or wrong Node version
+ * must not strand the Builder — we warn, and `report` prints the two commands
+ * to run by hand.
+ */
+async function setupWorkspace(deps, targetDir) {
+    deps.out.say("กำลังติดตั้งแพ็กเกจและเตรียมฐานข้อมูลบนเครื่อง…");
+    const steps = [
+        ["npm", ["install"]],
+        ["npm", ["run", "db:migrate:local"]],
+    ];
+    for (const [command, args] of steps) {
+        const result = await deps
+            .run(command, args, { cwd: targetDir })
+            .catch(() => null);
+        if (!result || result.code !== 0)
+            return false;
+    }
+    return true;
 }
 async function resolveName(deps, name) {
     if (await peekLink(deps)) {
@@ -116,7 +141,7 @@ async function isAlreadyBuilt(targetDir) {
         .then(() => true)
         .catch(() => false);
 }
-function report(deps, app, targetDir) {
+function report(deps, app, targetDir, setupOk) {
     const folder = path.basename(targetDir);
     deps.out.say();
     deps.out.say(`"${app.name}" พร้อมให้ทำงานแล้วใน ${folder}/`);
@@ -124,7 +149,11 @@ function report(deps, app, targetDir) {
     deps.out.say();
     deps.out.say("ขั้นต่อไป:");
     deps.out.say(`  cd ${folder}`);
-    deps.out.say("  npm install");
+    if (!setupOk) {
+        // Auto-setup didn't finish — the Builder runs these once by hand.
+        deps.out.say("  npm install");
+        deps.out.say("  npm run db:migrate:local");
+    }
     deps.out.say("  npm run dev        # ดูผลบนเครื่องนี้");
     deps.out.say("  pple deploy        # นำขึ้นใช้งานจริง");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pplethai/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "repository": {
     "type": "git",

package/skills/pple-platform/references/pple-id-auth.md

@@ -40,12 +40,20 @@ import { PPLEMiniApp } from "@pplethai/pple-today-miniapp-sdk";
 // Production (Today or browser): sdk.init() → getAccessToken() → { kind: "signed-in" }
 ```
 
-OAuth client values (`VITE_OAUTH_URL`, `VITE_OAUTH_CLIENT_ID`,
-`VITE_OAUTH_REDIRECT_URI`) are provisioned per app and injected at build
-time — Builders do not register clients by hand. The redirect URI defaults
-to the app's own origin, which matches the mini-app URL the platform
-registers as an allowed redirect on that OAuth client
-(`docs/integration/today-sso-changes.md` §5).
+OAuth client values are provisioned per app — Builders do not register
+clients by hand. The SPA reads them at **build time** via Vite
+(`VITE_OAUTH_URL`, `VITE_OAUTH_CLIENT_ID`), so the platform bakes them into
+the `env:` block of the deploy workflow it owns in each app repo
+(`.github/workflows/deploy.yml`), where `npm run build` can see them. Because
+that workflow is reconciled on every deploy (ADR-0004), an app self-heals
+these values on its next deploy. `VITE_OAUTH_REDIRECT_URI` is not baked in:
+it defaults to the app's own origin (`window.location.origin`), which matches
+the mini-app URL the platform registers as an allowed redirect on that OAuth
+client (`docs/integration/today-sso-changes.md` §5).
+
+A build that runs without `VITE_OAUTH_URL` set produces a bundle with an
+empty `oauthUrl`; the template's `bootstrap()` catches that and shows an
+"app is misconfigured" error instead of the raw `oidc-client-ts` failure.
 
 ## Worker: validating the token
 

package/templates/golden-path/.dev.vars.example

@@ -1,17 +1,14 @@
-# Local development configuration. Copy this file to `.dev.vars` (which is
-# gitignored) and adjust. `wrangler dev` and `vite dev` load `.dev.vars`
-# automatically.
+# Optional local-development overrides. `npm run dev` works with NO `.dev.vars`
+# at all — copy this to `.dev.vars` (gitignored) only if you want one of the
+# settings below. `vite dev` and `wrangler dev` load `.dev.vars` automatically.
 
-# Turns on the local auth bypass. When set, any request whose bearer token
-# equals this value is accepted as a fake signed-in user, so you can develop
-# in a plain browser without PPLE Today. The React app uses this token
-# automatically during `vite dev`.
-#
-# NEVER set DEV_AUTH in production — the platform never provisions it, and the
-# Worker treats its absence as "real auth only".
-DEV_AUTH="dev-token"
+# Which mock identity to sign in as locally. Defaults to "hq-staff".
+# Built-in personas: hq-staff, province-coordinator, platform-admin, delegate
+# (add your own in src/dev-personas.ts). Set to "none" to turn the bypass off
+# and exercise the real PPLE ID sign-in path locally.
+# DEV_PERSONA="province-coordinator"
 
-# Optional: exercise the notification helper locally. These are normally
-# injected by the platform at deploy time.
+# Exercise the notification helper locally. These are normally injected by the
+# platform at deploy time.
 # NOTIFY_API_BASE="https://today.peoplesparty.or.th"
 # NOTIFY_API_KEY="your-app-notification-key"

package/templates/golden-path/CLAUDE.md

@@ -27,14 +27,29 @@ which attach the PPLE ID bearer token. Same origin, so paths are relative
 
 ## How auth works
 
-- Inside PPLE Today, the mini-app SDK (`web/pple.ts`) captures the access
-  token from the launch URL. The Worker validates it against PPLE ID
-  (`src/auth.ts`).
+Every `/api/*` request carries a PPLE ID bearer token; the Worker resolves it
+to an `Identity` (`src/auth.ts`, shape in `shared/api.ts`) with two faces:
+
+- **`actor`** — the real human clicking (`sub`, `name`, `mobile`). For audit
+  and display only.
+- **`effective`** — what they may do: `activeRole`, `eligibleRoles`,
+  `provinces` (scope), `extraRoles` (capabilities like `platform:admin`).
+  **Gate every authorization decision on `effective`, never on `actor`.** Under
+  delegation these are the *supervisor's* values and `effective.isDelegated`
+  is true.
+
+Where the token comes from:
+
+- Inside PPLE Today, the mini-app SDK (`web/pple.ts`) captures the access token
+  from the launch URL; the Worker validates it against PPLE ID.
 - In a plain browser, the same SDK runs the PPLE ID OIDC login (redirect /
-  callback) and returns an access token — do not add a custom sign-in page
-  or resurrect a NotInApp guard.
-- Locally, `DEV_AUTH` in `.dev.vars` bypasses PPLE Today. **Never** set
-  `DEV_AUTH` in production; the platform never provisions it.
+  callback) — do not add a custom sign-in page or resurrect a NotInApp guard.
+- Locally (`npm run dev`) there is no login: the Worker signs you in as a mock
+  **persona** (`DEV_PERSONA`, default `hq-staff` — see `src/dev-personas.ts`).
+  To test a province-scoped feature use `DEV_PERSONA=province-coordinator`;
+  for delegation use `delegate`; for admin-only paths use `platform-admin`.
+  This bypass is gated on `import.meta.env.DEV`, so it is compiled out of the
+  deployed Worker — there is nothing to set or unset for production.
 
 ## Conventions
 

package/templates/golden-path/README.md

@@ -14,7 +14,7 @@ what you want to your AI coding agent and edit the demo cards. See
 | Capability | Where | Demo |
 | ---------- | ----- | ---- |
 | **API** | Hono Worker, `src/index.ts` | routes under `/api/*` |
-| **Identity** | `src/auth.ts` + `web/pple.ts` | validates PPLE ID tokens; browser PPLE ID login; dev bypass |
+| **Identity** | `src/auth.ts` + `web/pple.ts` | validates PPLE ID tokens; browser PPLE ID login; local mock personas (`src/dev-personas.ts`) |
 | **Database** | D1, `src/db.ts` + `migrations/` | the Notes card |
 | **Files** | R2, `src/files.ts` | the Files card |
 | **Notifications** | `src/notify.ts` | the Notify card (audience-bound; optional `linkPath`) |
@@ -27,15 +27,20 @@ everything else — same origin, no CORS.
 
 ```bash
 npm install
-cp .dev.vars.example .dev.vars   # local auth bypass
-npm run db:migrate:local         # set up the local database
-npm run dev                      # http://localhost:5173
+npm run dev        # http://localhost:5173
 ```
 
-In local dev you're signed in automatically as a fake user (the `DEV_AUTH`
-bypass), so you can build without PPLE Today. Opened inside PPLE Today, the
-mini-app SDK signs the real user in from the launch URL; opened in a plain
-browser after deploy, the same SDK runs the PPLE ID login.
+`npm run dev` applies your local database migrations, then starts the
+full-stack dev server. No config files, no PPLE Today, no OAuth: you're signed
+in automatically as a mock **persona** (`hq-staff` by default). To develop as
+someone else, set `DEV_PERSONA` in `.dev.vars` (see `.dev.vars.example`) to
+`hq-staff`, `province-coordinator`, `platform-admin`, or `delegate` — or add
+your own in `src/dev-personas.ts`.
+
+Opened inside PPLE Today, the mini-app SDK signs the real user in from the
+launch URL; opened in a plain browser after deploy, the same SDK runs the
+PPLE ID login. (`pple init` runs `npm install` and the first migration for
+you, so a freshly created app is ready to `npm run dev` straight away.)
 
 ## Everyday commands
 

package/templates/golden-path/package.json

@@ -4,6 +4,7 @@
   "type": "module",
   "//": "Golden-path template for a PPLE Platform Builder App. Rename this to your app slug. Everything runs on Cloudflare: a Hono Worker (API), D1 (database), R2 (files); the UI is a React SPA built with the People's Party design system.",
   "scripts": {
+    "predev": "wrangler d1 migrations apply DB --local",
     "dev": "vite dev",
     "build": "vite build",
     "preview": "vite preview",

package/templates/golden-path/shared/api.ts

@@ -4,12 +4,45 @@
 // the inferred TypeScript types.
 import { z } from "zod";
 
-/** The signed-in user, as the Worker resolves it from the PPLE ID token. */
-export const MeSchema = z.object({
+/**
+ * The signed-in caller, as the Worker resolves it from the PPLE ID token
+ * (src/auth.ts). Two faces:
+ *
+ * - `actor` — the real human clicking. Use for audit and display only.
+ * - `effective` — what they may do. Gate every authorization decision on this,
+ *   never on `actor`. Under Delegation these are the supervisor's values and
+ *   `isDelegated` is true. See docs/adr/0012 and CONTEXT.md.
+ */
+export const ActorSchema = z.object({
   sub: z.string(),
   name: z.string().nullable(),
+  /** Thai mobile number, the join key across PPLE systems. May be null. */
+  mobile: z.string().nullable(),
+});
+export type Actor = z.infer<typeof ActorSchema>;
+
+export const EffectiveSchema = z.object({
+  /** True ⇒ the values below are borrowed from a supervisor (see Actor). */
+  isDelegated: z.boolean(),
+  /** The Role in play now (one of `eligibleRoles`), e.g. "hq", "province". */
+  activeRole: z.string(),
+  eligibleRoles: z.array(z.string()),
+  /** Geographic scope, or ["all"]. */
+  provinces: z.array(z.string()),
+  /** Capabilities, e.g. "platform:admin", "exco", "province_co". */
+  extraRoles: z.array(z.string()),
+});
+export type Effective = z.infer<typeof EffectiveSchema>;
+
+export const IdentitySchema = z.object({
+  actor: ActorSchema,
+  effective: EffectiveSchema,
 });
-export type Me = z.infer<typeof MeSchema>;
+export type Identity = z.infer<typeof IdentitySchema>;
+
+/** What `GET /api/me` returns: the caller's Identity. */
+export const MeSchema = IdentitySchema;
+export type Me = Identity;
 
 /** A row in the example `notes` table (the D1 read/write demo). */
 export const NoteSchema = z.object({

package/templates/golden-path/src/auth.ts

@@ -5,11 +5,16 @@
 // The Worker validates that token server-side against the PPLE ID userinfo
 // endpoint — the same seam the platform's own services use. There is no local
 // session or cookie: each request carries the token.
+//
+// The token resolves to an Identity with two faces (see shared/api.ts):
+//   • actor     — the real human clicking (audit/display only)
+//   • effective — what they may do (gate authorization on this)
+// Under Delegation, effective.* are the supervisor's and effective.isDelegated
+// is true, while actor stays the delegate. See docs/adr/0012.
+import type { Identity } from "../shared/api";
+import { resolveDevPersona } from "./dev-personas";
 
-export interface Identity {
-  sub: string;
-  name: string | null;
-}
+export type { Identity };
 
 export type AuthResult =
   | { ok: true; identity: Identity }
@@ -17,8 +22,12 @@ export type AuthResult =
 
 interface AuthEnv {
   SSO_BASE_URL: string;
-  /** Local-only bypass token; unset in production. See .dev.vars.example. */
-  DEV_AUTH?: string;
+  /**
+   * Local development only: which mock persona to sign in as (see
+   * src/dev-personas.ts). Unset means the default persona; "none" turns the
+   * bypass off so you can exercise the real PPLE ID path locally.
+   */
+  DEV_PERSONA?: string;
 }
 
 /**
@@ -31,23 +40,99 @@ export async function authenticate(
   token: string,
   fetchImpl: typeof fetch = globalThis.fetch.bind(globalThis),
 ): Promise<AuthResult> {
-  // Local development bypass: accept a fake user when the request carries the
-  // configured DEV_AUTH token. Never active in production, because the
-  // platform never provisions DEV_AUTH.
-  if (env.DEV_AUTH && token === env.DEV_AUTH) {
-    return { ok: true, identity: { sub: "dev-user", name: "Local Dev" } };
+  // Local development bypass. `import.meta.env.DEV` is true under `vite dev`
+  // (and tests) and statically `false` in `vite build`, so this whole block is
+  // dead-code-eliminated from the deployed Worker — the bypass cannot exist in
+  // production (docs/adr/0011). No token, no `.dev.vars`, no PPLE Today needed;
+  // set DEV_PERSONA="none" to fall through to the real path instead.
+  if (import.meta.env.DEV && env.DEV_PERSONA !== "none") {
+    return { ok: true, identity: resolveDevPersona(env.DEV_PERSONA) };
   }
 
+  if (!token) return { ok: false, status: 401 };
+
   const res = await fetchImpl(`${env.SSO_BASE_URL}/oidc/v1/userinfo`, {
     headers: { authorization: `Bearer ${token}` },
   });
   if (res.status === 401 || res.status === 403) return { ok: false, status: 401 };
   if (!res.ok) return { ok: false, status: 502 };
 
-  const body = (await res.json().catch(() => ({}))) as {
-    sub?: string;
-    name?: string;
-  };
+  const body = (await res.json().catch(() => ({}))) as RawUserInfo;
   if (!body.sub) return { ok: false, status: 502 };
-  return { ok: true, identity: { sub: body.sub, name: body.name ?? null } };
+  return { ok: true, identity: toIdentity(body) };
+}
+
+// --- Parsing the PPLE ID userinfo response -------------------------------
+//
+// Organization members carry an `ad` block. Its `user` is the person whose
+// authority is in effect (a delegate is already resolved to their supervisor
+// here); `actualPpleUser` is the real human who logged in. Every level is
+// optional, so a missing or oddly-shaped payload yields empty values rather
+// than throwing. See pple-sso's lib/ad/legacy-context.ts for the full shape.
+
+interface RawPerson {
+  id?: number;
+  role?: string;
+  mobile?: string;
+  metadata?: { ad?: { extra_roles?: unknown; is_province_coordinator?: unknown } };
+}
+
+interface RawAd {
+  user?: RawPerson;
+  actualPpleUser?: RawPerson;
+  activeRole?: string;
+  eligibleRoles?: unknown;
+  eligibleProvinces?: unknown;
+}
+
+interface RawUserInfo {
+  sub?: string;
+  name?: string;
+  ad?: RawAd;
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((v): v is string => typeof v === "string")
+    : [];
+}
+
+/** Extra-roles nested under a person's AD metadata, plus the synthetic
+ * `province_co` a province coordinator carries. */
+function extraRolesOf(person: RawPerson | undefined): string[] {
+  const ad = person?.metadata?.ad;
+  const roles = stringArray(ad?.extra_roles);
+  if (person?.role === "province" && ad?.is_province_coordinator === true) {
+    roles.push("province_co");
+  }
+  return roles;
+}
+
+function toIdentity(body: RawUserInfo): Identity {
+  const ad = body.ad;
+  const effectivePerson = ad?.user;
+  // When nobody is delegating, `actualPpleUser` mirrors `user`.
+  const actualPerson = ad?.actualPpleUser ?? effectivePerson;
+  const activeRole = ad?.activeRole ?? effectivePerson?.role ?? "";
+  const eligibleRoles = stringArray(ad?.eligibleRoles);
+
+  return {
+    actor: {
+      // Top-level `sub` is the OIDC subject of the human who logged in.
+      sub: body.sub as string,
+      name: body.name ?? null,
+      mobile: actualPerson?.mobile ?? null,
+    },
+    effective: {
+      isDelegated:
+        effectivePerson?.id !== undefined &&
+        actualPerson?.id !== undefined &&
+        effectivePerson.id !== actualPerson.id,
+      activeRole,
+      eligibleRoles:
+        eligibleRoles.length > 0 ? eligibleRoles : activeRole ? [activeRole] : [],
+      provinces: stringArray(ad?.eligibleProvinces),
+      extraRoles: extraRolesOf(effectivePerson),
+    },
+  };
 }

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

@@ -0,0 +1,88 @@
+// Mock identities for local development (`npm run dev`).
+//
+// Pick one with DEV_PERSONA in .dev.vars (default "hq-staff"); add your own by
+// appending to DEV_PERSONAS. Each persona is a real Identity shape, so what
+// 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.
+//
+// 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";
+
+export const DEFAULT_DEV_PERSONA = "hq-staff";
+
+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" },
+    effective: {
+      isDelegated: false,
+      activeRole: "hq",
+      eligibleRoles: ["hq"],
+      provinces: ["all"],
+      extraRoles: [],
+    },
+  },
+
+  // A province coordinator: scoped to a single province.
+  "province-coordinator": {
+    actor: {
+      sub: "dev-province-coordinator",
+      name: "Local Dev (จังหวัด)",
+      mobile: "0800000002",
+    },
+    effective: {
+      isDelegated: false,
+      activeRole: "province",
+      eligibleRoles: ["province"],
+      provinces: ["เชียงใหม่"],
+      extraRoles: ["province_co"],
+    },
+  },
+
+  // Carries the platform:admin extra-role (may work the platform admin queue).
+  "platform-admin": {
+    actor: {
+      sub: "dev-platform-admin",
+      name: "Local Dev (Admin)",
+      mobile: "0800000003",
+    },
+    effective: {
+      isDelegated: false,
+      activeRole: "hq",
+      eligibleRoles: ["hq"],
+      provinces: ["all"],
+      extraRoles: ["platform:admin"],
+    },
+  },
+
+  // A delegate acting for a supervisor: effective.* are the SUPERVISOR's role
+  // and scope, actor.* is the delegate human, and isDelegated is true.
+  delegate: {
+    actor: { sub: "dev-delegate", name: "Local Dev (ผู้รับมอบ)", mobile: "0800000004" },
+    effective: {
+      isDelegated: true,
+      activeRole: "province",
+      eligibleRoles: ["province"],
+      provinces: ["เชียงใหม่"],
+      extraRoles: [],
+    },
+  },
+};
+
+/** Resolve the configured persona; an unknown name warns and falls back to the
+ * default so a typo never breaks local dev. */
+export function resolveDevPersona(name: string | undefined): Identity {
+  const key = name?.trim() || DEFAULT_DEV_PERSONA;
+  const persona = DEV_PERSONAS[key];
+  if (persona) return persona;
+  console.warn(
+    `Unknown DEV_PERSONA "${key}"; using "${DEFAULT_DEV_PERSONA}". ` +
+      `Valid personas: ${Object.keys(DEV_PERSONAS).join(", ")}.`,
+  );
+  return DEV_PERSONAS[DEFAULT_DEV_PERSONA] as Identity;
+}

package/templates/golden-path/src/env.ts

@@ -14,6 +14,8 @@ export interface Env {
   NOTIFY_API_BASE: string;
   NOTIFY_API_KEY?: string;
 
-  // Local development auth bypass. Never set in production.
-  DEV_AUTH?: string;
+  // Local development only: which mock persona to sign in as (src/dev-personas.ts).
+  // Unset means the default persona; "none" turns the bypass off. Never set in
+  // production — the dev bypass is compiled out of the deployed Worker anyway.
+  DEV_PERSONA?: string;
 }

package/templates/golden-path/src/index.ts

@@ -4,8 +4,9 @@
 // so each concern is easy to find and test.
 import { Hono } from "hono";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { Identity } from "../shared/api";
 import { CreateNoteSchema, NotificationSchema } from "../shared/api";
-import { authenticate, type Identity } from "./auth";
+import { authenticate } from "./auth";
 import { addNote, listNotes } from "./db";
 import type { Env } from "./env";
 import { getFile, listFiles, putFile } from "./files";
@@ -29,12 +30,13 @@ export function createApp(overrides: AppOverrides = {}) {
   // Liveness check — no auth, so uptime monitors and CI smoke tests can hit it.
   app.get("/health", (c) => c.json({ ok: true }));
 
-  // Everything below requires a valid PPLE ID token.
+  // Everything below requires a valid PPLE ID token. authenticate() owns the
+  // whole decision — including the local dev-persona bypass — so a missing
+  // token is just one of the ways it can say 401.
   app.use("*", async (c, next) => {
     const token = (c.req.header("authorization") ?? "")
       .replace(/^Bearer\s+/i, "")
       .trim();
-    if (!token) return c.json({ error: "not_authenticated" }, 401);
     const result = await authenticate(c.env, token, fetchImpl);
     if (!result.ok) {
       return c.json(
@@ -46,10 +48,9 @@ export function createApp(overrides: AppOverrides = {}) {
     await next();
   });
 
-  app.get("/me", (c) => {
-    const { sub, name } = c.get("identity");
-    return c.json({ sub, name });
-  });
+  // The signed-in caller. `actor` is who is clicking; `effective` is what they
+  // may do — gate authorization on `effective`, never on `actor`.
+  app.get("/me", (c) => c.json(c.get("identity")));
 
   // --- D1 demo: a shared notes list ---
   app.get("/notes", async (c) => c.json({ notes: await listNotes(c.env.DB) }));

package/templates/golden-path/src/vite-env.d.ts

@@ -0,0 +1,14 @@
+// The Worker is built by Vite (via @cloudflare/vite-plugin), so `import.meta.env`
+// is available here just as it is in the browser bundle. Vite replaces
+// `import.meta.env.DEV` with a literal: `true` under `vite dev` and `vitest`,
+// `false` in `vite build` — which is what lets the local auth bypass in
+// src/auth.ts be dead-code-eliminated from the deployed Worker.
+interface ImportMetaEnv {
+  readonly DEV: boolean;
+  readonly PROD: boolean;
+  readonly MODE: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/templates/golden-path/test/harness.ts

@@ -2,7 +2,10 @@ import { env } from "cloudflare:test";
 import type { Env } from "../src/env";
 import { createApp } from "../src/index";
 
-export const DEV_TOKEN = "dev-token";
+// A placeholder bearer. In tests `import.meta.env.DEV` is true, so the Worker
+// signs in as the default persona and ignores the token — the value only
+// matters on the real PPLE ID path, where tests pass an explicit one.
+export const DEV_TOKEN = "dev";
 
 export interface Fakes {
   /** Handles GET {SSO_BASE_URL}/oidc/v1/userinfo */
@@ -39,7 +42,8 @@ export function makeHarness(fakes: Fakes = {}, envOverrides: Partial<Env> = {})
     ...env,
     SSO_BASE_URL: "https://sso.test",
     NOTIFY_API_BASE: "",
-    DEV_AUTH: DEV_TOKEN,
+    // No DEV_PERSONA ⇒ the default persona. Pass { DEV_PERSONA: "none" } to
+    // exercise the real PPLE ID path instead.
     ...envOverrides,
   };
 

package/templates/golden-path/test/smoke.test.ts

@@ -11,38 +11,121 @@ describe("health", () => {
   });
 });
 
-describe("authentication", () => {
-  it("rejects requests without a token", async () => {
+describe("local dev personas", () => {
+  it("signs in as the default persona (hq-staff) with no config", async () => {
     const h = makeHarness();
-    const res = await h.request("/api/me", {}, null);
-    expect(res.status).toBe(401);
-    expect(await res.json()).toMatchObject({ error: "not_authenticated" });
+    const res = await h.request("/api/me");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({
+      actor: { sub: "dev-hq-staff" },
+      effective: { activeRole: "hq", provinces: ["all"], isDelegated: false },
+    });
   });
 
-  it("accepts the dev-bypass token locally", async () => {
-    const h = makeHarness();
-    const res = await h.request("/api/me");
+  it("switches persona via DEV_PERSONA, even without a token", async () => {
+    const h = makeHarness({}, { DEV_PERSONA: "province-coordinator" });
+    const res = await h.request("/api/me", {}, null);
     expect(res.status).toBe(200);
-    expect(await res.json()).toMatchObject({ sub: "dev-user" });
+    expect(await res.json()).toMatchObject({
+      effective: { activeRole: "province", provinces: ["เชียงใหม่"], extraRoles: ["province_co"] },
+    });
+  });
+
+  it("exposes a delegate persona as effective≠actor", async () => {
+    const h = makeHarness({}, { DEV_PERSONA: "delegate" });
+    const { actor, effective } = await (await h.request("/api/me")).json<{
+      actor: { sub: string };
+      effective: { isDelegated: boolean };
+    }>();
+    expect(actor.sub).toBe("dev-delegate");
+    expect(effective.isDelegated).toBe(true);
+  });
+
+  it("falls back to the default persona on an unknown DEV_PERSONA", async () => {
+    const h = makeHarness({}, { DEV_PERSONA: "does-not-exist" });
+    expect(await (await h.request("/api/me")).json()).toMatchObject({
+      actor: { sub: "dev-hq-staff" },
+    });
+  });
+});
+
+describe("real PPLE ID authentication (DEV_PERSONA=none)", () => {
+  it("rejects requests without a token", async () => {
+    const h = makeHarness({}, { DEV_PERSONA: "none" });
+    const res = await h.request("/api/me", {}, null);
+    expect(res.status).toBe(401);
+    expect(await res.json()).toMatchObject({ error: "not_authenticated" });
   });
 
   it("validates real tokens against PPLE ID userinfo", async () => {
-    // No dev bypass here; an unknown token must be checked with PPLE ID.
     const h = makeHarness(
       { sso: () => Response.json({ error: "invalid_token" }, { status: 401 }) },
-      { DEV_AUTH: undefined },
+      { DEV_PERSONA: "none" },
     );
     const res = await h.request("/api/me", {}, "some-real-looking-token");
     expect(res.status).toBe(401);
   });
 
-  it("resolves identity from a valid PPLE ID token", async () => {
+  it("resolves an effective/actor Identity from a valid token", async () => {
     const h = makeHarness(
-      { sso: () => Response.json({ sub: "u-42", name: "Somchai" }) },
-      { DEV_AUTH: undefined },
+      {
+        sso: () =>
+          Response.json({
+            sub: "u-42",
+            name: "Somchai",
+            ad: {
+              user: {
+                id: 7,
+                role: "hq",
+                mobile: "0810000007",
+                metadata: { ad: { extra_roles: ["exco"] } },
+              },
+              actualPpleUser: { id: 7, role: "hq", mobile: "0810000007" },
+              activeRole: "hq",
+              eligibleRoles: ["hq"],
+              eligibleProvinces: ["all"],
+            },
+          }),
+      },
+      { DEV_PERSONA: "none" },
     );
     const res = await h.request("/api/me", {}, "valid-token");
-    expect(await res.json()).toMatchObject({ sub: "u-42", name: "Somchai" });
+    expect(await res.json()).toMatchObject({
+      actor: { sub: "u-42", name: "Somchai", mobile: "0810000007" },
+      effective: {
+        isDelegated: false,
+        activeRole: "hq",
+        provinces: ["all"],
+        extraRoles: ["exco"],
+      },
+    });
+  });
+
+  it("keeps actor (the delegate) distinct from effective (the supervisor)", async () => {
+    const h = makeHarness(
+      {
+        sso: () =>
+          Response.json({
+            sub: "u-delegate",
+            name: "Nok",
+            ad: {
+              // The supervisor whose authority is in effect…
+              user: { id: 9, role: "province", mobile: "0810000009" },
+              // …while the real human acting is the delegate.
+              actualPpleUser: { id: 14, role: "delegate", mobile: "0810000014" },
+              activeRole: "province",
+              eligibleRoles: ["province"],
+              eligibleProvinces: ["เชียงใหม่"],
+            },
+          }),
+      },
+      { DEV_PERSONA: "none" },
+    );
+    const res = await h.request("/api/me", {}, "valid-token");
+    expect(await res.json()).toMatchObject({
+      actor: { sub: "u-delegate", mobile: "0810000014" },
+      effective: { isDelegated: true, activeRole: "province", provinces: ["เชียงใหม่"] },
+    });
   });
 });
 

package/templates/golden-path/web/App.tsx

@@ -42,7 +42,7 @@ export function App() {
       <header className="appbar">
         <Logo className="appbar__logo" title="People's Party" />
         <span className="appbar__title">PPLE App</span>
-        {me && <Badge>{me.name ?? me.sub}</Badge>}
+        {me && <Badge>{me.actor.name ?? me.actor.sub}</Badge>}
       </header>
 
       <div className="stack">

package/templates/golden-path/web/main.tsx

@@ -35,8 +35,8 @@ function ErrorScreen({ message }: { message: string }) {
 
 const root = createRoot(document.getElementById("root")!);
 
-// Establish the session (PPLE Today token, browser PPLE ID login, or local
-// DEV_AUTH) before rendering, so the first paint is the right screen.
+// Establish the session (PPLE Today token, browser PPLE ID login, or a local
+// dev persona) before rendering, so the first paint is the right screen.
 bootstrap().then((result) => {
   root.render(
     <StrictMode>

package/templates/golden-path/web/pple.ts

@@ -1,16 +1,19 @@
 // The single place the app talks to PPLE Today and to its own API.
 //
 // Three ways the app can start:
-//   1. Local dev (`vite dev`) — bypass PPLE Today, use the DEV_AUTH token so
-//      the Worker accepts you as a fake user.
+//   1. Local dev (`vite dev`) — no login. The Worker signs you in as a mock
+//      persona (DEV_PERSONA); we just attach a placeholder bearer it ignores.
 //   2. Inside PPLE Today — the SDK captures the access token from the launch
 //      URL; we attach it to every API call.
 //   3. A plain browser — the same SDK runs the PPLE ID OIDC sign-in (redirect
 //      / callback) and hands back an access token.
 import { PPLEMiniApp } from "@pplethai/pple-today-miniapp-sdk";
 
-// Provisioned per app, injected at build time. Needed for the SDK in both
-// PPLE Today and the browser (browser login uses the OIDC redirect flow).
+// Provisioned per app and baked into this bundle at build time by the
+// platform deploy workflow's env (VITE_OAUTH_URL / VITE_OAUTH_CLIENT_ID).
+// Needed for the SDK in both PPLE Today and the browser (browser login uses
+// the OIDC redirect flow). Empty here means the build var was missing —
+// bootstrap() below turns that into a legible error.
 const OAUTH_URL = import.meta.env.VITE_OAUTH_URL ?? "";
 const OAUTH_CLIENT_ID = import.meta.env.VITE_OAUTH_CLIENT_ID ?? "";
 // Must match a redirect URI on the app's PPLE ID OAuth client. Provisioning
@@ -18,8 +21,9 @@ const OAUTH_CLIENT_ID = import.meta.env.VITE_OAUTH_CLIENT_ID ?? "";
 const OAUTH_REDIRECT_URI =
   import.meta.env.VITE_OAUTH_REDIRECT_URI ?? window.location.origin;
 
-// Must match DEV_AUTH in .dev.vars so the Worker's dev bypass accepts it.
-const DEV_TOKEN = "dev-token";
+// In local dev the Worker ignores the token entirely (it signs you in as a
+// mock persona), but api() still needs a non-null bearer to attach.
+const DEV_PLACEHOLDER_TOKEN = "dev";
 
 export type Bootstrap =
   | { kind: "signed-in" }
@@ -31,10 +35,23 @@ let token: string | null = null;
 export async function bootstrap(): Promise<Bootstrap> {
   try {
     if (import.meta.env.DEV) {
-      token = DEV_TOKEN;
+      token = DEV_PLACEHOLDER_TOKEN;
       return { kind: "signed-in" };
     }
 
+    // The OAuth config is baked in at build time by the platform deploy
+    // workflow (VITE_OAUTH_URL / VITE_OAUTH_CLIENT_ID). If it's missing the
+    // SDK throws a bare "No authority or metadataUrl configured on settings"
+    // from oidc-client-ts — turn that into something a Builder can act on
+    // instead of a stack trace they can't read (issue #115).
+    if (!OAUTH_URL || !OAUTH_CLIENT_ID) {
+      return {
+        kind: "error",
+        message:
+          "This app is misconfigured: its PPLE ID sign-in settings were not set when it was built. Redeploy the app from the platform to fix it.",
+      };
+    }
+
     const sdk = new PPLEMiniApp({
       oauthUrl: OAUTH_URL,
       oauthClientId: OAUTH_CLIENT_ID,