npm - @terreno/mcp - Versions diffs - 57.20.0 → 58.0.0-beta.1 - Mend

@terreno/mcp 57.20.0 → 58.0.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4274) hide show

package/src/docs/versioned/57.2.0/explanation/ai-workflows.md DELETED Viewed

@@ -1,270 +0,0 @@
-# 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 | 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
-## 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/57.2.0/explanation/authentication.md DELETED Viewed

@@ -1,431 +0,0 @@
-# Authentication Architecture
-Understanding how authentication works in @terreno/api — Better Auth sessions for new apps, with JWT/Passport documented for legacy consumers.
-## Overview
-**Better Auth is the default path** for new Terreno apps. It provides session-based authentication with MongoDB storage, built-in social OAuth (Google, GitHub, Apple), and clean integration with `@terreno/syncdb` (`betterAuthAdapter`, `RealtimeApp` socket sessions).
-Set `AUTH_PROVIDER=better-auth` and register `BetterAuthApp` on the server. On the client, use `createBetterAuthClient` + `generateBetterAuthSlice` from `@terreno/rtk` for session Redux state, then wire `betterAuthAdapter` into `createSyncDb`.
-**JWT/Passport (legacy)** remains supported through the current major release line for existing deployments. It uses stateless tokens, Passport strategies (email/password, GitHub OAuth, anonymous), and manual token refresh via `@terreno/rtk`. New projects should not start on JWT unless they have a specific requirement (custom token contracts, non-cookie clients, or a phased migration).
-Both systems can run in parallel during migration (`AUTH_PROVIDER` selects the primary path; legacy JWT routes stay available).
-## When to choose which
-| Choose Better Auth | Stay on JWT (legacy) |
-|--------------------|----------------------|
-| New app or greenfield screen | Existing production JWT deployment |
-| Social login (Google, GitHub, Apple) | Custom JWT payload requirements |
-| `@terreno/syncdb` local-first data | Non-cookie API clients only |
-| Socket sessions via `RealtimeApp` | Gradual migration in progress |
-**Setup:** [Configure Better Auth](../how-to/configure-better-auth.md). **Data layer:** migrate auth before or with syncdb — see [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) §7.
-## Authentication Strategies
-### Better Auth (default)
-Modern session-based authentication with built-in social OAuth support.
-**Flow:**
-1. Configure Better Auth with `AUTH_PROVIDER=better-auth` and register `BetterAuthApp`
-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 (web) or bearer session token (native)
-6. Session middleware populates `req.user` for subsequent requests
-**Key properties:**
-- Session-based (cookies / bearer session) vs. stateless JWT
-- Built-in OAuth providers with PKCE
-- `betterAuthAdapter` for syncdb socket auth
-- `sync:auth-expired` socket event when the session is no longer valid
-**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)
-### Email/Password (JWT / Local Strategy — legacy)
-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 (JWT — legacy)
-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)
-### Anonymous Strategy (JWT — legacy)
-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 (legacy)
-> JWT/Passport auth is **legacy**. It remains supported through the current major line but is not the recommended path for new apps. Prefer Better Auth above.
-### 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 (legacy)](../reference/legacy/rtk.md)