PiCloud/E2E_TODO_REPORT.md

# E2E Developer Test — Rich To-Do App via the `pic` CLI

**Date:** 2026-06-12 · **Tester:** manual end-to-end walkthrough · **Build:** v1.1.9
(`product 1.1.9`, `sdk 1.10`, `api 1`, `schema 42`) · **Instance:** host-run `picloud`
in dev mode on `127.0.0.1:8099`, Postgres via `docker compose up postgres`.

## Goal

Act as a developer building a real product — a multi-user **To-Do app** (end-user
signup/login, per-user todos in document storage, full HTTP CRUD, a nightly cron cleanup,
and a realtime activity feed) — **entirely through the `pic` CLI**, and record every place
the happy path forced me off the CLI or behaved surprisingly.

## Verdict

**The platform can build and run the whole app — every capability exists and works.** The
data-plane journey (register → login → create → list → complete → ownership-checked delete →
auth rejection) is correct, `users::*` auth is solid, `docs::*` storage works, durable pubsub
fans out to an external SSE subscriber, and the cron trigger registers and runs.

**But a CLI-only developer cannot reach the finish line.** Two control-plane operations have
**no `pic` command at all** and forced me to drop to raw `curl` against the admin API — and
without the first one, *every* app created through the CLI serves `404` on every route.

