@pplethai/cli 0.1.0

package/templates/golden-path/tsconfig.worker.json

@@ -0,0 +1,21 @@
+// TypeScript config for the Worker (src/) and its tests (test/). Uses the
+// Cloudflare Workers runtime types, not the browser DOM.
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "lib": ["es2022"],
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "types": [
+      "@cloudflare/workers-types",
+      "@cloudflare/vitest-pool-workers/types"
+    ],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src", "test", "shared"]
+}

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

@@ -0,0 +1,29 @@
+import { fileURLToPath } from "node:url";
+import { cloudflare } from "@cloudflare/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+// 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()],
+  resolve: {
+    alias: [
+      // @pplethai/components ships a "development" export condition pointing at
+      // its (unpublished) source, which Vite would otherwise pick during dev
+      // and fail to resolve. Pin the bare import to the built entry; the
+      // /styles.css and /form subpaths still resolve normally.
+      {
+        find: /^@pplethai\/components$/,
+        replacement: fileURLToPath(
+          new URL(
+            "./node_modules/@pplethai/components/dist/index.js",
+            import.meta.url,
+          ),
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,26 @@
+import path from "node:path";
+import {
+  cloudflareTest,
+  readD1Migrations,
+} from "@cloudflare/vitest-pool-workers";
+import { defineConfig } from "vitest/config";
+
+// 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
+// migrations are applied to the test database in test/apply-migrations.ts.
+export default defineConfig(async () => {
+  const migrations = await readD1Migrations(path.join(__dirname, "migrations"));
+  return {
+    plugins: [
+      cloudflareTest({
+        wrangler: { configPath: "./wrangler.jsonc" },
+        miniflare: {
+          bindings: { TEST_MIGRATIONS: migrations },
+        },
+      }),
+    ],
+    test: {
+      setupFiles: ["./test/apply-migrations.ts"],
+    },
+  };
+});

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

@@ -0,0 +1,250 @@
+import {
+  Badge,
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Input,
+  Logo,
+  Spinner,
+  Textarea,
+  showToast,
+} from "@pplethai/components";
+import { useEffect, useRef, useState } from "react";
+import type { Me, Note, UploadedFile } from "../shared/api";
+import { api, apiJson } from "./pple";
+
+function bytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function message(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+export function App() {
+  const [me, setMe] = useState<Me | null>(null);
+
+  useEffect(() => {
+    apiJson<Me>("/api/me").then(setMe).catch((e) => showToast({
+      title: "Could not load your profile",
+      description: message(e),
+      variant: "error",
+    }));
+  }, []);
+
+  return (
+    <main className="screen">
+      <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>}
+      </header>
+
+      <div className="stack">
+        <p className="muted">
+          This is the golden-path template. Each card below exercises one
+          platform capability. Replace them with your own app.
+        </p>
+        <NotesCard />
+        <FilesCard />
+        <NotifyCard />
+      </div>
+    </main>
+  );
+}
+
+// --- D1: a shared notes list ---------------------------------------------
+function NotesCard() {
+  const [notes, setNotes] = useState<Note[] | null>(null);
+  const [body, setBody] = useState("");
+  const [saving, setSaving] = useState(false);
+
+  const load = () =>
+    apiJson<{ notes: Note[] }>("/api/notes")
+      .then((r) => setNotes(r.notes))
+      .catch((e) => showToast({ title: "Could not load notes", description: message(e), variant: "error" }));
+
+  useEffect(() => void load(), []);
+
+  async function add() {
+    if (!body.trim()) return;
+    setSaving(true);
+    try {
+      await apiJson<Note>("/api/notes", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ body }),
+      });
+      setBody("");
+      await load();
+    } catch (e) {
+      showToast({ title: "Could not save note", description: message(e), variant: "error" });
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <Card className="card">
+      <CardHeader>
+        <CardTitle>Notes</CardTitle>
+        <CardDescription>Reads and writes your app's D1 database.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <div className="stack">
+          <div className="row">
+            <Input
+              value={body}
+              placeholder="Write a note…"
+              onChange={(e) => setBody(e.target.value)}
+              onKeyDown={(e) => e.key === "Enter" && add()}
+            />
+            <Button onClick={add} disabled={saving || !body.trim()}>
+              {saving ? <Spinner /> : "Add"}
+            </Button>
+          </div>
+          {notes === null ? (
+            <Spinner />
+          ) : notes.length === 0 ? (
+            <p className="muted">No notes yet.</p>
+          ) : (
+            <ul className="list">
+              {notes.map((n) => (
+                <li key={n.id} className="list__item">
+                  <span>{n.body}</span>
+                  <span className="muted">{new Date(n.createdAt).toLocaleString()}</span>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+// --- R2: file upload ------------------------------------------------------
+function FilesCard() {
+  const [files, setFiles] = useState<UploadedFile[] | null>(null);
+  const [uploading, setUploading] = useState(false);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const load = () =>
+    apiJson<{ files: UploadedFile[] }>("/api/files")
+      .then((r) => setFiles(r.files))
+      .catch((e) => showToast({ title: "Could not load files", description: message(e), variant: "error" }));
+
+  useEffect(() => void load(), []);
+
+  async function upload() {
+    const file = inputRef.current?.files?.[0];
+    if (!file) return;
+    setUploading(true);
+    try {
+      const fd = new FormData();
+      fd.append("file", file);
+      const res = await api("/api/files", { method: "POST", body: fd });
+      if (!res.ok) throw new Error(`upload failed (${res.status})`);
+      if (inputRef.current) inputRef.current.value = "";
+      await load();
+    } catch (e) {
+      showToast({ title: "Could not upload file", description: message(e), variant: "error" });
+    } finally {
+      setUploading(false);
+    }
+  }
+
+  return (
+    <Card className="card">
+      <CardHeader>
+        <CardTitle>Files</CardTitle>
+        <CardDescription>Uploads to your app's R2 bucket.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <div className="stack">
+          <div className="row">
+            <input ref={inputRef} type="file" className="file-input" onChange={upload} />
+            {uploading && <Spinner />}
+          </div>
+          {files === null ? (
+            <Spinner />
+          ) : files.length === 0 ? (
+            <p className="muted">No files yet.</p>
+          ) : (
+            <ul className="list">
+              {files.map((f) => (
+                <li key={f.key} className="list__item">
+                  <span>{f.name}</span>
+                  <span className="muted">{bytes(f.size)}</span>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+// --- Audience-bound notifications ----------------------------------------
+function NotifyCard() {
+  const [title, setTitle] = useState("");
+  const [body, setBody] = useState("");
+  const [sending, setSending] = useState(false);
+
+  async function send() {
+    if (!title.trim() || !body.trim()) return;
+    setSending(true);
+    try {
+      const res = await api("/api/notify", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ title, body }),
+      });
+      const data = (await res.json().catch(() => ({}))) as { error?: string };
+      if (res.ok) {
+        showToast({ title: "Notification sent", variant: "success" });
+        setTitle("");
+        setBody("");
+      } else if (data.error === "notifications_not_configured") {
+        showToast({
+          title: "Notifications not configured",
+          description: "Set NOTIFY_API_BASE and NOTIFY_API_KEY to send for real.",
+          variant: "warning",
+        });
+      } else {
+        showToast({ title: "Could not send", description: data.error, variant: "error" });
+      }
+    } catch (e) {
+      showToast({ title: "Could not send", description: message(e), variant: "error" });
+    } finally {
+      setSending(false);
+    }
+  }
+
+  return (
+    <Card className="card">
+      <CardHeader>
+        <CardTitle>Notify your users</CardTitle>
+        <CardDescription>
+          Sends an audience-bound push to your App Users — content only, no
+          phone numbers.
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <div className="stack">
+          <Input value={title} placeholder="Title" onChange={(e) => setTitle(e.target.value)} />
+          <Textarea value={body} placeholder="Message" onChange={(e) => setBody(e.target.value)} />
+          <Button onClick={send} disabled={sending || !title.trim() || !body.trim()}>
+            {sending ? <Spinner /> : "Send notification"}
+          </Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

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

@@ -0,0 +1,23 @@
+import { Card, CardContent, Logo } from "@pplethai/components";
+
+// Shown when the app is opened outside PPLE Today (a plain browser). There is
+// no sign-in here on purpose: mini-apps authenticate through PPLE Today.
+export function NotInApp() {
+  return (
+    <main className="screen screen--center">
+      <Card className="card">
+        <CardContent>
+          <div className="notinapp">
+            <Logo className="notinapp__logo" title="People's Party" />
+            <h1 className="notinapp__title">เปิดในแอป PPLE Today</h1>
+            <p>
+              แอปนี้ทำงานภายในแอป PPLE Today เท่านั้น
+              กรุณาเปิดจากแอป PPLE Today เพื่อเข้าสู่ระบบ
+            </p>
+            <p className="muted">Please open this mini-app from inside PPLE Today to sign in.</p>
+          </div>
+        </CardContent>
+      </Card>
+    </main>
+  );
+}

package/templates/golden-path/web/app.css

@@ -0,0 +1,112 @@
+/* App layout. The design system (@pplethai/components) styles the components;
+   this file only handles page layout, and stays mobile-first: one column,
+   comfortable tap targets, safe-area padding for the PPLE Today WebView. */
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: "IBM Plex Sans Thai Looped", system-ui, -apple-system, sans-serif;
+  background: #f5f5f5;
+  color: #212121;
+}
+
+.screen {
+  max-width: 640px;
+  margin: 0 auto;
+  padding: 16px;
+  padding-bottom: max(16px, env(safe-area-inset-bottom));
+  min-height: 100vh;
+}
+
+.screen--center {
+  display: grid;
+  place-items: center;
+}
+
+.appbar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 8px 4px 16px;
+}
+
+.appbar__logo {
+  height: 28px;
+  width: auto;
+  color: #ff6a13; /* brand primary */
+}
+
+.appbar__title {
+  font-weight: 600;
+  font-size: 18px;
+  margin-right: auto;
+}
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.row {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.row > :first-child {
+  flex: 1;
+}
+
+.card {
+  width: 100%;
+}
+
+.list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.list__item {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  align-items: baseline;
+}
+
+.muted {
+  color: #6b6b6b;
+  font-size: 14px;
+}
+
+.file-input {
+  flex: 1;
+  min-width: 0;
+}
+
+.notinapp {
+  text-align: center;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  align-items: center;
+  padding: 16px;
+}
+
+.notinapp__logo {
+  height: 48px;
+  width: auto;
+  color: #ff6a13;
+}
+
+.notinapp__title {
+  margin: 0;
+  font-size: 20px;
+}

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

@@ -0,0 +1,40 @@
+// App entry point. Import the design-system styles first, then our own.
+import "@pplethai/components/styles.css";
+import "./app.css";
+
+import { Alert, AlertDescription, AlertTitle, Toaster } from "@pplethai/components";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import { NotInApp } from "./NotInApp";
+import { bootstrap } from "./pple";
+
+function ErrorScreen({ message }: { message: string }) {
+  return (
+    <main className="screen screen--center">
+      <Alert variant="destructive" className="card">
+        <AlertTitle>Could not start</AlertTitle>
+        <AlertDescription>{message}</AlertDescription>
+      </Alert>
+    </main>
+  );
+}
+
+const root = createRoot(document.getElementById("root")!);
+
+// Establish the session (PPLE Today token, dev bypass, or "not in app") before
+// rendering, so the first paint is the right screen.
+bootstrap().then((result) => {
+  root.render(
+    <StrictMode>
+      <Toaster />
+      {result.kind === "signed-in" ? (
+        <App />
+      ) : result.kind === "not-in-app" ? (
+        <NotInApp />
+      ) : (
+        <ErrorScreen message={result.message} />
+      )}
+    </StrictMode>,
+  );
+});

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

@@ -0,0 +1,73 @@
+// 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.
+//   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 — not inside PPLE Today, so we show the NOT_IN_APP
+//      screen instead of trying to sign in.
+import { isInMiniAppUserAgent } from "@pplethai/components";
+import { PPLEMiniApp } from "@pplethai/pple-today-miniapp-sdk";
+
+// Provisioned per app, injected at build time. Only needed inside PPLE Today.
+const OAUTH_URL = import.meta.env.VITE_OAUTH_URL ?? "";
+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";
+
+export type Bootstrap =
+  | { kind: "signed-in" }
+  | { kind: "not-in-app" }
+  | { kind: "error"; message: string };
+
+let token: string | null = null;
+
+/** Establish the session. Call once at startup, before rendering the app. */
+export async function bootstrap(): Promise<Bootstrap> {
+  try {
+    if (import.meta.env.DEV) {
+      token = DEV_TOKEN;
+      return { kind: "signed-in" };
+    }
+
+    if (!isInMiniAppUserAgent(navigator.userAgent)) {
+      return { kind: "not-in-app" };
+    }
+
+    const sdk = new PPLEMiniApp({
+      oauthUrl: OAUTH_URL,
+      oauthClientId: OAUTH_CLIENT_ID,
+      oauthRedirectUri: OAUTH_REDIRECT_URI,
+    });
+    await sdk.init();
+    token = await sdk.getAccessToken();
+    return { kind: "signed-in" };
+  } catch (e) {
+    return { kind: "error", message: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/**
+ * Call your Worker API with the bearer token attached. Paths are relative
+ * ("/api/notes"), since the SPA and the Worker share one origin.
+ */
+export async function api(path: string, init: RequestInit = {}): Promise<Response> {
+  if (!token) throw new Error("not signed in — call bootstrap() first");
+  const headers = new Headers(init.headers);
+  headers.set("authorization", `Bearer ${token}`);
+  return fetch(path, { ...init, headers });
+}
+
+/** Small helper: call the API and parse JSON, throwing on a non-2xx status. */
+export async function apiJson<T>(path: string, init: RequestInit = {}): Promise<T> {
+  const res = await api(path, init);
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as { error?: string };
+    throw new Error(body.error ?? `request failed (${res.status})`);
+  }
+  return res.json() as Promise<T>;
+}

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

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+// Build-time OIDC config for the mini-app SDK. These are public values (a
+// client id and public OAuth URLs), safe to ship in the bundle. The platform
+// injects them at deploy time; see .env.example.
+interface ImportMetaEnv {
+  readonly VITE_OAUTH_URL?: string;
+  readonly VITE_OAUTH_CLIENT_ID?: string;
+  readonly VITE_OAUTH_REDIRECT_URI?: string;
+}

package/templates/golden-path/wrangler.jsonc

@@ -0,0 +1,53 @@
+// Your Builder App's Cloudflare configuration. The platform provisions the
+// real D1/R2 resources and injects secrets at deploy time; the values below
+// work for local development out of the box.
+//
+// Everything here is meant to be read top-to-bottom: one Worker serves the
+// API under /api/* and the React SPA for everything else.
+{
+  "name": "pple-app",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-06-01",
+
+  // The React SPA (built to dist/client by Vite) is served for any request
+  // that isn't worker-first. "/api/*" is the app's API; "/.pple/*" is reserved
+  // for the platform deploy probe. "single-page-application" makes every
+  // other path return index.html so client-side routing works.
+  "assets": {
+    "not_found_handling": "single-page-application",
+    "run_worker_first": ["/api/*", "/.pple/*"]
+  },
+
+  // Your app's private SQLite database (D1). Migrations live in ./migrations
+  // and are applied with `npm run db:migrate:local` / `:remote`.
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "pple-app",
+      "database_id": "00000000-0000-0000-0000-000000000000",
+      "migrations_dir": "migrations"
+    }
+  ],
+
+  // Your app's private file storage (R2).
+  "r2_buckets": [
+    {
+      "binding": "FILES",
+      "bucket_name": "pple-app"
+    }
+  ],
+
+  "vars": {
+    // PPLE ID (identity). The Worker validates bearer tokens against this.
+    "SSO_BASE_URL": "https://sso.peoplesparty.or.th",
+    // Audience-bound notification endpoint (see src/notify.ts): the base that
+    // `${NOTIFY_API_BASE}/notifications` is posted to. The platform sets the
+    // real value; empty locally so notify is a no-op unless you wire it up in
+    // .dev.vars.
+    "NOTIFY_API_BASE": ""
+  }
+
+  // Secrets (never checked in): set with `wrangler secret put <NAME>`.
+  //   NOTIFY_API_KEY  — your app's audience-bound notification key (platform-provisioned)
+  //   DEV_AUTH        — local dev only; set in .dev.vars, never in production
+}