@mediamonks/canopy-cli 0.7.20 → 0.7.22

package/dist/docs/sdk-slack.md

@@ -0,0 +1,132 @@
+---
+title: Slack
+description: Handle your bot's events and slash commands in your worker, and post to Slack as the bot — no tokens in project code.
+---
+
+Once your project has a Slack app ([set up on the Services
+tab](https://docs.canopy.website/platform/slack)), the integration is two halves: inbound events arrive
+at a `slack()` export in your worker, and outbound calls go through
+`canopy.slack`. The bot token and signing secret stay with the platform —
+Slack's signatures are verified before anything reaches your code.
+
+## The `slack()` handler
+
+Export it next to `fetch` and `scheduled`:
+
+```ts
+export default {
+  fetch(request, env) {
+    /* … */
+  },
+
+  async slack(event, env) {
+    if (event.kind === "command") {
+      return { response_type: "in_channel", text: `Running ${event.payload.command}…` };
+    }
+    // kind === "event": an @-mention, a DM, …
+  },
+};
+```
+
+**The event object:**
+
+- `kind` — `"event"` (Events API: `app_mention`, `message`, …) or
+  `"command"` (a slash command).
+- `payload` — Slack's payload, verbatim. For events that's the full
+  callback (the interesting part is `payload.event`); for commands it's the
+  command form fields (`command`, `text`, `channel_id`, `user_id`, …).
+- `responseUrl` — commands only: where a late reply can still be sent (see
+  below).
+- `user` — who triggered this, as Slack tells it: `{ id, name? }`. Present
+  whenever Slack names a person.
+- `teamId`, `appId` — which workspace and app this came from.
+- `retry` — set when Slack is redelivering. Delivery is at-least-once, so
+  handlers that create things should tolerate seeing an event twice.
+
+## Who is talking to the bot
+
+Two identities, at two trust levels:
+
+- **`env.USER`** is set when the bot lives in the Monks workspace and the
+  sender has a Canopy account: the same `{ sub, email, name }` your fetch
+  routes see for a signed-in visitor, so user-specific logic works the same
+  way. The mapping rides the corporate directory — Slack accounts and Canopy
+  sign-ins are the same people there.
+- In any other workspace — a client's, say — `env.USER` is `null` and
+  `event.user` is all you get: Slack's own word for who typed, nothing
+  Canopy has verified. Fine for personalising a reply; don't hang
+  authorization on it.
+
+Either way, payload text is written by whoever typed it in Slack — treat it
+as untrusted input. And SDK calls from the handler still run as the project
+itself (`canopy.auth.user()` reports kind `worker`), regardless of
+`env.USER`.
+
+## Answering a slash command
+
+Slack gives a command three seconds. Return quickly and Canopy relays your
+answer as the command's response:
+
+```ts
+async slack(event, env) {
+  if (event.kind === "command") {
+    return { response_type: "ephemeral", text: "Done." };
+  }
+}
+```
+
+Return a Slack message object, or a plain string (sent as ephemeral text).
+Return nothing and the command completes silently.
+
+If your handler needs longer — it queries something slow, calls a model —
+the command is acknowledged for you, and you answer afterwards through the
+`responseUrl`, which stays valid for 30 minutes:
+
+```ts
+if (event.kind === "command") {
+  const answer = await somethingSlow();
+  await canopy.slack.respond(event.responseUrl!, {
+    response_type: "in_channel",
+    text: answer,
+  });
+}
+```
+
+Events (`kind: "event"`) have no response channel — react by calling out,
+usually `chat.postMessage` back into the conversation the event names.
+
+## slack.api(method, args)
+
+Any [Slack Web API method](https://docs.slack.dev/reference/methods), called
+as your project's bot:
+
+```ts
+const result = await canopy.slack.api("chat.postMessage", {
+  channel: "C0123456789",
+  text: "Deploy finished.",
+});
+if (!result.ok) console.warn("slack said no:", result.error);
+```
+
+The response is Slack's own, `ok: false` included — check it for
+method-level outcomes like `channel_not_found` or `not_in_channel` (the bot
+can only post to channels it's been invited to, and to people's DMs).
+Workspace-management method families (`admin.*`, `tooling.*`, `apps.*`,
+`oauth.*`) are refused before Slack is ever contacted; everything else is
+bounded by the permissions the app was installed with.
+
+Backend and `canopy dev` only — pages can't call it, so a visitor can never
+act as your bot.
+
+## slack.respond(responseUrl, message)
+
+The late reply to a slash command, described above. `message` is a Slack
+message object or a plain string.
+
+## Errors
+
+Refusals arrive as thrown errors with stable codes: `slack_not_configured`
+(no app on this project), `slack_not_installed` (created but not installed
+to a workspace), `slack_disabled` (switched off on the Services tab), and
+`slack_method_not_allowed`. A network-level failure reaching Slack is
+`slack_api_error`.

package/dist/docs/static-serving.md

@@ -1,323 +1,81 @@
 ---
 title: How static files are served
-description: The full path a browser request takes to a deployed file.
+description: Why every page is a file, and what that means for routing, caching, and deploys.
 ---
 
-This explains the full path a browser request takes to receive a deployed
-project's `index.html` and its assets (JS/CSS/images/fonts), and reviews that
-path from a **security** and a **performance** angle.
+Everything a visitor sees is a **file from your last deploy**. Canopy stores
+the build you shipped and serves it directly — a request for `/`, `/about`, or
+`/reports/42` never runs your code. If your project has a backend, requests
+under `/api/*` go to it; everything else is a file.
 
-Everything a visitor sees is a _deployed_ build stored in R2 — the platform
-serves pre-built static files. (When a project has a backend worker, `/api/*`
-requests dispatch to it — Workers for Platforms on Cloudflare, Cloud Run on
-GCP; everything else is still static serving.)
+That one fact explains most of how the platform behaves, so it's worth
+understanding before you fight it.
 
-Asset serving is the hottest **data-plane** path (see
-[`docs/09-plane-split.md`](../09-plane-split.md)): it lives at
-`/data/v1/assets/*`, and the URL carries no project slug — the gateway stamps
-which project the request is for.
+## Nothing is served to a stranger
 
-## The request path
+Every request passes the sign-in wall before a single byte of your project is
+read. A visitor arrives with a company login, or — if you've turned on
+[client access](https://docs.canopy.website/platform/client-access) — the project's password. There is no
+public URL, no "unlisted" link, and no way to opt a single file out. A project
+is readable by any signed-in colleague unless you set it to collaborators only,
+in [members and access](https://docs.canopy.website/platform/members-and-access).
 
-A request to `https://<slug>.canopy.<domain>/some/path` flows through two
-Workers and one R2 bucket:
+## Deep links work — routing is yours
 
-```
-Browser
-  │  GET https://dashboard.canopy.example.com/assets/app-a1b2.js
-  ▼
-canopy-gateway  (apps/gateway/src/index.ts)
-  │  1. Parse <slug> (and optional pinned version) from the hostname
-  │  2. Enforce auth — OneLogin session cookie, or client-password cookie
-  │  3. Rewrite path → /data/v1/assets/<path>  (+ ?v=<n> if pinned),
-  │     stamping X-Canopy-Project: <slug> + an internal JWT vouching for it
-  ▼  env.API.fetch(...)  (service binding, no public hop)
-canopy-api  (apps/api/src/routes/assets.ts)
-  │  4. Resolve the project from the stamp + which version is live
-  │  5. Sanitize the asset path; directory index, else SPA fallback
-  │  6. R2 GET  deploys/<project-id>/<version>/<path>
-  ▼
-R2 bucket "canopy-assets"
-```
+When a path doesn't match a file, Canopy serves your `index.html` instead of a 404. That's what makes client-side routing work: someone can bookmark
+`/reports/42`, reload it, and your app boots and handles the route.
 
-### 1–3. Gateway: hostname, auth, path rewrite
+The trade-off is that a **typo'd asset also gets `index.html`** rather than an
+error. If a script or image comes back as your homepage HTML, you're looking at
+a wrong path, not a broken server.
 
-[`apps/gateway/src/index.ts`](../../apps/gateway/src/index.ts) is the front door
-for every `*.canopy.<domain>` request.
+## Caching, and why a new deploy shows up immediately
 
-- **Hostname → slug + version.** `parseHost()`
-  ([`index.ts`](../../apps/gateway/src/index.ts)) splits the first DNS label.
-  A plain `dashboard` resolves to that project's _live_ version; a
-  `v12-dot-dashboard` prefix pins version 12 of the **frontend only** — auth,
-  client access, and the data plane still resolve to the real project, so an old
-  build previews against _current_ data rather than forking it.
-- **Auth before any project bytes.** No asset is served unauthenticated. A
-  request must carry either a valid OneLogin session cookie (verified via a
-  shared `SESSION_SECRET`) or — on client-enabled projects — a scope-limited
-  client-password cookie. Missing both: client-enabled projects get the password
-  page ([`client.ts`](../../apps/gateway/src/client.ts)), everything else
-  redirects to OneLogin. Collaborators-only projects additionally turn
-  non-members away with a members-only page before any dispatch.
-- **Path rewrite + project stamp.** Once authorized, the gateway rewrites the
-  request to the data plane and forwards it over a **service binding**
-  (`env.API.fetch`), never a public URL
-  ([`index.ts`](../../apps/gateway/src/index.ts)). The URL carries no slug —
-  the project travels as a header the gateway vouches for:
+Two different rules, picked automatically:
 
-  ```ts
-  const assetUrl = new URL(request.url);
-  assetUrl.pathname = `/data/v1/assets${url.pathname}`;
-  if (version !== null) assetUrl.searchParams.set("v", String(version));
-  const assetRequest = new Request(assetUrl, request);
-  assetRequest.headers.delete("x-canopy-project");
-  assetRequest.headers.set("x-canopy-project", slug);
-  assetRequest.headers.set("x-canopy-internal", await createInternalJwt(env.SESSION_SECRET));
-  return env.API.fetch(assetRequest);
-  ```
+- **HTML always revalidates.** Browsers re-check it on every visit, so the
+  moment you deploy, people get the new build — no cache-busting dance, no
+  waiting.
+- **Assets cache for an hour.** JS, CSS, images, and fonts sit in the visitor's
+  browser, which is what keeps repeat visits fast.
 
-  The caller's cookie travels along, so canopy-api re-verifies it independently,
-  and canopy-api trusts the `X-Canopy-Project` stamp only when the accompanying
-  internal JWT verifies.
+This is the right shape for a normal build tool that puts a content hash in
+asset filenames (Vite does this by default) — the HTML that names them is
+always fresh, so a new deploy points at new files.
 
-`/_api/*` requests are handled separately, forwarded to the API before the
-session wall so the SDK gets JSON 401s instead of login HTML. The plane is the
-path: `/_api/control/v1/*` forwards untouched, `/_api/data/v1/*` gets the same
-project stamp as asset requests.
+## Deploys and rollbacks are instant
 
-### 4–6. API: version resolution, path sanitizing, R2 read
+Shipping a version doesn't copy or rebuild anything at serve time — the
+platform just points at the new one. A [rollback](https://docs.canopy.website/platform/deploys-and-rollbacks)
+is the same move in reverse, which is why it takes effect immediately rather
+than propagating for minutes.
 
-The serving handler is `GET /data/v1/assets/*` in
-[`apps/api/src/routes/assets.ts`](../../apps/api/src/routes/assets.ts).
+You can also preview an **older frontend against current data** by putting the
+version in the hostname — `v12-dot-<project>` serves build 12 while auth and all
+data still resolve to the real, current project. Handy for "when did this break?"
+without deploying anything.
 
-- **Project + status.** Resolves the project from the gateway's vouched stamp
-  only (`vouchedProject` — never a query string), via a cached
-  `ProjectSnapshot` from the `ProjectDirectory`
-  ([`src/directory.ts`](../../apps/api/src/directory.ts)) — the data plane
-  never queries the control database directly. Unknown → 404 placeholder;
-  paused (`status !== "active"`) → a "paused" placeholder page. Viewability is
-  company-wide by default; projects marked **collaborators-only**
-  (`members_only`) turn non-members away with a 403 placeholder
-  (`checkAppAccess`, [`src/access.ts`](../../apps/api/src/access.ts)).
-- **Which version.** `?v=<n>` pins an exact version (must exist in the
-  project's deploy history, else 404 — it never silently falls back to live);
-  otherwise the snapshot's `liveAssetVersion` is served, which falls back to
-  the max deployed version for legacy rows with a NULL pointer.
-- **Path → R2 key.** The tail after `/assets/` is sanitized (see Security)
-  and mapped to the R2 key `deploys/<project-id>/<version>/<path>`; the root
-  path serves `index.html`.
-- **Directory index + SPA fallback**: the exact asset is read first. On a
-  miss, an extensionless path is probed for its own directory index — `/feeds/`
-  serves `feeds/index.html` (multi-page static exports), and the slash-less
-  `/feeds` 301-redirects to `/feeds/` so the page's relative URLs resolve.
-  Only when no directory index exists does the request fall back to the root
-  `index.html`, so client-side routes (`/settings`, `/projects/42`) still all
-  resolve to the SPA entry point. Both the fallback `index.html` and the
-  per-path probe results are served from per-version caches (see
-  [Performance](#performance-review)), so a deep-linked route doesn't pay a
-  second R2 read on every request.
+## What a deploy may contain
 
-### How assets are stored & versioned
+- Up to **500 files** and **25 MB** in total.
+- An `index.html` — a bundle without one is rejected.
+- Each file's type is fixed at deploy time from its extension. Unknown
+  extensions are sent as a download rather than run as code.
 
-`canopy deploy` uses a two-step signed upload
-([`docs/09-plane-split.md`](../09-plane-split.md) D-d): the **control plane**
-authorizes the deploy (`POST /control/v1/projects/:slug/deploys`,
-[`deploys.ts`](../../apps/api/src/routes/deploys.ts)) and issues a short-lived
-signed grant; the CLI PUTs each file to the **data plane**
-(`PUT /data/v1/uploads/:grant`,
-[`data-plane.ts`](../../apps/api/src/routes/data-plane.ts)); a completion call
-(`POST …/deploys/:version/complete`) validates the staged bundle and records
-the version. Bundle bytes never transit the control plane.
+If you're over the file count, it's almost always un-bundled assets that a build
+step would combine; over the size limit, it's usually images or fonts that
+belong in [file storage](https://docs.canopy.website/sdk/files) instead of the bundle.
 
-- Each file is written to R2 at `deploys/<project-id>/<version>/<path>` with its
-  `contentType` stored as R2 `httpMetadata` by the upload endpoint.
-- The bucket is `canopy-assets`, bound as `ASSETS`
-  ([`apps/api/wrangler.main.jsonc`](../../apps/api/wrangler.main.jsonc)).
-- **Immutable, append-only versioning.** A deploy bumps the version and writes a
-  new prefix; the `deployments` row commits at completion _before_
-  `live_asset_version` moves, so a half-uploaded deploy is never served (an
-  abandoned grant leaves only unreferenced staged bytes). Rollback
-  (`POST …/deploys/:version/rollback`,
-  [`deploys.ts`](../../apps/api/src/routes/deploys.ts)) just repoints
-  `live_asset_version` at an existing version — instant, nothing copied, nothing
-  deleted, and any version can be made live again. Old versions keep their bytes
-  and their identity, which is what makes `v<n>-dot-` preview hosts work.
-- Project deletion purges the whole `deploys/<project-id>/` prefix (plus blobs
-  and snapshots) so no R2 residue remains
-  ([`projects.ts`](../../apps/api/src/routes/projects.ts)).
+## What this rules out
 
-The browser SDK itself is served by the platform, not from a deploy bundle:
-`GET /_api/data/v1/sdk.js` returns an inlined bundle
-([`data-plane.ts`](../../apps/api/src/routes/data-plane.ts)) so scaffolded
-projects need no `npm install`.
+- **Server-side rendering.** No per-request HTML, no server components
+  resolved at request time, no incremental regeneration. Render in the browser,
+  or move the work into a backend route under `/api/*`.
+- **Redirects and rewrites as configuration.** There's no routing config file;
+  handle it in your app, or in your backend.
+- **Serving from anywhere but your build output.** If you want a file to be
+  reachable, deploy it, or put it in [file storage](https://docs.canopy.website/sdk/files) and hand out a
+  signed link.
 
----
-
-## Security review
-
-### What's solid
-
-- **Nothing is public.** Every asset request passes the gateway auth wall
-  (OneLogin session or client-password cookie) before any project bytes are
-  read, and the gateway→API hop is a private service binding, not an internet
-  URL. This is the north-star "never public URLs" guarantee.
-- **Path-traversal defense.** `safeAssetPath()`
-  ([`assets.ts`](../../apps/api/src/routes/assets.ts)) rejects on both
-  ingest (the upload endpoint) and serve: strips a leading `./` or `/`, then
-  rejects empty paths, paths over 512 chars, and any path containing `\`, `//`,
-  `\0`, or a `.`/`..`/empty segment. A malicious key can't escape the
-  `deploys/<project-id>/<version>/` prefix, and one project can never read
-  another's bytes because the prefix is keyed by the resolved project id.
-- **Tenant isolation by key prefix and by stamp.** The R2 key always embeds the
-  resolved `project.id`, so cross-project reads are structurally impossible even
-  if a path slipped through. Serving resolves its project from the gateway's
-  vouched `X-Canopy-Project` stamp alone — never a query parameter — so a
-  crafted query string can't render one project's pages under another's host.
-- **Content-Type is fixed at deploy time**, from an allowlist keyed by extension
-  (`contentTypeFor()`, [`assets.ts`](../../apps/api/src/routes/assets.ts)),
-  and stored as R2 metadata by the upload endpoint. Serving echoes that stored
-  type; unknown extensions become `application/octet-stream` (download, not
-  execute). The type is never derived from request input at serve time.
-- **Deploy bundle limits.** Max 500 files and 25 MB total
-  ([`storage-keys.ts`](../../apps/api/src/storage-keys.ts)), enforced per file
-  at upload and re-checked over the staged inventory at completion; a bundle
-  must contain `index.html` or completion is rejected — bounds the blast radius
-  of a bad upload. Upload grants are HMAC-signed, project- and version-bound,
-  and expire after 15 minutes ([`upload-grant.ts`](../../apps/api/src/upload-grant.ts)).
-- **Password page escapes untrusted input.** `escapeHtml()` and the same-site
-  `safeLocalPath()`/`safeReturnTo()` guards prevent reflected-XSS and open-redirect
-  via the `returnTo` parameter
-  ([`client.ts`](../../apps/gateway/src/client.ts),
-  [`index.ts`](../../apps/gateway/src/index.ts)).
-- **Version pinning can't leak data.** A `v<n>-dot-` host pins only _which
-  frontend build_ is served; auth, client-access, and all `/_api` data-plane
-  calls resolve to the real project (the stamp names the real slug),
-  so an old build cannot be used to read a different project's data.
-
-### Gaps / things to weigh
-
-These are observations, not known incidents — worth a conscious decision:
-
-1. **No hardening response headers.** Served assets carry `content-type`, `etag`,
-   and `cache-control` only ([`assets.ts`](../../apps/api/src/routes/assets.ts)).
-   There is **no** `X-Content-Type-Options: nosniff`, no `Content-Security-Policy`,
-   no `X-Frame-Options`/`frame-ancestors`, no `Referrer-Policy`, and no HSTS. For
-   an app platform serving arbitrary user HTML/JS on shared `*.canopy.<domain>`
-   subdomains, the most impactful additions are:
-   - `X-Content-Type-Options: nosniff` — cheap, prevents MIME-sniffing of e.g. a
-     user-uploaded file into script.
-   - `frame-ancestors`/`X-Frame-Options` — clickjacking, and stops one canopy
-     subdomain from framing another.
-   - A default `Content-Security-Policy` (even a permissive one) as a baseline.
-     Note projects run against a shared cookie domain, so cross-subdomain
-     concerns (cookie scoping, framing) matter more here than on an isolated
-     site.
-2. **`text/html` is served for deployed HTML with the session cookie present.**
-   That's by design (auth-gated apps), but it means any XSS in a deployed project
-   runs on a `*.canopy.<domain>` origin that shares the session-cookie domain.
-   The session cookie's flags (HttpOnly/SameSite/Secure) in
-   [`session.ts`](../../apps/gateway/src/session.ts) are the mitigation to keep an
-   eye on; per-project origin isolation would be the stronger fix.
-3. **SPA fallback returns `index.html` with 200 for unknown paths**, including
-   things that look like missing assets (`/assets/typo.js` → HTML). That's normal
-   SPA behavior but can mask 404s and, combined with #1, is another reason
-   `nosniff` matters (an HTML body served where a script was expected).
-4. **Serving is company-wide readable by default.** Any authenticated monk can
-   view any active project unless it opts into collaborators-only
-   (`members_only`, enforced in [`assets.ts`](../../apps/api/src/routes/assets.ts)
-   via `checkAppAccess`). The default is an intentional product decision (see
-   docs/02-decisions.md), not a bug — but it means "authenticated" ≠
-   "authorized for this specific project" on the read path unless the project
-   tightens it.
-
----
-
-## Performance review
-
-### What helps
-
-- **Split caching policy by type** ([`assets.ts`](../../apps/api/src/routes/assets.ts)):
-
-  ```ts
-  "cache-control": type.startsWith("text/html")
-    ? "no-cache"                 // HTML always revalidates → new deploys show up
-    : "private, max-age=3600",   // hashed subresources cache for 1h
-  ```
-
-  HTML revalidates so a fresh deploy is picked up immediately; hashed JS/CSS/font
-  assets cache in the browser for an hour. This is the right shape for a
-  content-hashed SPA build.
-
-- **ETags** (`"v<version>-<path>"`, [`assets.ts`](../../apps/api/src/routes/assets.ts))
-  give a stable validator per version+path, so revalidation of `no-cache` HTML
-  can come back as a cheap `304`. Because the etag encodes the version, a rollback
-  or new deploy changes the validator and busts caches correctly.
-- **Instant deploys and rollbacks.** Serving reads a pointer
-  (`live_asset_version`); deploy/rollback move the pointer without copying bytes,
-  so there's no propagation delay and no rebuild.
-- **Service-binding hop.** Gateway→API is an in-Cloudflare service binding, not a
-  public fetch, so there's no extra internet round-trip or TLS handshake between
-  the two Workers.
-
-### Bottlenecks / opportunities
-
-1. **`max-age=3600` is modest for hashed assets.** Content-hashed filenames (the
-   Vite default) can safely use `public, max-age=31536000, immutable`. The current
-   value is `private` (see #2) and only an hour, so returning visitors refetch
-   more than necessary. Consider keying on filename hash pattern or a deploy-time
-   flag to mark truly immutable assets.
-2. **`private` prevents any shared/edge caching.** Because assets are auth-gated
-   and served `private`, they can't be cached by Cloudflare's CDN or any shared
-   proxy — every cache miss goes Worker→R2. For an auth-walled platform that's a
-   deliberate trade (privacy over edge-cache hit rate), but it means R2 latency is
-   on the critical path for every uncached request. If per-project caching is ever
-   wanted, the Cache API keyed by (project, version, path) inside the Worker would
-   let you cache without making anything public.
-3. **No compression / `Content-Encoding`.** The handler streams R2 bytes as-is
-   with no gzip/brotli negotiation and ignores `Accept-Encoding`. Cloudflare may
-   apply compression at the edge for eligible content types, but nothing is stored
-   pre-compressed and the Worker doesn't negotiate it. For large JS bundles,
-   storing brotli-precompressed variants (or relying on and verifying edge
-   compression) is worth measuring.
-4. **Range requests / streaming media.** The handler returns the full R2 object
-   body and doesn't honor `Range`. Fine for a bundled SPA; if projects ever serve
-   large video/audio, add `Range` support (R2 supports ranged `get`).
-
-### Addressed — in-worker caches
-
-Two former bottlenecks are now handled by best-effort, per-isolate caches
-(a performance layer only — never a source of truth; a cold isolate just reads
-D1/R2):
-
-- **SPA fallback no longer double-reads R2.** The serve path reads the exact
-  asset once; on a miss it falls back to `index.html` served from a per-`(project,
-version)` cache ([`asset-cache.ts`](../../apps/api/src/asset-cache.ts)). Because a
-  deployed version's bytes are immutable, that entry is cached indefinitely
-  (count-bounded), so the second R2 read is paid **once per version**, not once
-  per deep-linked route. Verified by a test that serves three client routes and
-  asserts a single `index.html` read.
-- **Project state is cached per slug** as a `ProjectSnapshot` in the
-  `ProjectDirectory` ([`src/directory.ts`](../../apps/api/src/directory.ts) —
-  the generalization of the old metadata cache), sparing the hot path its
-  control-DB queries. Since this data _does_ change, deploy, rollback, and
-  delete call `invalidateSnapshot()` so a write is reflected immediately on the
-  same isolate; a short TTL (5 s) is only a backstop for a write that lands on
-  a different isolate than the next read.
-
----
-
-## Quick reference
-
-| Concern                     | Where                                                                          | Notes                                                                  |
-| --------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| Front door / auth / routing | [`apps/gateway/src/index.ts`](../../apps/gateway/src/index.ts)                 | Hostname→slug, auth wall, `/data/v1/assets` rewrite + project stamp    |
-| Client-password page        | [`apps/gateway/src/client.ts`](../../apps/gateway/src/client.ts)               | HTML-escaped, same-site returnTo                                       |
-| Asset serve handler         | [`apps/api/src/routes/assets.ts`](../../apps/api/src/routes/assets.ts)         | Version resolve, path sanitize, SPA fallback, headers                  |
-| Project snapshots           | [`apps/api/src/directory.ts`](../../apps/api/src/directory.ts)                 | `ProjectDirectory` cache (5 s TTL), invalidated on write               |
-| index.html cache            | [`apps/api/src/asset-cache.ts`](../../apps/api/src/asset-cache.ts)             | Per-version, immutable bytes, count-bounded                            |
-| Path sanitizing             | [`assets.ts`](../../apps/api/src/routes/assets.ts)                             | `safeAssetPath()` — traversal defense, shared with the upload endpoint |
-| Content-Type allowlist      | [`assets.ts`](../../apps/api/src/routes/assets.ts)                             | Fixed at deploy, stored in R2 metadata                                 |
-| Deploy authorize / complete | [`apps/api/src/routes/deploys.ts`](../../apps/api/src/routes/deploys.ts)       | Signed grant, 500 files / 25 MB, pointer moves last                    |
-| Upload bytes                | [`apps/api/src/routes/data-plane.ts`](../../apps/api/src/routes/data-plane.ts) | `PUT /data/v1/uploads/:grant`, grant is the credential                 |
-| Rollback                    | [`deploys.ts`](../../apps/api/src/routes/deploys.ts)                           | Repoints `live_asset_version`                                          |
-| R2 bucket binding           | [`apps/api/wrangler.main.jsonc`](../../apps/api/wrangler.main.jsonc)           | `ASSETS` → `canopy-assets`                                             |
-| SDK serving                 | [`apps/api/src/routes/data-plane.ts`](../../apps/api/src/routes/data-plane.ts) | `/_api/data/v1/sdk.js`, `public, max-age=300`                          |
+Porting an app that assumed a server? [Porting a Next.js app](https://docs.canopy.website/guides/porting-nextjs)
+walks through the restructure.

package/dist/{docs-C2D7__Iz.mjs → docs-c0CdeBxh.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-B-aXVcQu.mjs";
+import { t as version } from "./package-BuwV_mje.mjs";
 import { n as siteConfig } from "./site-BFaWfSVu.mjs";
 import { i as latestKnownVersion, r as compareSemver } from "./version-check-CcsA1QjI.mjs";
 import { r as reportErrors } from "./ui--atbZ-TM.mjs";

package/dist/{feedback-BvkCjS-g.mjs → feedback-QhD8k6Ph.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-B-aXVcQu.mjs";
+import { t as version } from "./package-BuwV_mje.mjs";
 import { a as projectDirArgs, c as resolveProject, d as tryResolveProject, n as siteConfig, u as tryReadCanopyJson } from "./site-BFaWfSVu.mjs";
 import { c as apiDownload, l as apiRequest, r as reportErrors, t as formatDateTime, u as apiUpload } from "./ui--atbZ-TM.mjs";
 import { defineCommand } from "citty";
@@ -89,6 +89,10 @@ function firstLine(body) {
 	const line = body.split("\n")[0] ?? "";
 	return line.length > 72 ? `${line.slice(0, 71)}…` : line;
 }
+/** List label: the AI-written title when there is one, else the first line. */
+function itemLabel(item) {
+	return firstLine(item.title || item.body);
+}
 function printItems(items) {
 	if (items.length === 0) {
 		console.log("No matching feedback items.");
@@ -97,7 +101,7 @@ function printItems(items) {
 	for (const item of items) {
 		const comments = item.comment_count ? `  💬${item.comment_count}` : "";
 		const shots = item.attachment_count ? `  📎${item.attachment_count}` : "";
-		console.log(`${item.id}  ${item.status}  ${item.kind}  ${firstLine(item.body)}${comments}${shots}`);
+		console.log(`${item.id}  ${item.status}  ${item.kind}  ${itemLabel(item)}${comments}${shots}`);
 	}
 }
 const listCommand = defineCommand({
@@ -153,6 +157,7 @@ const showCommand = defineCommand({
 			return;
 		}
 		const { item, comments } = detail;
+		if (item.title) console.log(item.title);
 		console.log(`${item.kind} · ${item.status} · via ${item.source} · ${formatDateTime(item.created_at)}`);
 		console.log(`reported by ${item.reporter_name || item.reporter_email || "unknown"}` + (item.deployment_id ? ` on ${item.deployment_id}` : "") + (item.channel === "staging" ? " (staging)" : ""));
 		console.log(`\n${item.body}\n`);
@@ -276,7 +281,7 @@ const mineCommand = defineCommand({
 			console.log("You haven't filed any reports.");
 			return;
 		}
-		for (const item of items) console.log(`${item.id}  ${item.status}  ${item.kind}  [${item.project_slug}]  ${firstLine(item.body)}`);
+		for (const item of items) console.log(`${item.id}  ${item.status}  ${item.kind}  [${item.project_slug}]  ${itemLabel(item)}`);
 	})
 });
 const reportCommand = defineCommand({

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as version } from "./package-B-aXVcQu.mjs";
+import { t as version } from "./package-BuwV_mje.mjs";
 import { r as siteHeaderLine, t as setInvocationProfile } from "./site-BFaWfSVu.mjs";
 import { a as notifyOfUpdate, o as runRefresh } from "./version-check-CcsA1QjI.mjs";
 import { defineCommand, runMain } from "citty";
@@ -60,14 +60,14 @@ const main = defineCommand({
 		description: "canopy — create and deploy vibecoded projects"
 	},
 	subCommands: {
-		login: () => import("./login-D-Ac_kFW.mjs").then((m) => m.loginCommand),
-		whoami: () => import("./login-D-Ac_kFW.mjs").then((m) => m.whoamiCommand),
-		logout: () => import("./login-D-Ac_kFW.mjs").then((m) => m.logoutCommand),
+		login: () => import("./login-BrEDKrb3.mjs").then((m) => m.loginCommand),
+		whoami: () => import("./login-BrEDKrb3.mjs").then((m) => m.whoamiCommand),
+		logout: () => import("./login-BrEDKrb3.mjs").then((m) => m.logoutCommand),
 		create: () => import("./projects-1r5387ui.mjs").then((m) => m.createCommand),
 		init: () => import("./projects-1r5387ui.mjs").then((m) => m.initCommand),
 		projects: () => import("./projects-1r5387ui.mjs").then((m) => m.projectsCommand),
 		delete: () => import("./projects-1r5387ui.mjs").then((m) => m.deleteCommand),
-		dev: () => import("./dev-DjkK-50R.mjs").then((m) => m.devCommand),
+		dev: () => import("./dev-D7v7WK9O.mjs").then((m) => m.devCommand),
 		deploy: () => import("./deploy-DCggsLD7.mjs").then((m) => m.deployCommand),
 		promote: () => import("./deploy-DCggsLD7.mjs").then((m) => m.promoteCommand),
 		staging: () => import("./staging-CdpV2YHB.mjs").then((m) => m.stagingCommand),
@@ -76,13 +76,13 @@ const main = defineCommand({
 		token: () => import("./token-C8Bmzwfl.mjs").then((m) => m.tokenCommand),
 		egress: () => import("./egress-BhbQfjjV.mjs").then((m) => m.egressCommand),
 		schedule: () => import("./schedule-DK_Cv6Xf.mjs").then((m) => m.scheduleCommand),
-		feedback: () => import("./feedback-BvkCjS-g.mjs").then((m) => m.feedbackCommand),
+		feedback: () => import("./feedback-QhD8k6Ph.mjs").then((m) => m.feedbackCommand),
 		db: () => import("./db-TaSLpQZ5.mjs").then((m) => m.dbCommand),
-		usage: () => import("./usage-CRpVLLi6.mjs").then((m) => m.usageCommand),
+		usage: () => import("./usage-C1-cvS2-.mjs").then((m) => m.usageCommand),
 		open: () => import("./open-D7f1wNn3.mjs").then((m) => m.openCommand),
-		docs: () => import("./docs-C2D7__Iz.mjs").then((m) => m.docsCommand),
-		skill: () => import("./skill-CqiSkac0.mjs").then((m) => m.skillCommand),
-		upgrade: () => import("./upgrade-CpUCVTrN.mjs").then((m) => m.upgradeCommand),
+		docs: () => import("./docs-c0CdeBxh.mjs").then((m) => m.docsCommand),
+		skill: () => import("./skill-BvoYCIKk.mjs").then((m) => m.skillCommand),
+		upgrade: () => import("./upgrade-0lmdjvom.mjs").then((m) => m.upgradeCommand),
 		logs: () => import("./logs-Beqz--Df.mjs").then((m) => m.logsCommand)
 	}
 });

package/dist/{local-CKRZur_5.mjs → local-CsSP4Vpt.mjs}

@@ -1,6 +1,6 @@
 import { s as apiDataRequest } from "./ui--atbZ-TM.mjs";
-import { n as META_COLUMNS, r as blobRouter, t as dbRouter } from "./src-Bu4Ze32I.mjs";
-import { n as rewriteApiPath } from "./dev-DtEwiNYi.mjs";
+import { n as META_COLUMNS, r as blobRouter, t as dbRouter } from "./src-BKKAEkbH.mjs";
+import { n as rewriteApiPath } from "./dev-CNqx_53I.mjs";
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";