@pplethai/cli 0.1.0

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

@@ -0,0 +1,85 @@
+# PPLE ID authentication (Builder Apps)
+
+PPLE ID is the party's OIDC identity provider. For a **mini-app**, the flow is:
+
+```
+PPLE Today ──opens mini-app in WebView──▶ web (React)
+    web: PPLEMiniApp.init() → getAccessToken()     ── bearer token
+    web ──Authorization: Bearer <token>──▶ Worker
+    Worker ──GET {SSO_BASE_URL}/oidc/v1/userinfo──▶ PPLE ID
+```
+
+The Worker never sees a password and holds no session; the bearer token is
+the credential on every request (`src/auth.ts`).
+
+Tokens also exist outside mini-apps for **Builders** (Console browser login,
+`pple auth login` device flow). That does not change end-user auth for the
+app you are building: do not invent a browser sign-in for the mini-app itself.
+
+## Three ways the mini-app can start
+
+Canonical wiring: `web/pple.ts` + `web/main.tsx` + `web/NotInApp.tsx` in the
+golden-path template.
+
+1. **Local `vite dev`** — set `token` to the `DEV_AUTH` value from `.dev.vars`
+   and treat the session as signed-in. No PPLE Today required.
+2. **Inside PPLE Today** — detect the mini-app user agent, init
+   `@pplethai/pple-today-miniapp-sdk`, capture the access token from the
+   launch URL, attach it on every `api()` call.
+3. **Plain browser (production)** — show the friendly NOT_IN_APP screen
+   ("เปิดในแอป PPLE Today"). There is no browser login for mini-apps.
+
+```tsx
+import { isInMiniAppUserAgent } from "@pplethai/components";
+import { PPLEMiniApp } from "@pplethai/pple-today-miniapp-sdk";
+
+// Local: import.meta.env.DEV → DEV_AUTH token ("dev-token" by default)
+// Plain browser: !isInMiniAppUserAgent → { kind: "not-in-app" }
+// Inside Today: 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.
+
+## Worker: validating the token
+
+```ts
+// src/auth.ts — pattern from the template
+if (env.DEV_AUTH && token === env.DEV_AUTH) {
+  return { ok: true, identity: { sub: "dev-user", name: "Local Dev" } };
+}
+
+const res = await fetch(`${env.SSO_BASE_URL}/oidc/v1/userinfo`, {
+  headers: { authorization: `Bearer ${token}` },
+});
+```
+
+- Missing / invalid token → 401.
+- PPLE ID unreachable / malformed profile → 502 (so the client can tell
+  "sign in again" from "try again later").
+- Attach `{ sub, name }` to the request context; keep route handlers thin.
+
+## Local DEV_AUTH only
+
+```env
+# .dev.vars (gitignored) — copy from .dev.vars.example
+DEV_AUTH="dev-token"
+```
+
+Rules:
+
+- **Never** set `DEV_AUTH` in production. The platform never provisions it;
+  absence means real auth only.
+- The React app's local token must match `DEV_AUTH` exactly (template default:
+  `dev-token`).
+- Do not resurrect header-based impersonation (`x-dev-phone`,
+  `ALLOW_DEV_AUTH`) — that was the Express-era bypass.
+
+## What not to tell the Builder
+
+- Do not claim "tokens only exist inside PPLE Today" as a platform-wide fact
+  (Console and CLI also hold Builder tokens).
+- Do not add a custom OAuth redirect login page to the mini-app "so it works
+  in Chrome."
+- Do not ask for GitHub or Cloudflare credentials to "get a token."

package/skills/pple-platform/references/project-scaffold.md

@@ -0,0 +1,75 @@
+# Project scaffold & local development
+
+New Builder Apps start from the golden-path template in
+`pple-platform/template`, copied by `pple init <slug>` after the Console
+creates the app. Do not scaffold Express/Prisma monorepos or copy
+`pple-erp` — that layout is the old path.
+
+## Layout (single package)
+
+```
+my-app/                     # folder name matches the App Slug
+├── package.json            # scripts: dev, build, test, deploy, db:migrate:*
+├── wrangler.jsonc          # Worker + D1 + R2 bindings (platform-owned names)
+├── .dev.vars.example       # copy to .dev.vars for local DEV_AUTH
+├── .pple/app.json          # App Link — written by pple init; do not invent
+├── src/                    # Worker (API) — Hono routes under /api/*
+│   ├── index.ts            # thin route handlers
+│   ├── auth.ts             # PPLE ID userinfo + DEV_AUTH bypass
+│   ├── db.ts               # D1 helpers
+│   ├── files.ts            # R2 helpers
+│   ├── notify.ts           # audience-bound notifications
+│   └── env.ts              # Env bindings type
+├── web/                    # React SPA (Vite)
+│   ├── main.tsx            # bootstrap → App | NotInApp | error
+│   ├── pple.ts             # SDK / DEV_AUTH / api() helpers
+│   ├── App.tsx
+│   ├── NotInApp.tsx
+│   └── app.css             # mobile-first layout only
+├── shared/                 # Zod schemas + types used by both sides
+│   └── api.ts
+├── migrations/             # D1 SQL migrations (0001_*.sql, …)
+└── test/                   # smoke tests in the Workers runtime
+```
+
+**`shared/api.ts` is the contract** between Worker and SPA. Change a shape
+there once; both sides import the Zod schema / inferred type.
+
+## Conventions
+
+- **One origin.** The Worker serves `/api/*` and the SPA for everything else.
+  Frontend calls use relative paths (`/api/notes`) via `api()` / `apiJson()`
+  in `web/pple.ts`.
+- **Keep handlers thin.** Put logic in `auth` / `db` / `files` / `notify`.
+- **Validate with Zod** from `shared/api.ts`.
+- **Bind D1 parameters** (`?` + `.bind(...)`) — never string-concatenate SQL.
+- **Add a table** with a new `migrations/000N_*.sql` (never edit an applied
+  migration), then `npm run db:migrate:local`.
+- **Mobile-first.** The app runs in a phone-sized WebView.
+- **User-facing strings are Thai** where the template already is; code and
+  comments stay English.
+
+## Local development
+
+```bash
+# After Console create-app + pple auth login + pple init <slug>:
+cd <slug>
+npm install
+cp .dev.vars.example .dev.vars   # enables DEV_AUTH for plain-browser work
+npm run db:migrate:local
+npm run dev                      # http://localhost:5173 — SPA + Worker
+```
+
+Everyday commands:
+
+| Command | Does |
+| ------- | ---- |
+| `npm run dev` | Full-stack Vite + Worker with hot reload |
+| `npm run typecheck` | Type-check app and Worker |
+| `npm test` | Smoke tests in the Workers runtime |
+| `npm run build` | Deployable bundle |
+| `npm run db:migrate:local` | Apply D1 migrations locally |
+| `pple deploy` | Ship via the platform CLI |
+
+In local `vite dev`, `web/pple.ts` uses the `DEV_AUTH` token automatically so
+you never need PPLE Today open. See [pple-id-auth.md](pple-id-auth.md).

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

@@ -0,0 +1,17 @@
+# Local development configuration. Copy this file to `.dev.vars` (which is
+# gitignored) and adjust. `wrangler dev` and `vite 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"
+
+# Optional: 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/.env.example

@@ -0,0 +1,8 @@
+# Frontend build-time config (Vite exposes VITE_* to the browser bundle).
+# These are the app's PPLE ID OIDC client details, used by the mini-app SDK
+# when running inside PPLE Today. They are public values, safe to ship.
+# The platform injects them at deploy time; copy to `.env` to set locally.
+VITE_OAUTH_URL="https://sso.peoplesparty.or.th"
+VITE_OAUTH_CLIENT_ID=""
+# Defaults to the app's own origin if unset.
+# VITE_OAUTH_REDIRECT_URI=""

package/templates/golden-path/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+# CI for a PPLE Platform Builder App. Runs on every push and pull request:
+# type-checks the Worker and the React app, runs the smoke tests in the
+# Workers runtime, and builds the deployable bundle.
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build

package/templates/golden-path/CLAUDE.md

@@ -0,0 +1,60 @@
+# Working in this repo
+
+This is a **PPLE Platform Builder App** — a mobile-first mini-app that runs
+inside PPLE Today. The person you're helping is a party workforce member who
+may not read stack traces; keep changes simple, explain them plainly, and
+prefer editing the existing demo cards over introducing new patterns.
+
+## Architecture (read once)
+
+One Cloudflare Worker serves everything:
+
+- **`src/`** — the Worker (API). Hono, TypeScript, Workers runtime. Routes
+  live under `/api/*` in `src/index.ts`; keep handlers thin and put logic in
+  the helper modules (`auth`, `db`, `files`, `notify`).
+- **`web/`** — the React app (browser). Built by Vite, served for every
+  non-`/api` path. Uses the `@pplethai/components` design system.
+- **`shared/`** — types shared by both sides (Zod schemas in `shared/api.ts`).
+  When you change an API shape, change it here and both sides update.
+- **`migrations/`** — D1 (SQLite) schema, applied in order.
+
+The frontend calls the backend with `api()` / `apiJson()` from `web/pple.ts`,
+which attach the PPLE ID bearer token. Same origin, so paths are relative
+(`/api/notes`).
+
+## 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`).
+- In a plain browser, the app shows the NOT_IN_APP screen — there is no
+  browser sign-in for mini-apps.
+- Locally, `DEV_AUTH` in `.dev.vars` bypasses PPLE Today. **Never** set
+  `DEV_AUTH` in production; the platform never provisions it.
+
+## Conventions
+
+- **TypeScript is strict.** Run `npm run typecheck` after changes.
+- **Validate input with the Zod schemas** in `shared/api.ts`.
+- **Always bind D1 query parameters** (`?` + `.bind(...)`) — never build SQL
+  with string concatenation.
+- **Notifications are content only** (title/body), plus an optional path-only
+  `linkPath` into this app. Never send phone numbers or user ids; the platform
+  resolves the audience. See `src/notify.ts`.
+- **Mobile-first.** The app runs in a phone-sized WebView. Use the design
+  system's components and the layout classes in `web/app.css`.
+- **Add a DB table** by writing a new `migrations/000N_*.sql` (never edit an
+  applied migration) and running `npm run db:migrate:local`.
+
+## Before you finish
+
+Run these and make sure they pass:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```
+
+`npm test` runs the smoke tests inside the real Workers runtime. If you add a
+capability, add a smoke test for it in `test/`.

package/templates/golden-path/README.md

@@ -0,0 +1,60 @@
+# PPLE Platform — Golden-path template
+
+The starting point for a **Builder App** on the PPLE Platform. It's a
+mobile-first mini-app that runs inside PPLE Today, built on the platform's
+managed Cloudflare stack, wired to the People's Party identity, data, file,
+and notification services out of the box.
+
+You don't need to understand Cloudflare, OAuth, or SQL to use it — describe
+what you want to your AI coding agent and edit the demo cards. See
+[CLAUDE.md](CLAUDE.md) for how the agent should work in this repo.
+
+## What's inside
+
+| Capability | Where | Demo |
+| ---------- | ----- | ---- |
+| **API** | Hono Worker, `src/index.ts` | routes under `/api/*` |
+| **Identity** | `src/auth.ts` + `web/pple.ts` | validates PPLE ID tokens; NOT_IN_APP screen; dev bypass |
+| **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`) |
+| **Design system** | `@pplethai/components` | every screen |
+
+One Worker serves the API under `/api/*` and the React app (`web/`) for
+everything else — same origin, no CORS.
+
+## Getting started
+
+```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
+```
+
+In local dev you're signed in automatically as a fake user (the `DEV_AUTH`
+bypass), so you can build without PPLE Today. Opened in a plain browser after
+deploy, the app shows a friendly "open in PPLE Today" screen; opened inside
+PPLE Today, it signs the real user in via the mini-app SDK.
+
+## Everyday commands
+
+| Command | Does |
+| ------- | ---- |
+| `npm run dev` | Full-stack dev server (React + Worker) with hot reload |
+| `npm run typecheck` | Type-check the app and the Worker |
+| `npm test` | Run the smoke tests in the Workers runtime |
+| `npm run build` | Build the deployable bundle |
+| `npm run db:migrate:local` | Apply migrations to the local database |
+| `pple deploy` | Ship it (the platform CLI; wraps `npm run deploy`) |
+
+## Making it yours
+
+- **Add a table:** create `migrations/0002_*.sql`, run `npm run db:migrate:local`,
+  add queries in `src/db.ts`.
+- **Add an API route:** add it under `/api` in `src/index.ts`.
+- **Change the UI:** edit `web/App.tsx` using `@pplethai/components`.
+- **Send notifications:** the platform provisions `NOTIFY_API_KEY`; the helper
+  in `src/notify.ts` already speaks the audience-bound contract.
+
+The demo cards (Notes / Files / Notify) are examples — replace them.

package/templates/golden-path/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.wrangler/
+.dev.vars
+*.log
+.claude/skills/pple-platform/

package/templates/golden-path/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="th">
+  <head>
+    <meta charset="utf-8" />
+    <!-- Mobile-first: fit the notch/safe areas of the PPLE Today WebView. -->
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, viewport-fit=cover"
+    />
+    <title>PPLE App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/web/main.tsx"></script>
+  </body>
+</html>

package/templates/golden-path/migrations/0001_init.sql

@@ -0,0 +1,9 @@
+-- The example table behind the D1 read/write demo. Replace it with your own
+-- schema: add a new file (0002_add_something.sql, …) and apply it with
+-- `npm run db:migrate:local` (local) or `npm run db:migrate:remote` (deployed).
+CREATE TABLE notes (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  body TEXT NOT NULL,
+  -- ISO-8601 UTC (…T…Z) so the timestamp is unambiguous everywhere it's read.
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);