@terreno/mcp 57.18.0 → 57.20.0

package/src/docs/versioned/57.18.0/implementationPlans/public-roadmap-github.md

@@ -0,0 +1,205 @@
+# Implementation Plan: Public Roadmap on GitHub
+
+**Status:** Complete
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1004
+**Priority:** High
+**Effort:** Small batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`oss-governance-baseline`](oss-governance-baseline.md) (issue templates land there)
+**RTK deprecation flag:** None — process and metadata only. Safe to implement before PR #869.
+
+## Goal
+
+Run Terreno's roadmap in public on GitHub while keeping Linear as the internal execution tracker. Outside users need to see what is planned, argue about priorities, and file well-shaped requests; Flourish engineers need to keep sprinting in Linear without double-entry.
+
+The design principle: **one direction of truth per artifact.** Public discussion and roadmap state live on GitHub. Sprint execution, estimates, and assignees live in Linear. IPs in `docs/implementationPlans/` remain the design source of truth for both.
+
+## Non-Goals
+
+- Migrating Flourish's internal work off Linear.
+- Building a custom sync service between Linear and GitHub.
+- Publishing internal Flourish product roadmap items that happen to touch Terreno.
+- Public sprint planning or estimates.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Decision |
+|---|----------|
+| R1 | Target **release version** on the roadmap (`0.28`, `0.29`, `Future`) — no calendar dates |
+| R2 | GitHub Project board + **generated `ROADMAP.md`** |
+| R3 | Linear GitHub sync on issues labeled **`tracked`** (one-way GitHub → Linear) |
+| R4 | **Maintainers only** open board items; users file Ideas discussions |
+| R5 | **One tracking issue per IP**, opened manually when IP reaches Approved |
+| R6 | **Post-moderated** Discussions |
+| R7 | Lightweight **RFC** discussion category → graduates to IP |
+
+## Architecture
+
+### Three surfaces, one flow
+
+```mermaid
+flowchart LR
+  subgraph public ["Public (GitHub)"]
+    D["Discussions<br/>Ideas / Q&A / RFC"]
+    I["Issues<br/>triaged work"]
+    P["Project: Terreno Roadmap"]
+    RM["ROADMAP.md<br/>generated"]
+  end
+  subgraph design ["Design (repo)"]
+    IP["docs/implementationPlans/*.md"]
+  end
+  subgraph internal ["Internal"]
+    L["Linear"]
+  end
+  D -->|"maintainer promotes"| I
+  I -->|"triage: add to board"| P
+  P -->|"nightly generate"| RM
+  I -->|"label: tracked"| L
+  IP -->|"Approved → tracking issue"| I
+  D -->|"RFC accepted"| IP
+```
+
+### Discussion categories
+
+| Category | Format | Purpose | Who posts |
+|----------|--------|---------|-----------|
+| **Announcements** | Announcement | Releases, breaking changes, deprecations (including the RTK → syncdb deprecation), launch posts | Maintainers only |
+| **Q&A** | Question / Answer | "How do I…" support questions. Answers marked accepted; recurring ones graduate into `docs/how-to/` | Anyone |
+| **Ideas** | Open-ended | Feature requests before they are shaped. The intake funnel — nothing goes straight to an issue | Anyone |
+| **RFCs** | Open-ended | Proposals that change public API or add a package. Graduates into an IP when accepted | Anyone, template-guided |
+| **Show and tell** | Open-ended | Apps built with Terreno. Social proof, and a source of real-world friction reports | Anyone |
+| **Agents & AI** | Open-ended | MCP setup, skills, agent workflows, prompt patterns. Deliberately separate — it is the differentiator and deserves a visible home | Anyone |
+| **Docs feedback** | Open-ended | Per-page feedback; linked from every docs page footer | Anyone |
+
+Category ordering in the UI should be: Announcements, Q&A, Ideas, Agents & AI, RFCs, Show and tell, Docs feedback.
+
+### Project board
+
+One org- or repo-level Project named **Terreno Roadmap**, board layout, grouped by `Status`.
+
+**Fields**
+
+| Field | Type | Values | Notes |
+|-------|------|--------|-------|
+| `Status` | single select | `Inbox`, `Shaping`, `Planned`, `In progress`, `In review`, `Shipped`, `Declined` | `Inbox` = triaged but not committed |
+| `Area` | single select | `api`, `ui`, `syncdb`, `auth`, `admin`, `ai`, `mcp`, `docs`, `deploy`, `examples`, `dx` | Mirrors package boundaries plus cross-cutting areas |
+| `Target` | single select | `0.28`, `0.29`, `Next`, `Future` | Per R1; add versions as releases approach |
+| `IP` | text | e.g. `web-ssr-and-admin-spa` | Slug of the IP file, empty if no IP yet |
+| `Impact` | single select | `Breaking`, `Feature`, `Improvement`, `Fix` | Drives changelog grouping |
+| `Community interest` | number | 👍 count, refreshed on triage | Makes prioritization legible |
+
+**Views**
+
+1. **Roadmap** (board, grouped by `Status`, filtered to `Status != Declined`) — the default public view.
+2. **By area** (table, grouped by `Area`) — for contributors looking for something to pick up.
+3. **Next release** (table, filtered to `Target = <current+1>`) — what is actually landing.
+4. **Needs shaping** (table, filtered to `Status = Shaping`) — where community input changes outcomes.
+
+### Label taxonomy
+
+Keep it small enough to be used consistently.
+
+| Prefix | Labels | Purpose |
+|--------|--------|---------|
+| `area:` | `area:api`, `area:ui`, `area:syncdb`, `area:auth`, `area:admin`, `area:ai`, `area:mcp`, `area:docs`, `area:deploy`, `area:examples`, `area:dx` | Matches the `Area` project field |
+| `type:` | `type:bug`, `type:feature`, `type:docs`, `type:chore`, `type:rfc` | Set by issue forms where possible |
+| `status:` | `status:needs-triage`, `status:needs-info`, `status:blocked`, `status:wontfix` | Workflow state that is not board state |
+| (bare) | `good first issue`, `help wanted`, `breaking`, `tracked`, `deprecation` | `tracked` triggers the Linear sync; `deprecation` marks RTK-migration work |
+
+### Linear bridge
+
+- Linear's GitHub integration is configured to import GitHub issues labeled `tracked` into the Terreno Linear team.
+- Direction: GitHub → Linear for creation and title/description; status is **not** synced automatically. When a Linear issue closes, the engineer closes the GitHub issue in the same PR (`Fixes #NNN`), which moves the board to `Shipped`.
+- Linear issues created internally that will become public work get a GitHub issue opened manually and the Linear URL pasted into it. No automation in that direction.
+- Internal-only Linear work is never mirrored.
+
+Rationale: two-way status sync between trackers reliably produces confusing loops. One-way intake plus `Fixes #NNN` on merge gives correct public state with no maintenance.
+
+### Automation
+
+Three GitHub Actions workflows:
+
+1. **`roadmap-generate.yml`** — on a schedule and on Project item changes, query the Project via the GraphQL API and regenerate `ROADMAP.md` (grouped by `Target`, then `Area`, with links to issues and IPs). Commits only when the content changes.
+2. **`triage.yml`** — on issue open: apply `status:needs-triage`, and apply the `area:*` label derived from the issue form's package dropdown.
+3. **`discussion-to-issue.yml`** — optional; when a maintainer adds the `promote` label to a Discussion (or comments `/promote`), open a linked issue pre-filled from the discussion body. Skip in v1 if the GraphQL surface proves fiddly; manual promotion is acceptable.
+
+## Models
+
+None (GitHub metadata only).
+
+## APIs
+
+GitHub GraphQL API (`ProjectV2` queries) is used read-only by `roadmap-generate.yml`. Requires a token with `project: read` and `contents: write`; use the built-in `GITHUB_TOKEN` if org settings permit Projects access, otherwise a fine-grained PAT stored as a secret and validated at job start per the repo's required-secret-validation convention.
+
+## Notifications
+
+None beyond GitHub's own subscriptions. Announcements category posts should be the release channel; the `release` skill gains a step to post one for releases with breaking changes.
+
+## UI
+
+- `ROADMAP.md` at the repo root, linked from `README.md` and the docs site sidebar.
+- A "Discuss this page" footer link on docs pages pointing at the Docs feedback category (implemented in the Docusaurus theme config).
+
+## Phases
+
+1. **Discussions** — enable, create categories, seed each with a pinned intro post, add the RFC template.
+2. **Project board** — create the Project, fields, and views; backfill items from the IPs in this program.
+3. **Labels and triage** — create the label set, delete unused defaults, add `triage.yml`.
+4. **Roadmap generation** — `ROADMAP.md` + `roadmap-generate.yml`, link from README and docs site.
+5. **Linear bridge** — configure the integration, document the process in `CONTRIBUTING.md`, and record the rules in a maintainer doc.
+
+## Feature Flags & Migrations
+
+None. Existing open issues need a one-time triage pass to apply the new labels and land on the board (Task 3.3).
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- Public voting/prioritization beyond 👍 reactions.
+- Automated changelog generation from board state.
+- A status page or uptime dashboard for the hosted MCP server.
+- Contributor recognition automation (all-contributors bot).
+
+## Files to Create / Modify
+
+**Create**
+
+- `ROADMAP.md`
+- `.github/DISCUSSION_TEMPLATE/rfc.yml`
+- `.github/DISCUSSION_TEMPLATE/ideas.yml`
+- `.github/workflows/roadmap-generate.yml`
+- `.github/workflows/triage.yml`
+- `docs/explanation/roadmap-process.md`
+- `scripts/generate-roadmap.ts`
+
+**Modify**
+
+- `README.md` (link `ROADMAP.md` and Discussions)
+- `CONTRIBUTING.md` (intake flow: Discussions → issue → board; RFC path)
+- `website/docusaurus.config.ts` (docs feedback footer link, roadmap sidebar entry)
+- `.rulesync/skills/release/SKILL.md` (post an Announcements discussion for breaking releases)
+- `.github/ISSUE_TEMPLATE/*.yml` (add `type:` labels via the `labels:` key)
+
+## Task List
+
+See [`docs/tasks/public-roadmap-github.md`](../tasks/public-roadmap-github.md).
+
+## Acceptance Criteria
+
+- [ ] All seven Discussion categories exist with the specified formats and a pinned intro post each.
+- [ ] The **Terreno Roadmap** Project exists with the six fields and four views described above.
+- [ ] Every IP whose `**Status:**` header is Approved or later has a tracking issue on the board with its `IP` field set to the IP slug.
+- [ ] The label set matches the taxonomy table; no unused GitHub default labels remain.
+- [ ] `bun run scripts/generate-roadmap.ts` produces `ROADMAP.md` grouped by `Target` then `Area`, and `roadmap-generate.yml` commits it only when changed.
+- [ ] Opening a new issue applies `status:needs-triage` and the correct `area:*` label automatically.
+- [ ] Adding `tracked` to a GitHub issue creates a corresponding Linear issue; closing the Linear issue does **not** silently change GitHub state.
+- [ ] `CONTRIBUTING.md` documents the intake flow and the RFC path in under 30 lines.
+- [ ] `docs/explanation/roadmap-process.md` explains the GitHub/Linear split, including why status is not two-way synced.
+- [ ] Every docs page shows a working "Discuss this page" link.

