@terreno/mcp 0.21.0

package/src/docs/versioned/0.19.0/explanation/ai-workflows.md

@@ -0,0 +1,270 @@
+# AI-Powered Workflows
+
+Understanding Terreno's autonomous AI workflows for continuous improvement.
+
+## Overview
+
+Terreno uses GitHub Actions with AI agents to maintain code quality, documentation, and developer experience. These workflows run automatically and create pull requests when improvements are needed.
+
+## Workflow Categories
+
+### Documentation Workflows
+
+#### Update Docs
+**Trigger:** Push to master  
+**Purpose:** Keeps documentation synchronized with code changes
+
+Analyzes code diffs after each merge to identify:
+- New or changed APIs, functions, classes
+- Missing or outdated documentation
+- Documentation gaps that need attention
+
+**Output:** Draft pull requests with documentation updates following the Diátaxis framework (tutorials, how-to guides, reference, explanation).
+
+**Philosophy:** Treats documentation gaps like failing tests — they must be fixed.
+
+#### Update Rules
+**Trigger:** Push to master  
+**Purpose:** Keeps AI assistant rules synchronized with codebase changes
+
+Maintains the single source of truth in `.rulesync/rules/` and ensures:
+- `.cursorrules` (Cursor IDE)
+- `.windsurfrules` (Windsurf IDE)
+- `AGENTS.md` (Claude Code, Copilot)
+- `.github/copilot-instructions.md` (GitHub Copilot)
+
+**Workflow:**
+1. Detects package changes, new APIs, or convention updates
+2. Updates source files in `.rulesync/rules/`
+3. Creates PR with instructions to run `bun run rules` to regenerate outputs
+4. Ensures `rulesync-check` CI passes
+
+**Key insight:** Rule files are code — they must be kept in sync with implementation.
+
+### Code Quality Workflows
+
+#### Daily JSDoc Improver
+**Trigger:** Daily schedule + push to master  
+**Purpose:** Systematically improves JSDoc documentation across the codebase
+
+**Two modes:**
+- **Targeted (on push):** Improves JSDoc for files changed in recent commits
+- **Systematic (daily):** Three-phase approach covering entire codebase
+
+**Output:** Draft PRs with improved JSDoc comments on exported functions, methods, and classes.
+
+#### Daily Test Improver
+**Trigger:** Daily schedule  
+**Purpose:** Enhances test coverage and test quality
+
+Analyzes test files and implementation to:
+- Add missing test cases
+- Improve test clarity and coverage
+- Identify edge cases that need testing
+- Ensure tests follow best practices
+
+**Output:** Draft PRs with test improvements.
+
+### Maintenance Workflows
+
+#### Agentic Maintenance
+**Trigger:** Daily at 00:37 UTC  
+**Purpose:** Cleans up expired issues, discussions, and pull requests
+
+Automatically closes expired entities based on the `expires` field in safe-outputs configuration. Schedule is determined by the shortest expiration time across all workflows.
+
+**Prevents:** Stale issues and PRs from accumulating.
+
+#### RulesSync Check
+**Trigger:** Pull request  
+**Purpose:** Validates that generated rule files are synchronized with sources
+
+**Validation steps:**
+1. Runs `bun run rules` to regenerate outputs
+2. Checks for uncommitted changes
+3. Fails if generated files don't match committed versions
+
+**Prevents:** Merging PRs with out-of-sync rule files.
+
+## CI/CD Workflows
+
+### Package Testing
+
+Each package has its own CI workflow that runs on pull requests and pushes:
+
+| Workflow | Package | Tests |
+|----------|---------|-------|
+| `api-ci.yml` | @terreno/api | Unit tests, type checking, linting |
+| `ui-ci.yml` | @terreno/ui | Component tests, type checking, linting |
+| `rtk-ci.yml` | @terreno/rtk | Unit tests, type checking, linting |
+| `mcp-server-ci.yml` | @terreno/mcp-server | Integration tests, type checking, linting |
+| `example-backend-ci.yml` | example-backend | Integration tests, type checking |
+| `example-frontend-ci.yml` | example-frontend | Build verification, type checking |
+| `ui-demo-ci.yml` | demo | Build verification, type checking |
+
+### Deployment Workflows
+
+#### Demo Deploy
+**Trigger:** Push to master  
+**Purpose:** Deploys UI demo to Google Cloud Storage with Cloud CDN
+
+**Architecture:** Static site hosting with custom domain, SSL, and CDN acceleration.
+
+**Learn more:** [GCP Hosting Architecture](gcp-hosting-architecture.md), [Deploy to GCP](../how-to/deploy-to-gcp.md)
+
+#### Frontend Example Deploy
+**Trigger:** Push to master, pull request  
+**Purpose:** Deploys example frontend with preview environments
+
+**Features:**
+- **Production:** Deploys to production GCS bucket on master
+- **Preview:** Creates preview environments for pull requests
+- **Cleanup:** Automatically removes preview environments when PRs close
+
+#### MCP Server Deploy
+**Trigger:** Push to master  
+**Purpose:** Deploys Model Context Protocol server
+
+Builds and deploys the MCP server for AI coding assistant integration.
+
+#### Preview Cleanup
+**Trigger:** Pull request close  
+**Purpose:** Removes preview deployments when PRs are closed or merged
+
+Ensures preview environments don't accumulate and waste resources.
+
+### Security & Quality
+
+#### CodeQL Analysis
+**Trigger:** Push to master, pull request, schedule (weekly)  
+**Purpose:** Security vulnerability scanning with GitHub CodeQL
+
+**Languages analyzed:** JavaScript, TypeScript
+
+**Output:** Security alerts in the Security tab when vulnerabilities are found.
+
+#### Dependabot Auto-merge
+**Trigger:** Dependabot pull request opened  
+**Purpose:** Automatically merges dependency updates after CI passes
+
+**Requirements for auto-merge:**
+- All CI checks pass
+- Dependabot PR (created by Dependabot)
+- No conflicts
+- 7-day cooldown for security (see Dependency Management)
+
+**Learn more:** [Dependency Management](dependency-management.md)
+
+### Publishing
+
+#### Publish on Tag
+**Trigger:** Tag push matching `v*.*.*`  
+**Purpose:** Publishes packages to npm registry
+
+**Workflow:**
+1. Validates tag format and package versions match
+2. Runs full test suite
+3. Publishes to npm with appropriate tags (`latest` or `next`)
+4. Creates GitHub release with changelog
+
+**Packages published:**
+- @terreno/api
+- @terreno/ui
+- @terreno/rtk
+- @terreno/mcp-server
+
+## Workflow Philosophy
+
+### Single Source of Truth
+- **Documentation:** Code is truth, docs must reflect it
+- **Rules:** `.rulesync/rules/` is truth, generated files derive from it
+- **Tests:** Implementation is truth, tests verify it
+
+### Fail Fast
+- All checks must pass before merge
+- Generated files must be committed (no drift)
+- Documentation gaps are treated like failing tests
+
+### Autonomous Improvement
+- Workflows create PRs, not commits
+- PRs are drafts requiring human review
+- Workflow agents make suggestions, humans make decisions
+
+### Continuous Sync
+- Documentation syncs on every master push
+- Rules sync on every master push
+- Dependencies update daily (Dependabot)
+- Quality improvements run daily (JSDoc, tests)
+
+## Working with AI Workflows
+
+### When a Workflow Creates a PR
+
+1. **Review the changes** — AI is helpful but not perfect
+2. **Run suggested commands** — E.g., `bun run rules` for rule updates
+3. **Test locally** — Ensure changes work as intended
+4. **Approve or close** — Merge if valuable, close if not
+
+### When a Workflow Fails
+
+Check the workflow run logs in the Actions tab:
+- **Documentation updates:** May need manual clarification
+- **Rule updates:** May need manual fixes to `.rulesync/rules/`
+- **JSDoc/test improvements:** May need guidance on conventions
+
+### Customizing Workflows
+
+Workflow definitions live in `.github/workflows/*.md` files. These are compiled into `.github/workflows/*.lock.yml` by the GitHub Agentic Workflows CLI.
+
+**To customize:**
+1. Edit the `.md` source file (e.g., `update-docs.md`)
+2. Run `gh aw compile` (if using gh-aw CLI)
+3. Commit both the `.md` and regenerated `.lock.yml`
+
+**Note:** Never edit `.lock.yml` files directly — they are generated.
+
+## Best Practices
+
+### For Maintainers
+- **Review workflow PRs regularly** — Don't let them accumulate
+- **Provide feedback** — If a workflow generates bad suggestions, close with a comment explaining why
+- **Tune prompts** — If a workflow consistently misses the mark, update the `.md` file
+
+### For Contributors
+- **Run CI before pushing** — `bun run lint && bun run test`
+- **Update rules if needed** — `bun run rules` after changing `.rulesync/rules/`
+- **Check workflow status** — Ensure your PR doesn't break workflows
+
+### For Users
+- **Check Actions tab** — See what's running and what's pending
+- **Review draft PRs** — Workflow-generated PRs may contain useful improvements
+- **Report issues** — If a workflow behaves unexpectedly, open an issue
+
+## Troubleshooting
+
+### Workflow doesn't run when expected
+- Check `.github/workflows/*.yml` trigger configuration
+- Verify branch name matches (usually `master`)
+- Check workflow permissions and safe-outputs limits
+
+### RulesSync check fails on PR
+- Run `bun run rules` locally
+- Commit any generated file changes
+- Ensure `.rulesync/rules/` files have valid YAML frontmatter
+
+### Dependabot PR doesn't auto-merge
+- Verify all CI checks pass (green checkmarks)
+- Check 7-day cooldown hasn't been violated
+- Ensure no merge conflicts exist
+
+### AI workflow creates poor quality PR
+- Review the workflow definition in `.github/workflows/*.md`
+- Consider customizing the prompt or instructions
+- Close the PR with feedback for future improvements
+
+## Related Documentation
+
+- [Dependency Management](dependency-management.md) — Dependabot configuration and auto-merge
+- [Deploy to GCP](../how-to/deploy-to-gcp.md) — Manual deployment guide
+- [GCP Hosting Architecture](gcp-hosting-architecture.md) — Static site hosting design
+- [Environment Variables](../reference/environment-variables.md) — Configuration reference

