@pplethai/cli 0.5.1 → 0.7.0

package/skills/pple-platform/references/mini-app.md

@@ -1,111 +0,0 @@
-# Mini-app integration & notifications
-
-## Running inside PPLE Today
-
-Builder Apps ship as **mini-apps**: web apps opened in PPLE Today's WebView.
-`@pplethai/pple-today-miniapp-sdk` captures the access token — see
-[pple-id-auth.md](pple-id-auth.md). Facts that shape your design:
-
-- `sdk.init()` must complete before any other SDK call.
-- Outside PPLE Today (plain browser), the same SDK runs the PPLE ID browser
-  login — that is expected, not an error. Locally, `DEV_AUTH` covers
-  development.
-- The OAuth client and mini-app URL are provisioned when the app is created in
-  the Console; Builders do not register them manually with the Today team.
-- Design mobile-first; test at ~375 px width.
-
-## Push notifications (Broadcast and Direct)
-
-Builder Apps send push notifications through `sendNotification` in
-`src/notify.ts`. Every send **states its audience** — the two kinds follow
-from that:
-
-- **Broadcast** (การแจ้งเตือนทุกคน) — `{ kind: "all" }`, to everyone this app
-  can reach: its App Users ∩ its current publication-tier audience.
-- **Direct** (การแจ้งเตือนรายบุคคล) — `{ kind: "direct", recipients }`, to
-  the people this app names, by PPLE ID `sub` or mobile number.
-
-The audience is a **required discriminated union**. Omitting it is a compile
-error, not a silent broadcast — that is the dangerous bug this shape exists
-to prevent. Do not default a missing audience to `all`.
-
-Naming **narrows** the reachable set and never widens it. A named person who
-has never opened this app receives nothing and comes back `not_reachable`.
-That status is **one collapsed reason** covering "no PPLE ID at all", "never
-opened this app", "outside the tier", and "opted out". Do not decompose it,
-surface it as a guess, or infer *why*. Use it to prune stale names — a send
-debits the reach it requested (every named recipient, or the Broadcast
-audience size), so leftover entries cost quota until removed.
-
-`NOTIFY_API_BASE` and `NOTIFY_API_KEY` are provisioned bindings. The key *is*
-the address — no app id on the wire. Recipients belong only on a Direct send,
-on this same route.
-
-### App-facing shape (`shared/api.ts`)
-
-Call `sendNotification` with a `Notification` from `shared/api.ts`. Do not
-invent a parallel payload or POST the wire shape yourself.
-
-```ts
-import { sendNotification } from "./notify";
-
-await sendNotification(env, {
-  audience: {
-    kind: "direct",
-    recipients: [{ sub: "…" }, { phone: "0812345678" }],
-  },
-  // or: { kind: "all" },
-  title: "Reimbursement approved",
-  body: "Your claim was approved",
-  linkPath: "/claims/123", // optional path-only self-link
-});
-```
-
-A recipient entry names **exactly one** of `sub` or `phone`. Cap is 200 per
-call — over it is a refusal, never a silent truncation, so chunk a long list
-deliberately. Optional `idempotencyKey` makes a retry after a timeout safe.
-
-Optional `linkPath` is a deep link into **this** app only. The platform joins
-it to the app's known entry and rejects absolute URLs, schemes, `..`, or
-anything that would leave this app. Free-form destinations that could address
-another mini app (e.g. `content.link`) are not available on this route.
-Omit `linkPath` when the tap should open the notification centre.
-
-A Direct send returns each named entry as `delivered` or `not_reachable`,
-echoed as the caller named it. A Broadcast names no one, so there is nothing
-to enumerate.
-
-### Wire shape (`src/notify.ts`)
-
-Keep the platform vocabulary translation in `notify.ts` only. Your routes
-call `sendNotification`; they do not POST this themselves:
-
-```ts
-body: JSON.stringify({
-  audience: input.audience,
-  content: { header: input.title, message: input.body },
-  ...(input.linkPath !== undefined ? { linkPath: input.linkPath } : {}),
-  ...(input.idempotencyKey !== undefined
-    ? { idempotencyKey: input.idempotencyKey }
-    : {}),
-})
-```
-
-- Missing config → fail loud (`notifications_not_configured` / 503), not silent.
-- HTTP 429 → `quota_exceeded` (**nothing was delivered**). The helper also
-  maps the other refusals (`invalid_request`, `invalid_recipients`,
-  `idempotency_key_conflict`, `not_permitted`).
-- Prefer fire-and-forget from route handlers with error logging — do not fail
-  the user's primary action solely because notify is slow.
-
-### What not to do
-
-Do **not** call the legacy central-team endpoint that accepts a
-`PHONE_NUMBER` audience (`/external/notifications/send` with raw numbers).
-Naming a phone on `sendNotification` is the Direct contract; that unbound
-path is not. If you see older docs or `mini-app-example` code addressing
-phones on `/external/notifications/send`, ignore them for new apps.
-Do **not** invent free-form link / absolute URL fields — self-links use
-`linkPath` only.
-Do **not** treat `not_reachable` as "not a party member" versus "not a user
-of this app". That distinction is the one fact this status exists to hide.

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

@@ -1,99 +0,0 @@
-# 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
-```
-
-In a plain browser the same SDK runs the PPLE ID authorization-code login
-(redirect / callback) instead of reading tokens from the launch URL; the
-Worker still validates the bearer token the same way.
-
-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). End users of a Builder App authenticate
-through the mini-app SDK — either inside PPLE Today or via that SDK's
-browser PPLE ID flow. Do not invent a second custom login page.
-
-## Three ways the mini-app can start
-
-Canonical wiring: `web/pple.ts` + `web/main.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** — init `@pplethai/pple-today-miniapp-sdk`, capture
-   the access token from the launch URL, attach it on every `api()` call.
-3. **Plain browser (production)** — the same SDK completes the OIDC sign-in
-   callback or redirects to PPLE ID; on return it stores the access token
-   and the app continues as signed-in.
-
-```tsx
-import { PPLEMiniApp } from "@pplethai/pple-today-miniapp-sdk";
-
-// Local: import.meta.env.DEV → DEV_AUTH token ("dev-token" by default)
-// Production (Today or browser): sdk.init() → getAccessToken() → { kind: "signed-in" }
-```
-
-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
-
-```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; end users can also sign in via
-  the SDK's browser PPLE ID flow).
-- Do not add a custom OAuth redirect login page, or a NotInApp / "open in
-  PPLE Today only" guard — the SDK already handles the browser case.
-- Do not ask for GitHub or Cloudflare credentials to "get a token."

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

@@ -1,75 +0,0 @@
-# Project scaffold & local development
-
-New Builder Apps start from the golden-path template in
-`pple-platform/template`, copied by `pple init` (create-and-scaffold, or
-`pple init <slug>` after Console create). 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           # Broadcast and Direct notifications
-│   └── env.ts              # Env bindings type
-├── web/                    # React SPA (Vite)
-│   ├── main.tsx            # bootstrap → App | error
-│   ├── pple.ts             # SDK / DEV_AUTH / api() helpers
-│   ├── App.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 pple auth login + create/scaffold (pple init / --name, or Console
-# then 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).