package/src/docs/versioned/57.18.0/implementationPlans/rate-limiting.md

@@ -0,0 +1,212 @@
+# Implementation Plan: API rate limiting
+
+**Status:** Complete  
+**Branch:** `cursor/api-rate-limiting-d03a`  
+**Owner:** —  
+**Created:** 2026-08-30  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1187 (this feature **closes** that issue; implementation PRs use `Fixes #1187`)  
+**Task list:** [rate-limiting.md](../tasks/rate-limiting.md)  
+**Depends on:** —  
+**RTK deprecation flag:** None  
+
+## Goal
+
+Opt-in HTTP rate limiting on `TerrenoApp` covering modelRouter and the other framework HTTP surfaces (JWT login/signup/refresh, Better Auth credential routes, GitHub OAuth, admin, AI HTTP, in-process `POST /mcp`, custom OpenAPI routes). Default store is in-process memory. Operators may switch to Redis or Mongo for a shared bucket across replicas. Login uses a stricter `auth` bucket than general CRUD. Terreno **58** flips the default to on (documented now; not this release).
+
+## Non-Goals
+
+- Default-on in this release (Terreno 58).
+- Framework auto-read of `RATE_LIMIT_ENABLED` (apps may pass `process.env` into `rateLimit` themselves).
+- Per-org keys (`org-management-ui` is not shipped).
+- Replacing the existing sync mutation limiter in `api/src/sync/syncBatch.ts` (per-user in-process mutation budget + `rate_limited` nacks).
+- Hosted `@terreno/mcp` JSON-RPC rate limiting (`ai-dev-loop-boost` Task 5.3).
+- example-frontend / `@terreno/rtk` UI for 429.
+- IETF `RateLimit` headers on successful responses.
+- Account lockout / captcha.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Default | **Off.** `rateLimit` omitted or `undefined` → no limiter. Terreno 58 defaults to on; record that in how-to + upgrade notes now. |
+| Enable API | Object only: `rateLimit: { store?, limits?, trustProxy?, skip? }`. Empty `{}` enables defaults. Framework does **not** read an enable env var. |
+| Coverage | Global Express middleware after auth populates `req.user`. Skip `/health`, `/openapi.json`, `/swagger`. Keep sync mutation limiter and realtime subscribe caps as-is. |
+| Key | Authenticated `req.user.id` (or `_id`), else Express `req.ip`. |
+| Auth vs API | `auth`: 20 requests / 15 min. `api`: 600 / 15 min. Overridable via `rateLimit.limits`. |
+| Auth paths | JWT `POST /auth/login`, `/signup`, `/refresh_token`; GitHub OAuth start/callback; Better Auth sign-in/sign-up/forget-password under `basePath` (default `/api/auth`); future password-reset/OTP routes join this list when they land. `/auth/me` is `api`. |
+| Proxy | When limiter is enabled, `app.set("trust proxy", 1)` unless `rateLimit.trustProxy` is set (`false` \| hop count \| IP/subnet list). Key unauthenticated traffic with `req.ip` only — never parse `X-Forwarded-For` / `Forwarded` unless trust proxy is on. |
+| Stores | `memory` (default, per process) \| `redis` (`VALKEY_URL` then `REDIS_URL`, same as realtime) \| `mongo` (app mongoose connection, `rateLimitHits` collection + TTL). |
+| 429 | `APIError` status 429, `code: "rate-limit-exceeded"`, `title: "Too many requests"`. Headers: `Retry-After` plus IETF `RateLimit` / `RateLimit-Policy` (`limit`, `remaining`, `reset`) on the 429 only. |
+| Frontend | No client work this slice. |
+| Tests | Burst tests enable the limiter in-process. Existing suites stay green because default is off. |
+
+## Architecture
+
+```
+TerrenoApp({ rateLimit: { store, limits, trustProxy } })
+  → after JWT / Better Auth session middleware
+  → skip health / openapi / swagger
+  → policy = auth path ? auth : api
+  → key = userId || req.ip
+  → store.consume(key, policy)
+  → next() or APIError 429 + headers
+```
+
+Mount **after** `setupAuth` / Better Auth session so authenticated CRUD shares a user bucket. Login has no user yet → IP key (correct for password spray).
+
+Do not add per-route middleware on each `modelRouter` verb. The `TODO add rate limit` on `GET /` in `api/src/api.ts` is deleted once global middleware exists.
+
+### Config shape
+
+```typescript
+interface RateLimitLimits {
+  windowMs?: number; // default 15 * 60 * 1000
+  authMax?: number;  // default 20
+  apiMax?: number;   // default 600
+}
+
+interface RateLimitOptions {
+  store?: "memory" | "redis" | "mongo";
+  limits?: RateLimitLimits;
+  trustProxy?: boolean | number | string | string[];
+  skip?: (req: Request) => boolean; // extra skips; health/openapi/swagger always skipped
+}
+```
+
+`TerrenoAppOptions.rateLimit?: RateLimitOptions`.
+
+App-owned env example (not implemented inside `@terreno/api`):
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "redis"} : undefined,
+});
+```
+
+### Stores
+
+| Store | When | Semantics |
+|-------|--------|-----------|
+| `memory` | default | Per Node process. Document Cloud Run: N instances = N independent buckets. |
+| `redis` | `store: "redis"` | Optional peer / lazy import matching realtime (`VALKEY_URL` \|\| `REDIS_URL`). Fail startup if URL missing. |
+| `mongo` | `store: "mongo"` | Uses existing mongoose connection. Collection `rateLimitHits` with TTL on window expiry. Not a public modelRouter model. |
+
+Prefer a small `RateLimitStore` interface (`consume({key, max, windowMs}) → {allowed, remaining, resetAt}`) so Redis/Mongo adapters are testable without Express. `express-rate-limit` is allowed if the store interface still holds and 429 goes through `APIError`.
+
+### Skip list (always)
+
+- `GET /health` (and common aliases if already mounted, e.g. `/healthz`)
+- `GET /openapi.json`
+- `/swagger` prefix when Swagger is enabled
+
+Sync HTTP (`POST /sync/mutate`) is **not** skipped: it is `api` bucket HTTP *plus* the existing mutation nack limiter. That is intentional (HTTP flood vs mutation budget).
+
+### Trust proxy
+
+Express `req.ip` is the load-balancer address until `trust proxy` is set. Cloud Run is one hop (GFE). Default `1` when the limiter is on. Operators behind extra proxies set `trustProxy: 2` (or a subnet). `trustProxy: false` keeps the socket address (tests, local). Spoofing `X-Forwarded-For` without trust proxy must not change the key.
+
+## Models
+
+No public CRUD model. Mongo store may use an internal schema (`key`, `hits`, `expiresAt`) with field `description`s if it is a Mongoose model; otherwise a raw collection with a TTL index. Follow `mongoose-schema-safety` if a schema is added. No user-facing migration.
+
+## APIs
+
+| Method | Path | Policy |
+|--------|------|--------|
+| POST | `/auth/login` | auth |
+| POST | `/auth/signup` | auth |
+| POST | `/auth/refresh_token` | auth |
+| GET | `/auth/github`, `/auth/github/callback` | auth |
+| * | `{betterAuth.basePath}/sign-in/*`, `sign-up/*`, `forget-password` | auth |
+| GET/PATCH | `/auth/me` | api |
+| * | modelRouter, admin, AI HTTP, `POST /mcp` | api |
+| GET | `/health`, `/openapi.json` | skip |
+
+429 body is the existing JSONAPI `APIError` serializer (`TooManyRequestsError` name already mapped in `errors.ts`).
+
+## Notifications
+
+None.
+
+## UI
+
+None this slice. example-backend: commented or docs-only snippet showing how to enable; **do not** turn the limiter on in the default example server.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/how-to/rate-limiting.md` | **New.** Enable object, stores, trust proxy, auth vs api numbers, Terreno 58 default-on, memory vs replica warning. |
+| `docs/reference/api.md` | `rateLimit` on `TerrenoApp`; skip list; 429. |
+| `docs/reference/environment-variables.md` | Redis URLs reused; no new required enable env. |
+| `docs/explanation/authentication.md` | Replace “implement rate limiting” with the opt-in `auth` bucket. |
+| `docs/explanation/configuration-system.md` | Replace the fake `RATE_LIMIT_MAX` `express-rate-limit` snippet so it is not the HTTP limiter. |
+| `docs/explanation/roadmap-seed-issues.md` | IP + task URLs for `rate-limiting`. |
+| `mcp-server/src/docs/upgrades/` (next minor or a **58** stub section in how-to) | Default-on when Terreno 58 is cut; this slice documents the promise. |
+| `.rulesync/rules/api/00-api.mdc` | `rateLimit` option. |
+| `CHANGELOG.md` | Added opt-in rate limiting. |
+
+## Testing
+
+Tracer: `TerrenoApp` with `rateLimit: {}` → 21st `POST /auth/login` in 15 min → 429 + headers; 21st list GET still allowed until 601.
+
+Cases:
+
+- Default off: 100 logins succeed (no 429).
+- Auth bucket: 20 allowed, 21st 429; `api` still has remaining.
+- API bucket: 600 allowed, 601st 429 on a modelRouter list.
+- Skip: `/health` never 429.
+- Authenticated user: two IPs, same user, share `api` budget.
+- Unauthenticated: two users behind one IP share `auth` login budget.
+- `trustProxy: 1` + `X-Forwarded-For`: key is client IP; without trust proxy, spoofed header ignored.
+- Memory store isolation between keys.
+- Redis/Mongo: unit tests with fake store; optional integration if env present, skip otherwise.
+- Existing `api/` suite unchanged with limiter off.
+
+Skills: `backend-test-env` if any test mutates env (Redis URL). `mongoose-schema-safety` if Mongo store uses a schema.
+
+## Risks
+
+| Risk | Mitigation |
+|-------|-----------|
+| Default-on later breaks burst tests | 58 upgrade note + test helper `disableRateLimit` or omit option; current tests stay off. |
+| Memory store on Cloud Run | Docs: shared store required for a global bucket. |
+| Trust proxy spoofing | Never honor forwarded headers unless `trust proxy` is set. |
+| Auth path drift (Better Auth) | Central path table + tests against default `basePath`; configurable extra prefixes. |
+| Double limit with sync mutate | Documented; HTTP `api` + mutation nack are different units. |
+
+## Phases
+
+1. Store interface + memory + 429 + skip + auth/api classification + TerrenoApp mount (tracer).
+2. Redis + Mongo adapters.
+3. Trust-proxy tests + GitHub/Better Auth path coverage.
+4. Docs, changelog, rulesync, example-backend snippet, seed-issue links.
+
+## Files to Create / Modify
+
+| File | Role |
+|------|--------|
+| `api/src/rateLimit/*.ts` | Options, middleware, stores, path tables |
+| `api/src/terrenoApp.ts` | `rateLimit` option + mount + trust proxy |
+| `api/src/api.ts` | Remove list-GET TODO |
+| `api/src/index.ts` | Export types |
+| `api/src/rateLimit/*.test.ts` | Tracer + cases above |
+| `example-backend/src/server.ts` | Commented enable snippet |
+| Docs listed above | Same slice |
+
+## Task List
+
+[docs/tasks/rate-limiting.md](../tasks/rate-limiting.md)
+
+## Acceptance Criteria
+
+- [ ] Limiter off by default; existing `bun run api:test` does not 429 from this feature.
+- [ ] `rateLimit: {}` enforces auth 20 / api 600 per 15 min with documented keys.
+- [ ] `POST /auth/login` is on the auth bucket.
+- [ ] Redis and Mongo stores implement the same consume contract.
+- [ ] Trust proxy 1 + `req.ip` behind a forwarded-for header; spoofing ignored when trust is off.
+- [ ] 429 is `APIError` with `Retry-After` and `RateLimit` headers.
+- [ ] Docs how-to + reference + auth explanation + Terreno 58 default-on note exist.
+- [ ] Sync mutation limiter behavior unchanged (existing sync tests still pass).
+- [ ] Merging the implementation PR closes https://github.com/TerrenoLabs/terreno/issues/1187 (`Fixes #1187`).