package/src/docs/versioned/0.19.0/explanation/authentication.md

@@ -0,0 +1,438 @@
+# Authentication Architecture
+
+Understanding how authentication works in @terreno/api — from JWT tokens to OAuth strategies to automatic token refresh.
+
+## Overview
+
+@terreno/api provides two complete authentication systems to choose from:
+
+**JWT/Passport Authentication (Default)**
+- **JWT (JSON Web Tokens)** for stateless session management
+- **Passport.js** for authentication strategy management
+- **Multiple strategies**: Email/password, GitHub OAuth, Anonymous
+- **Automatic token refresh** to maintain long-lived sessions
+- **Token storage utilities** for secure frontend storage (via @terreno/rtk)
+
+**Better Auth (Optional)**
+- **Session-based authentication** with MongoDB storage
+- **Built-in OAuth providers**: Google, GitHub, Apple
+- **Modern OAuth 2.0 flows** with PKCE
+- **Automatic session management** via cookies
+- **Redux integration** for session state (via @terreno/rtk)
+
+Choose your authentication provider via `AUTH_PROVIDER` environment variable. Both systems can run in parallel, allowing gradual migration.
+
+## Authentication Strategies
+
+### Email/Password (Local Strategy)
+
+Traditional username/password authentication using `passport-local-mongoose`.
+
+**Flow:**
+1. User signs up with email and password
+2. Password is hashed with pbkdf2 (via passport-local-mongoose)
+3. User logs in with credentials
+4. Backend validates password and issues JWT tokens
+5. Frontend includes JWT in `Authorization` header for subsequent requests
+
+**Endpoints:**
+- `POST /auth/signup` — Create new user account
+- `POST /auth/login` — Authenticate and receive tokens
+
+### GitHub OAuth Strategy
+
+OAuth 2.0 authentication with GitHub.
+
+**Flow:**
+1. User clicks "Sign in with GitHub"
+2. Frontend redirects to `GET /auth/github?returnTo=<url>`
+3. Backend redirects to GitHub authorization page
+4. User grants permissions on GitHub
+5. GitHub redirects back to `GET /auth/github/callback`
+6. Backend verifies authorization code with GitHub
+7. Backend finds/creates user, issues JWT tokens
+8. Backend redirects to `returnTo` URL with tokens as query params
+
+**Account Linking:**
+- Authenticated users can link their GitHub account via `GET /auth/github/link`
+- Multiple authentication methods can be attached to one user account
+- Users must have a password set before unlinking GitHub
+
+**Learn more:** [How to add GitHub OAuth](../how-to/add-github-oauth.md)
+
+### Better Auth Strategy
+
+Modern session-based authentication with built-in social OAuth support. Better Auth runs **alongside** JWT/Passport authentication as an optional alternative.
+
+**Flow:**
+1. Configure Better Auth with `AUTH_PROVIDER=better-auth`
+2. User chooses social provider (Google, GitHub, Apple) or email/password
+3. Backend redirects to OAuth provider or validates credentials
+4. Better Auth creates session in MongoDB
+5. Frontend receives session cookie
+6. Session middleware populates `req.user` for subsequent requests
+
+**Key differences from JWT auth:**
+- Session-based (cookies) vs. stateless (tokens)
+- Built-in OAuth providers vs. custom Passport strategies
+- Automatic session management vs. manual token refresh
+- Modern OAuth 2.0 flows with PKCE
+
+**Use Better Auth when you need:**
+- Social login (Google, GitHub, Apple)
+- Session-based authentication
+- Modern OAuth 2.0 flows
+
+**Use JWT authentication when you need:**
+- Stateless authentication
+- Simpler token-based auth
+- No social login required
+
+**Endpoints (when enabled):**
+- `POST /api/auth/signup/email` — Email/password signup
+- `POST /api/auth/signin/email` — Email/password signin
+- `GET /api/auth/signin/{provider}` — Initiate OAuth flow (google, github, apple)
+- `GET /api/auth/callback/{provider}` — OAuth callback handler
+- `POST /api/auth/signout` — Sign out session
+- `GET /api/auth/session` — Get current session
+
+**Learn more:** [Configure Better Auth](../how-to/configure-better-auth.md)
+
+### Anonymous Strategy
+
+Allows limited access without authentication.
+
+**Use case:** Public read access to certain resources while requiring authentication for writes.
+
+``````typescript
+import {Permissions} from "@terreno/api";
+
+modelRouter(Model, {
+  permissions: {
+    list: [Permissions.IsAuthenticatedOrReadOnly],
+    read: [Permissions.IsAuthenticatedOrReadOnly],
+    create: [Permissions.IsAuthenticated],
+  },
+});
+``````
+
+## JWT Token System
+
+### Token Types
+
+**Access Token (short-lived)**
+- Default expiration: 15 minutes (`TOKEN_EXPIRES_IN`)
+- Used for API requests
+- Included in `Authorization: Bearer <token>` header
+- Contains user ID and permissions in payload
+
+**Refresh Token (long-lived)**
+- Default expiration: 30 days (`REFRESH_TOKEN_EXPIRES_IN`)
+- Used only to obtain new access tokens
+- Stored securely on client
+- Cannot be used for API requests
+
+### Token Payload
+
+Access tokens contain:
+
+``````json
+{
+  "sub": "507f1f77bcf86cd799439011",  // User ID
+  "admin": false,                      // Admin status
+  "iat": 1709000000,                   // Issued at (timestamp)
+  "exp": 1709000900,                   // Expires at (timestamp)
+  "iss": "your-app-name"               // Issuer (from TOKEN_ISSUER env var)
+}
+``````
+
+Customize the payload with `authOptions.generateJWTPayload`:
+
+``````typescript
+setupServer({
+  authOptions: {
+    generateJWTPayload: (user) => ({
+      sub: user._id,
+      admin: user.admin,
+      role: user.role,  // Custom field
+    }),
+  },
+});
+``````
+
+### Token Refresh Flow
+
+1. Access token expires (after 15 minutes)
+2. API request returns `401 Unauthorized`
+3. Frontend middleware detects 401
+4. Frontend calls `POST /auth/refresh_token` with refresh token
+5. Backend validates refresh token
+6. Backend issues new access token and refresh token
+7. Frontend retries original request with new token
+
+This is handled automatically by @terreno/rtk's `emptyApi` configuration.
+
+## Frontend Integration
+
+### Redux Store Setup (with @terreno/rtk)
+
+``````typescript
+import {generateAuthSlice} from "@terreno/rtk";
+import {configureStore} from "@reduxjs/toolkit";
+import {openapi} from "./openApiSdk";
+
+const {authReducer, middleware, logout} = generateAuthSlice(openapi);
+
+export const store = configureStore({
+  reducer: {
+    auth: authReducer,
+    [openapi.reducerPath]: openapi.reducer,
+  },
+  middleware: (getDefault) =>
+    getDefault().concat(openapi.middleware, ...middleware),
+});
+``````
+
+**What this provides:**
+- Automatic token storage (SecureStore on mobile, AsyncStorage on web)
+- Token refresh middleware
+- Login/logout state management
+- Auth header injection for all API requests
+
+### Token Storage
+
+**Mobile (iOS/Android):**
+- Uses `expo-secure-store` for encrypted storage
+- Tokens stored in device keychain
+
+**Web:**
+- Uses `@react-native-async-storage/async-storage`
+- Falls back to localStorage
+- SSR-safe (checks `typeof window`)
+
+**Storage keys:**
+- `AUTH_TOKEN` — Access token
+- `REFRESH_TOKEN` — Refresh token
+
+## Permission System
+
+Permissions control access to modelRouter endpoints.
+
+### Built-in Permissions
+
+| Permission | Description |
+|-----------|-------------|
+| `IsAny` | Always allows (public access) |
+| `IsAuthenticated` | Requires valid JWT (non-anonymous) |
+| `IsAdmin` | Requires `user.admin === true` |
+| `IsOwner` | Requires admin or `obj.ownerId === user.id` |
+| `IsAuthenticatedOrReadOnly` | Auth required for writes, anyone can read |
+| `IsOwnerOrReadOnly` | Owner or admin for writes, anyone can read |
+
+### Permission Evaluation
+
+Permissions are evaluated as an **AND** operation — all permissions in the array must return `true`:
+
+``````typescript
+permissions: {
+  update: [Permissions.IsAuthenticated, Permissions.IsOwner],
+  // Both conditions must be true
+}
+``````
+
+### Custom Permissions
+
+Create custom permission functions:
+
+``````typescript
+const IsPremiumUser = (user, obj, method) => {
+  return user?.subscription === "premium";
+};
+
+modelRouter(Model, {
+  permissions: {
+    create: [Permissions.IsAuthenticated, IsPremiumUser],
+  },
+});
+``````
+
+## Security Best Practices
+
+### Backend
+
+✅ **Do:**
+- Use environment variables for secrets (`TOKEN_SECRET`, `REFRESH_TOKEN_SECRET`)
+- Set strong, unique secrets in production (at least 32 characters)
+- Use HTTPS in production
+- Validate token issuer (`TOKEN_ISSUER`)
+- Set appropriate token expiration times
+- Implement rate limiting on auth endpoints
+- Log authentication failures
+
+❌ **Don't:**
+- Commit secrets to version control
+- Use the same secret for tokens and refresh tokens
+- Store sensitive data in JWT payload (it's base64, not encrypted)
+- Allow infinite token lifetimes
+
+### Frontend
+
+✅ **Do:**
+- Use SecureStore on mobile for token storage
+- Clear tokens on logout
+- Handle token expiration gracefully
+- Show user feedback during auth flows
+- Validate tokens before making authenticated requests
+
+❌ **Don't:**
+- Store tokens in localStorage on web (use httpOnly cookies in production)
+- Log tokens to console
+- Send tokens in URL query parameters
+- Ignore token refresh failures
+
+## Environment Variables
+
+Required for authentication:
+
+``````bash
+# JWT Configuration
+TOKEN_SECRET=your-secret-key-min-32-chars
+TOKEN_ISSUER=your-app-name
+REFRESH_TOKEN_SECRET=different-secret-key-min-32-chars
+SESSION_SECRET=session-secret-min-32-chars
+
+# Optional: Custom expiration times
+TOKEN_EXPIRES_IN=15m
+REFRESH_TOKEN_EXPIRES_IN=30d
+
+# GitHub OAuth (if using)
+GITHUB_CLIENT_ID=your_github_client_id
+GITHUB_CLIENT_SECRET=your_github_client_secret
+GITHUB_CALLBACK_URL=http://localhost:4000/auth/github/callback
+
+# Optional: Disable user registration
+SIGNUP_DISABLED=false
+``````
+
+## Authentication Middleware
+
+### Protecting Routes
+
+Use `authenticateMiddleware()` to require authentication:
+
+``````typescript
+import {authenticateMiddleware, asyncHandler} from "@terreno/api";
+
+router.get("/protected", [
+  authenticateMiddleware(),
+  asyncHandler(async (req, res) => {
+    // req.user is populated with authenticated user
+    const userId = req.user?._id;
+    return res.json({userId});
+  }),
+]);
+``````
+
+### Anonymous Access
+
+Allow unauthenticated requests but populate `req.user` if token is present:
+
+``````typescript
+router.get("/public", [
+  authenticateMiddleware({anonymous: true}),
+  asyncHandler(async (req, res) => {
+    // req.user is populated if token provided, undefined otherwise
+    const isLoggedIn = !!req.user;
+    return res.json({isLoggedIn});
+  }),
+]);
+``````
+
+## Troubleshooting
+
+### "Invalid token"
+
+- Token has expired — frontend should refresh
+- Token signature invalid — check `TOKEN_SECRET` matches
+- Token issuer mismatch — verify `TOKEN_ISSUER` is correct
+
+### "No auth token provided"
+
+- Missing `Authorization` header
+- Header format incorrect (should be `Bearer <token>`)
+
+### Token refresh fails
+
+- Refresh token expired — user must log in again
+- `REFRESH_TOKEN_SECRET` mismatch between token creation and validation
+- Refresh token revoked (user logged out)
+
+### User logged out unexpectedly
+
+- Access token expired and refresh failed
+- Backend `TOKEN_SECRET` changed (invalidates all tokens)
+- Token storage cleared (app reinstall, cache clear)
+
+## Advanced Topics
+
+### Custom User Fields in Token
+
+Add custom fields to JWT payload:
+
+``````typescript
+setupServer({
+  authOptions: {
+    generateJWTPayload: (user) => ({
+      sub: user._id,
+      admin: user.admin,
+      organizationId: user.organizationId,
+      roles: user.roles,
+    }),
+  },
+});
+``````
+
+### Multi-Tenant Authentication
+
+Scope users to organizations:
+
+``````typescript
+const queryFilter = (user, _query) => ({
+  organizationId: user?.organizationId,
+});
+
+modelRouter(Model, {
+  permissions: {list: [Permissions.IsAuthenticated]},
+  queryFilter,
+});
+``````
+
+### Webhook Authentication
+
+Verify webhook signatures instead of JWT:
+
+``````typescript
+import crypto from "crypto";
+
+router.post("/webhook", asyncHandler(async (req, res) => {
+  const signature = req.headers["x-signature"];
+  const payload = JSON.stringify(req.body);
+  const expected = crypto
+    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
+    .update(payload)
+    .digest("hex");
+  
+  if (signature !== expected) {
+    throw new APIError({status: 401, title: "Invalid signature"});
+  }
+  
+  // Process webhook
+}));
+``````
+
+## Learn More
+
+- [Add GitHub OAuth](../how-to/add-github-oauth.md)
+- [Create a model](../how-to/create-a-model.md)
+- [API reference](../reference/api.md)
+- [@terreno/rtk reference](../reference/rtk.md)