> ## ✅ RE-TEST 2026-06-12 — ALL GAPS CLOSED (verified live)
>
> After remediation (commits `04a24ea`, `ae2134e`, `7ffbb8d`, `b831138`), I rebuilt the **entire
> app a second time CLI-only, with zero raw `curl` against the admin API** (app `todoapp2`,
> domain `todos2.local`). Every finding below is now fixed and verified end-to-end. See the
> [Re-test verification](#re-test-verification--2026-06-12) section at the bottom for the
> per-finding evidence. The original findings are preserved as-is for the record.

---

## App as built

| Surface | Implementation |
|---|---|
| `POST /auth/register` | `register.rhai` → `users::create` |
| `POST /auth/login` | `login.rhai` → `users::login` → session token |
| `GET /todos` | `todos_list.rhai` → `docs.find({user_id})` |
| `POST /todos` | `todos_create.rhai` → `docs.create` + `pubsub::publish_durable("activity", …)` |
| `PATCH /todos/:id` | `todos_update.rhai` → ownership check + complete + publish |
| `DELETE /todos/:id` | `todos_delete.rhai` → ownership check + delete |
| cron `0 0 3 * * *` | `cleanup.rhai` → purge completed todos older than 7d |
| realtime | SSE `GET /realtime/topics/activity` |

7 scripts, 6 routes, 1 cron trigger, 1 app, 1 domain claim, 1 pubsub topic. Sources in
`/tmp/todo-app/*.rhai`.

---

## BLOCKERS — no CLI path; app cannot serve traffic without raw API

### B1. No domain-claim command — every CLI-created app 404s until you `curl`
**Severity: BLOCKER (highest-impact finding).**

After `pic apps create`, deploying scripts, and binding routes, *every* request 404'd:
```
$ curl -s -X POST localhost:8099/auth/register -d '{...}'
{"error":"no route matches POST /auth/register"}
```
Reason: Host→app dispatch resolves `localhost` to the **default** app; a non-default app's
routes are unreachable until the app claims a domain. But `pic apps` exposes only
`ls / create / show / delete` — **no domain subcommand** — and there is no top-level
`pic domains` either. The only way through is the raw admin API:
```
curl -X POST localhost:8099/api/v1/admin/apps/$APP/domains \
     -H "authorization: Bearer $TOKEN" -d '{"pattern":"todos.local"}'
```
After that, routing works (with `Host: todos.local`). **A developer who only knows the CLI is
hard-stuck here** — they have created scripts and routes that silently never match, with no CLI
affordance explaining why. *Fix: add `pic apps domains {ls,add,rm}` (the API already exists in
`apps_api.rs`).*

### B2. No pubsub topic-registration command — realtime feed needs raw API
**Severity: BLOCKER for the realtime requirement.**

Scripts can `pubsub::publish_durable("activity", …)` fine (publishing needs no pre-registration),
but an **external** SSE subscriber on `/realtime/topics/activity` only receives events once the
topic is registered as `external_subscribable`. There is no `pic topics` command. Worse, the
`pic triggers` help text actively points you at `create-from-json` "for kinds the CLI doesn't
expose … (docs/files/pubsub/…)" — but that creates a *pubsub trigger* (run a script on publish),
which is a different concept and does **not** register a topic for outside subscribers. Workaround:
```
curl -X POST localhost:8099/api/v1/admin/apps/$APP/topics \
     -H "authorization: Bearer $TOKEN" \
     -d '{"name":"activity","external_subscribable":true,"auth_mode":"public"}'
```
Once registered, the SSE path works perfectly — a subscriber received:
```
data: {"message":{"kind":"created","title":"Realtime test", …},"topic":"activity", …}
```
*Fix: add `pic topics {ls,create,update,rm}` (API exists in `topics_api.rs`).*

---

## FRICTION — completable via CLI, but sharp edges

### F1. `pic deploy` / `apps create` ignore `--output json`
They print human strings even in JSON mode, so you can't capture the new id:
```
$ pic --output json deploy register.rhai --app todos-e2e
Created register v1                      # not JSON — no id emitted
$ pic --output json apps create todos-e2e
Created app todos-e2e                    # not JSON — no id emitted
```
Every later `routes`/`triggers`/domain/topic call needs that id, so each create forces a
follow-up `scripts ls --output json | parse` or `apps show`. This breaks naive scripting/CI.
*Fix: emit the created object as JSON under `--output json`.*

### F2. No `pic users` command for app end-users
The full `/api/v1/admin/apps/{id}/users` surface exists (list, get, reset-password,
revoke-sessions, invitations) but has no CLI wrapper, so a developer has zero CLI visibility
into who registered. Listing the two users I created required raw API. *Fix: `pic users …`.*

### F3. Password login is interactive-only
`pic login` offers `--url` and `--token` but **no** `--username`/`--password`. Non-interactive
(CI) auth means obtaining a bearer out-of-band (raw `POST /auth/login`, or pre-minting an
`pic api-keys` token — chicken-and-egg if you have no token yet). *Fix: optional
`--username` + `--password-stdin`.*

### F4. No `ctx.request.method` in scripts → one script per verb
The request map exposes `path, headers, body, params, query, rest` but **not the HTTP method**
(`engine.rs` builds the map without it). A script therefore cannot branch GET vs POST on the
same path, forcing a separate script + method-scoped route per verb. My app needed **7 scripts
where ~3 would do** (`/todos` GET+POST and `/todos/:id` PATCH+DELETE each had to split).
*Fix: add `ctx.request.method`.*

---

## SDK / SCRIPTING SHARP EDGES — platform correct, but the natural code fails at runtime

### S1. `users::find_by_email` is forbidden for anonymous (public) callers
The obvious registration pattern — "look up email, 409 if taken, else create" — fails:
```
{"error":"Runtime error: users: forbidden"}   # HTTP 502
```
`find_by_email` deliberately requires an authenticated principal (anti-enumeration, audit
finding F-S-003 in `users_service.rs`), while `users::create` is allowed for anonymous public
scripts. So a self-serve register script **must skip the pre-check** and rely on `create`'s
uniqueness error instead. The SDK doc-comment for `find_by_email` shows it with no caveat, so
this only surfaces as a runtime 502. *Fix: document the principal requirement on
`find_by_email`; consider a dedicated `users::email_available()` that's safe for anonymous use.*

### S2. Response envelope is `statusCode`-gated (silent double-nesting)
A returned map is unwrapped as `{statusCode, headers, body}` **only if it contains
`statusCode`**. Without it, the *entire* map becomes the literal body — so `#{ body: #{token} }`
returns `{"body":{"token":…}}`, not `{"token":…}`. I hit this on login/list/update until I added
`statusCode: 200`. The doc-comment examples don't flag it. *Fix: doc note, or treat a lone
`body` key as an envelope.*

### S3. Rhai `String.replace()` mutates in place and returns `()`
`let token = auth.replace("Bearer ", "")` sets `token` to unit, then `users::verify(())` →
`Function not found: users::verify (())`. Stock Rhai semantics, but a JS/Python dev will hit it;
`auth.sub_string(7)` after `starts_with("Bearer ")` is the correct idiom. *Fix: a one-line note
+ a bearer-parsing example in the stdlib reference.*

---

## ONBOARDING

### O1. Dev mode needs a second, undocumented acknowledgement var
`PICLOUD_DEV_MODE=true` alone aborts at startup:
```
Error: PICLOUD_DEV_MODE=true without PICLOUD_SECRET_KEY requires an explicit acknowledgement.
Set PICLOUD_DEV_INSECURE_KEY=i-understand-this-is-insecure to confirm …
```
CLAUDE.md and the dev notes mention only `PICLOUD_DEV_MODE=true`. Good security default, but the
error message is the sole documentation. *Fix: document `PICLOUD_DEV_INSECURE_KEY` next to
`PICLOUD_DEV_MODE`.*

---

## What worked well (no changes needed)

- End-to-end data plane fully correct: register, login, per-user list, create, complete, delete,
  **ownership 403** (Bob can't touch Alice's todo), **401** on missing/garbage token.
- `users::*`: login returns a 43-char session token, `verify` resolves it (sliding TTL),
  password hashing + email uniqueness enforced.
- `docs::collection(...).find({field})` filtered correctly; full-blob `update` semantics as
  documented.
- `pubsub::publish_durable` → external SSE delivery worked once the topic was registered.
- Cron trigger registered; `pic invoke <cleanup-id>` ran it → `{"removed":0}`.
- `pic deploy` **updates in place** (v1→v2, same id) — no duplicate scripts on redeploy.
- `pic routes match` resolved param routes and captured `param.id`; empty param segment
  (`/todos/`) correctly did **not** match.
- `pic logs <id>` listed executions with success/error status.

## Reproduction

Server: `docker compose up -d postgres`; then host-run with
`PICLOUD_DEV_MODE=true PICLOUD_DEV_INSECURE_KEY=i-understand-this-is-insecure
PICLOUD_BIND=127.0.0.1:8099 PICLOUD_ADMIN_USERNAME=admin PICLOUD_ADMIN_PASSWORD=admin
target/debug/picloud`. CLI: `cargo build -p picloud-cli` → `target/debug/pic`. App scripts:
`/tmp/todo-app/*.rhai`. Every command + captured output above was run live against this instance.

## Priority recommendation

The two CLI gaps that turn "I built an app" into "…but it 404s and has no realtime" are **B1
(domain claims)** and **B2 (topic registration)**. Both already have working admin APIs; they
just need thin `pic` wrappers (mirroring the existing `routes`/`triggers` commands). Ship those
two and a CLI-only developer can build this entire app without ever touching `curl`.

---

# Re-test verification — 2026-06-12

Second pass after the fix commits (`04a24ea` CLI gaps, `ae2134e` `ctx.request.method`,
`7ffbb8d` `users::email_available`, `b831138` docs). I rebuilt the whole app as a **fresh,
CLI-only** flow against the same live instance — new app `todoapp2`, domain `todos2.local`,
**no raw `curl` to any `/api/v1/admin/*` endpoint**. Data-plane HTTP calls (the app's own
traffic) still use curl, as a real end-user client would.

## Status table

| # | Finding | Status | Evidence |
|---|---------|--------|----------|
| B1 | No domain-claim command | ✅ Fixed | `pic apps domains add todoapp2 todos2.local` → claim created; routes then match. Help text even explains the 404-without-claim trap. |
| B2 | No pubsub topic command | ✅ Fixed | `pic topics create --app todoapp2 activity --external` → `external_subscribable:true`; SSE subscriber received the published event. |
| F1 | `deploy`/`apps create` ignore `--output json` | ✅ Fixed | Both now emit the full JSON object; I captured every script id straight from `deploy --output json` (no follow-up `scripts ls`). |
| F2 | No `pic users` command | ✅ Fixed | `pic users ls/show/reset-password` all work; listed Carol+Dave, showed Carol, minted a 1-shot reset token. |
| F3 | Password login interactive-only | ✅ Fixed | `printf 'admin' \| pic login --username admin --password-stdin` logged in non-interactively. |
| F4 | No `ctx.request.method` | ✅ Fixed | One `todos.rhai` now serves **GET+POST** and one `todo_item.rhai` serves **PATCH+DELETE** by branching on `ctx.request.method`; unsupported verb returns my `405`. Script count dropped 7→5, routes 6→4. |
| S1 | `find_by_email` forbidden for anon registration | ✅ Fixed | New `users::email_available(email)` → bool works from the anonymous register route; duplicate email now returns a clean `409`, no more `users: forbidden`/502. |
| S2 | `statusCode`-gated envelope (double-nest) | ✅ Documented | Behaviour noted in stdlib docs (`b831138`); my scripts use explicit `statusCode` and responses are flat. |
| S3 | Rhai `replace()` returns `()` footgun | ✅ Documented | Bearer-parsing note added; `auth.sub_string(7)` after `starts_with` is the idiom used. |
| O1 | Dev-mode needs undocumented ack var | ✅ Documented | `PICLOUD_DEV_INSECURE_KEY` now documented alongside `PICLOUD_DEV_MODE`. |

## CLI-only build transcript (abridged, all succeeded)

```
pic login --username admin --password-stdin           # F3
pic apps create todoapp2 --output json                # F1 → captured id
pic apps domains add todoapp2 todos2.local            # B1
pic deploy <f>.rhai --app todoapp2 --output json      # F1 → captured 5 script ids
pic routes create --script <id> --path /todos         # ANY-method route (F4 in-script branch)
pic routes create --script <id> --path /todos/:id --path-kind param
pic topics create --app todoapp2 activity --external  # B2
pic triggers create-cron --app todoapp2 --script <cleanup> --schedule "0 0 3 * * *"
pic users ls --app todoapp2                           # F2
```

## Data-plane journey (all green)

```
register carol/dave                       201 / 201
duplicate carol (email_available, S1)     409  {"error":"email already registered"}
login carol/dave                          43-char tokens
POST /todos  (method-branch create, F4)   201 ×2
GET  /todos  (same script, list, F4)      200  count:2
PATCH /todos/:id complete                 200
dave PATCH/DELETE carol's todo            403 / 403  (ownership)
carol DELETE                              200
PUT /todos (unsupported verb)             405  (in-script method guard)
no-auth GET /todos                        401
realtime SSE on activity                  received {"kind":"created",...,"topic":"activity"}
```

**Conclusion: a CLI-only developer can now build this entire app — auth, storage, CRUD,
ownership, cron, and a realtime feed — without ever touching `curl` against the admin API.**