npm - @terreno/mcp - Versions diffs - 0.24.0 → 0.25.0 - Mend

@terreno/mcp 0.24.0 → 0.25.0

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 (1175) hide show

package/src/docs/versioned/0.19.0/reference/environment-variables.md DELETED Viewed

@@ -1,382 +0,0 @@
-# Environment Variables Reference
-Comprehensive guide to environment variables used across Terreno packages and example applications.
-## Table of Contents
-- [@terreno/api (Backend)](#terrenoapi-backend)
-- [@terreno/rtk (Frontend State)](#terrenortk-frontend-state)
-- [@terreno/ui (Components)](#terrenoui-components)
-- [Example Backend](#example-backend)
-- [Example Frontend](#example-frontend)
----
-## @terreno/api (Backend)
-Environment variables used by the `@terreno/api` package.
-### Authentication
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `AUTH_PROVIDER` | ❌ | `jwt` | Authentication provider: `"jwt"` or `"better-auth"` |
-| `TOKEN_SECRET` | ✅ (if JWT) | - | Secret key for signing JWT access tokens |
-| `TOKEN_ISSUER` | ✅ (if JWT) | - | JWT issuer claim (e.g., `your-app.com`) |
-| `REFRESH_TOKEN_SECRET` | ✅ (if JWT) | - | Secret key for signing refresh tokens |
-| `SESSION_SECRET` | ✅ (if JWT) | - | Express session secret |
-| `TOKEN_EXPIRES_IN` | ❌ | `15m` | Access token expiration (e.g., `1h`, `30m`) |
-| `REFRESH_TOKEN_EXPIRES_IN` | ❌ | `30d` | Refresh token expiration (e.g., `7d`, `90d`) |
-| `SIGNUP_DISABLED` | ❌ | `false` | Disable user registration (invite-only mode) |
-### Better Auth (Optional)
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `BETTER_AUTH_SECRET` | ✅ (if Better Auth) | - | Secret key for Better Auth session encryption |
-| `BETTER_AUTH_URL` | ✅ (if Better Auth) | - | Base URL for Better Auth server (e.g., `https://api.example.com`) |
-| `GOOGLE_CLIENT_ID` | ❌ | - | Google OAuth client ID |
-| `GOOGLE_CLIENT_SECRET` | ❌ | - | Google OAuth client secret |
-| `APPLE_CLIENT_ID` | ❌ | - | Apple Sign In service ID |
-| `APPLE_CLIENT_SECRET` | ❌ | - | Apple Sign In private key |
-### GitHub OAuth (Optional)
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `GITHUB_CLIENT_ID` | ❌ | - | GitHub OAuth application client ID |
-| `GITHUB_CLIENT_SECRET` | ❌ | - | GitHub OAuth application client secret |
-| `GITHUB_CALLBACK_URL` | ❌ | - | OAuth callback URL (e.g., `https://api.example.com/auth/github/callback`) |
-### Server Configuration
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `PORT` | ❌ | `3000` | HTTP server port |
-| `NODE_ENV` | ❌ | `development` | Node environment (`development`, `production`, `test`) |
-| `MONGO_URI` | ❌ | `mongodb://localhost:27017` | MongoDB connection string |
-| `ENABLE_SWAGGER` | ❌ | `false` | Enable Swagger UI at `/swagger` endpoint |
-### Logging & Monitoring
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `SENTRY_DSN` | ❌ | - | Sentry DSN for error tracking |
-| `USE_SENTRY_LOGGING` | ❌ | `false` | Send logs to Sentry |
-| `LOG_REQUESTS` | ❌ | `false` | Log all HTTP requests |
-| `LOG_SLOW_REQUESTS` | ❌ | `false` | Log requests exceeding threshold |
-| `SLOW_REQUEST_THRESHOLD_MS` | ❌ | `5000` | Milliseconds to consider a request "slow" |
-| `SLOW_DB_QUERY_THRESHOLD_MS` | ❌ | `100` | Milliseconds to consider a DB query "slow" |
-### Webhooks & Notifications (Optional)
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `SLACK_WEBHOOKS` | ❌ | - | JSON object mapping names to Slack webhook URLs<br/>Example: `{"default": "https://hooks.slack.com/..."}` |
-| `GOOGLE_CHAT_WEBHOOKS` | ❌ | - | JSON object mapping names to Google Chat webhook URLs<br/>Example: `{"default": "https://chat.googleapis.com/..."}` |
-| `ZOOM_WEBHOOK` | ❌ | - | Zoom webhook URL for notifications |
-### Google Cloud Platform (Optional)
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `GCP_PROJECT` | ❌ | - | Google Cloud project ID |
-| `GCP_LOCATION` | ❌ | - | GCP region (e.g., `us-central1`) |
-| `GCP_SERVICE_ACCOUNT_EMAIL` | ❌ | - | Service account email for authentication |
-| `GCP_TASKS_NOTIFICATIONS_QUEUE` | ❌ | - | Cloud Tasks queue name for notifications |
-| `GCP_TASK_PROCESSOR_QUEUE` | ❌ | - | Cloud Tasks queue name for background tasks |
-### Caching & Performance
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `VALKEY_URL` | ❌ | - | Redis/Valkey connection URL (e.g., `redis://localhost:6379`) |
-### Other APIs
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `GEMINI_API_KEY` | ❌ | - | Google Gemini API key for AI features |
-### Example .env File
-``````bash
-# Authentication Provider
-AUTH_PROVIDER=jwt  # or "better-auth"
-# Required for JWT authentication
-TOKEN_SECRET=your-secret-key-change-this-in-production
-TOKEN_ISSUER=your-app.com
-REFRESH_TOKEN_SECRET=your-refresh-secret-change-this-too
-SESSION_SECRET=your-session-secret-change-this-also
-# Required for Better Auth (if AUTH_PROVIDER=better-auth)
-# BETTER_AUTH_SECRET=your-better-auth-secret-min-32-chars
-# BETTER_AUTH_URL=http://localhost:4000
-# Optional - Social OAuth (Better Auth)
-# GOOGLE_CLIENT_ID=your-google-client-id
-# GOOGLE_CLIENT_SECRET=your-google-client-secret
-# GITHUB_CLIENT_ID=your-github-client-id
-# GITHUB_CLIENT_SECRET=your-github-client-secret
-# Database
-MONGO_URI=mongodb://localhost:27017/your-app
-# Optional - Common in development
-PORT=3000
-NODE_ENV=development
-ENABLE_SWAGGER=true
-LOG_REQUESTS=true
-# Optional - Production monitoring
-SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
-USE_SENTRY_LOGGING=true
-``````
----
-## @terreno/rtk (Frontend State)
-Environment variables used by the `@terreno/rtk` package and frontend applications.
-### Base URL Configuration
-The base URL is resolved in priority order:
-1. `Constants.expoConfig?.extra?.BASE_URL` (production/staging builds)
-2. `process.env.EXPO_PUBLIC_API_URL` (development web)
-3. `Constants.expoConfig?.hostUri` + `:3000` (dev simulator/device)
-4. `http://localhost:3000` (fallback)
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `EXPO_PUBLIC_API_URL` | ❌ | Auto-detected | Backend API base URL<br/>Web: `http://localhost:3000`<br/>Simulator: Auto-detected via `hostUri`<br/>Device: Use your computer's local IP |
-### Debug Flags
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `AUTH_DEBUG` | ❌ | `false` | Enable authentication debug logging |
-| `WEBSOCKETS_DEBUG` | ❌ | `false` | Enable WebSocket debug logging |
-### Example app.json Configuration
-``````json
-{
-  "expo": {
-    "extra": {
-      "BASE_URL": "https://api.example.com",
-      "AUTH_DEBUG": "false",
-      "WEBSOCKETS_DEBUG": "false"
-    }
-  }
-}
-``````
-### Example .env for Web Development
-``````bash
-# Backend API URL
-EXPO_PUBLIC_API_URL=http://localhost:4000
-``````
----
-## @terreno/ui (Components)
-The `@terreno/ui` package **does not require environment variables**. All configuration is done at runtime via the `TerrenoProvider` component.
-### Runtime Configuration
-``````typescript
-import {TerrenoProvider} from "@terreno/ui";
-<TerrenoProvider
-  initialTheme={{
-    primitives: {
-      primary500: "#0066CC",
-      accent500: "#FF6B35",
-    }
-  }}
->
-  <App />
-</TerrenoProvider>
-``````
----
-## Example Backend
-Environment variables specific to the example backend application (not part of @terreno/api).
-### Application Configuration
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `APP_ENV` | ❌ | `development` | Application environment (`development`, `staging`, `production`) |
-| `BACKEND_SERVICE` | ❌ | `all` | Service type to run: `api`, `websockets`, `tasks`, or `all` |
-| `API_URL` | ❌ | - | API service URL (for microservice architecture) |
-| `TASKS_URL` | ❌ | - | Tasks service URL (for microservice architecture) |
-| `FLOURISH_SERVICE` | ❌ | `flourish-backend` | Service name for OpenTelemetry tracing |
-### WebSockets
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `WEBSOCKET_PORT` | ❌ | Same as `PORT` | WebSocket server port (if separate from HTTP) |
-| `FRONTEND_URL` | ❌ | Auto-detected | Frontend URL for CORS (e.g., `http://localhost:8082`) |
-### Pull Request Environments
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `PR_NUMBER` | ❌ | - | Pull request number (set by CI/CD) |
-| `PR_SERVICE_URL` | ❌ | - | Cloud Run service URL base for PR environments |
-### Performance Monitoring
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `MEMORY_SAMPLE_INTERVAL_MS` | ❌ | `60000` | Interval for memory usage sampling |
-| `TRACE_SAMPLING_RATE` | ❌ | `0.1` | OpenTelemetry trace sampling rate (0.0-1.0) |
-### Testing
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `TEST_MONGO_URI` | ❌ | `mongodb://localhost:27017/test` | MongoDB URI for tests |
-| `CRON_SECRET_KEY` | ❌ | - | Secret key for testing cron endpoints |
-### Configuration Model System
-The example backend uses a **Configuration model** with a priority system:
-**Priority (highest to lowest)**:
-1. Runtime override via `Configuration.set()`
-2. Database cache (persisted values)
-3. Environment variable
-4. Default value
-``````typescript
-// Get configuration value
-const pageSize = await Configuration.get("DEFAULT_PAGE_SIZE"); // Returns 20
-// Set configuration value (persists to database)
-await Configuration.set("DEFAULT_PAGE_SIZE", 50);
-// Register new configuration
-Configuration.register("FEATURE_FLAG", {
-  defaultValue: false,
-  envVar: "FEATURE_FLAG",
-  description: "Enable new feature",
-  type: "boolean",
-});
-``````
-See [Configuration System](../explanation/configuration-system.md) for details.
----
-## Example Frontend
-Environment variables specific to the example frontend application.
-### SDK Generation
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `OPENAPI_URL` | ❌ | `http://localhost:4000/openapi.json` | Backend OpenAPI spec URL for SDK generation |
-Used by `bun run sdk` to fetch the OpenAPI specification and generate RTK Query hooks.
-### Development
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `EXPO_PUBLIC_API_URL` | ❌ | Auto-detected | Backend API URL (see [@terreno/rtk](#terrenortk-frontend-state)) |
-### Example .env File
-``````bash
-# Backend API (optional - auto-detected if not set)
-EXPO_PUBLIC_API_URL=http://localhost:4000
-# SDK generation (optional)
-OPENAPI_URL=http://localhost:4000/openapi.json
-``````
----
-## Best Practices
-### Security
-1. **Never commit `.env` files** - Add to `.gitignore`
-2. **Use strong secrets** - Generate with `openssl rand -base64 32`
-3. **Rotate secrets regularly** - Especially `TOKEN_SECRET` and `REFRESH_TOKEN_SECRET`
-4. **Different secrets per environment** - Don't reuse production secrets in development
-### Development
-1. **Use `.env.example`** - Check into version control with placeholder values
-2. **Document all variables** - Include description and default values
-3. **Validate required variables** - Fail fast if missing critical config
-4. **Auto-detect when possible** - Like `@terreno/rtk` does for `BASE_URL`
-### Production
-1. **Use environment variables** - Not hardcoded values or `.env` files
-2. **Set via platform** - Railway, Heroku, Cloud Run, etc.
-3. **Enable monitoring** - Set `SENTRY_DSN` and `USE_SENTRY_LOGGING`
-4. **Reduce logging** - Set `LOG_REQUESTS=false` to reduce noise
----
-## Troubleshooting
-### "TOKEN_SECRET is not set"
-**Problem**: Required authentication variables missing.
-**Solution**:
-```bash
-cp .env.example .env
-# Edit .env and set all required variables
-```
-### "Cannot connect to MongoDB"
-**Problem**: `MONGO_URI` incorrect or MongoDB not running.
-**Solutions**:
-- Ensure MongoDB is running: `docker run -d -p 27017:27017 mongo`
-- Check `MONGO_URI` in `.env`
-- Test connection: `mongosh mongodb://localhost:27017`
-### "Network request failed" (Frontend)
-**Problem**: Frontend can't reach backend.
-**Solutions**:
-- Ensure backend is running
-- Check `EXPO_PUBLIC_API_URL` matches backend port
-- For physical devices: Use your computer's local IP, not `localhost`
-- Verify CORS settings allow frontend origin
-### "Invalid token"
-**Problem**: Token secrets mismatch between frontend/backend.
-**Solution**: Ensure `TOKEN_SECRET` and `REFRESH_TOKEN_SECRET` are identical across deployments if using shared authentication.
----
-## Related Documentation
-- [Getting Started Tutorial](../tutorials/getting-started.md)
-- [@terreno/api Reference](./api.md)
-- [@terreno/rtk Reference](./rtk.md)
-- [Configuration System](../explanation/configuration-system.md)
-- [Example Backend README](../../example-backend/README.md)
-- [Example Frontend README](../../example-frontend/README.md)

package/src/docs/versioned/0.19.0/reference/feature-flags.md DELETED Viewed

@@ -1,252 +0,0 @@
-# @terreno/feature-flags
-Feature flags and A/B testing plugin for `@terreno/api`. Provides a Mongoose model, admin CRUD endpoints, user-facing evaluation, and deterministic hashing for gradual rollouts and variant assignment.
-## Install
-```bash
-bun add @terreno/feature-flags
-```
-Peer dependency: `mongoose >= 8.0.0`.
-## Quick Start
-### Backend
-Register `FeatureFlagsApp` as a `TerrenoPlugin` and add the pre-configured admin model config to your `AdminApp`:
-```typescript
-import {TerrenoApp} from "@terreno/api";
-import {AdminApp} from "@terreno/admin-backend";
-import {FeatureFlagsApp, featureFlagAdminConfig} from "@terreno/feature-flags";
-import {User} from "./models/user";
-const segments = {
-  "pro-users": (user) => user.plan === "pro",
-  "beta-testers": (user) => user.betaTester === true,
-};
-new TerrenoApp({userModel: User})
-  .register(new FeatureFlagsApp({segments}))
-  .register(
-    new AdminApp({
-      models: [featureFlagAdminConfig],
-    })
-  )
-  .start();
-```
-`featureFlagAdminConfig` is a ready-to-use admin model config that sets up the display name, list fields, route path, and model reference — no manual configuration needed. Downstream consumers can import it directly and pass it to `AdminApp`.
-### Frontend
-Use the `useFeatureFlags` hook from `@terreno/rtk` to evaluate flags for the current user:
-```typescript
-import {useFeatureFlags} from "@terreno/rtk";
-import {terrenoApi} from "@/store/sdk";
-const MyComponent = () => {
-  const {getFlag, isLoading} = useFeatureFlags(terrenoApi);
-  if (isLoading) return <Spinner />;
-  const showNewFeature = getFlag("new-feature");        // boolean
-  const variant = getFlag("checkout-experiment");        // string | null
-  return showNewFeature ? <NewFeature /> : <OldFeature />;
-};
-```
-## Exports
-### Classes
-| Export | Description |
-|--------|-------------|
-| `FeatureFlagsApp` | `TerrenoPlugin` that registers admin CRUD and evaluation endpoints |
-### Models
-| Export | Description |
-|--------|-------------|
-| `FeatureFlag` | Mongoose model for feature flag documents |
-### Constants
-| Export | Description |
-|--------|-------------|
-| `featureFlagAdminConfig` | Pre-configured `AdminModelConfig` for use with `AdminApp` |
-### Functions
-| Export | Description |
-|--------|-------------|
-| `evaluateFlag` | Evaluate a single flag for a user |
-| `evaluateAllFlags` | Evaluate all enabled, non-archived flags for a user |
-| `deterministicHash` | Hash a string to 0–99 for consistent assignment |
-### Types
-| Export | Description |
-|--------|-------------|
-| `FeatureFlagDocument` | Mongoose document type for a feature flag |
-| `FeatureFlagModel` | Mongoose model type with custom statics |
-| `FeatureFlagRule` | Targeting rule shape (field-based or segment-based) |
-| `FeatureFlagVariant` | Variant key + weight for A/B tests |
-| `FeatureFlagType` | `"boolean" \| "variant"` |
-| `FeatureFlagsOptions` | Constructor options for `FeatureFlagsApp` |
-| `SegmentFunction` | `(user: unknown) => boolean` |
-| `EvaluationResult` | `Record<string, boolean \| string \| null>` |
-## FeatureFlagsApp Options
-```typescript
-interface FeatureFlagsOptions {
-  basePath?: string;                                // Default: "/feature-flags"
-  segments?: Record<string, SegmentFunction>;       // Named segment functions
-  permissions?: ModelRouterOptions["permissions"];   // Override default IsAdmin on CRUD
-  segmentsPermission?: (user: unknown) => boolean;  // Override admin check on /segments
-}
-```
-## Generated Routes
-All routes are mounted under the configured `basePath` (default: `/feature-flags`).
-### Admin Routes (default: `IsAdmin`)
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `{basePath}/flags/` | Create a feature flag |
-| `GET` | `{basePath}/flags/` | List flags (paginated, sortable) |
-| `GET` | `{basePath}/flags/:id` | Get a single flag |
-| `PATCH` | `{basePath}/flags/:id` | Update a flag |
-| `DELETE` | `{basePath}/flags/:id` | Soft-delete a flag |
-| `GET` | `{basePath}/segments` | List registered segment names |
-### User Routes (`IsAuthenticated`)
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `{basePath}/evaluate` | Evaluate all flags for the current user |
-### Response Shapes
-**`GET /feature-flags/evaluate`**:
-```json
-{
-  "data": {
-    "new-checkout-flow": true,
-    "checkout-experiment": "variant-a",
-    "dark-mode": false
-  }
-}
-```
-**`GET /feature-flags/segments`**:
-```json
-{
-  "data": ["pro-users", "beta-testers"]
-}
-```
-## Flag Types
-### Boolean Flags (`type: "boolean"`)
-Return `true` or `false`. Use `rolloutPercentage` for gradual rollouts.
-- `enabled: false` → always `false`
-- `enabled: true`, no matching rules → deterministic hash compared against `rolloutPercentage`
-- Matching rule → returns the rule's `enabled` value
-### Variant Flags (`type: "variant"`)
-Return a string variant key. Use the `variants` array with weighted distribution.
-- `enabled: false` → returns `null`
-- `enabled: true`, no matching rules → deterministic hash mapped to variant by cumulative weights
-- Matching rule → returns the rule's `variant` value
-## Targeting Rules
-Rules are evaluated in order — first match wins. Each rule is either field-based or segment-based.
-### Field Rules
-Match against a user field with an operator:
-```json
-{
-  "field": "email",
-  "operator": "contains",
-  "value": "@mycompany.com",
-  "enabled": true
-}
-```
-Supported operators: `eq`, `neq`, `in`, `nin`, `gt`, `lt`, `contains`. Dot notation is supported for nested fields (e.g. `address.zip`).
-### Segment Rules
-Match against a named segment function registered at startup:
-```json
-{
-  "segment": "pro-users",
-  "enabled": true
-}
-```
-## Admin Integration
-The `featureFlagAdminConfig` export provides everything `AdminApp` needs:
-```typescript
-import {featureFlagAdminConfig} from "@terreno/feature-flags";
-// Use directly in AdminApp
-new AdminApp({
-  models: [featureFlagAdminConfig, ...otherModels],
-});
-```
-This is equivalent to manually configuring:
-```typescript
-import {FeatureFlag} from "@terreno/feature-flags";
-{
-  displayName: "Feature Flags",
-  listFields: ["key", "name", "type", "enabled", "archived", "created"],
-  model: FeatureFlag,
-  routePath: "/feature-flags",
-}
-```
-The admin panel auto-generates forms from the FeatureFlag model schema, including fields for rules, variants, rollout percentage, and archiving.
-## Segments
-Segments are named functions that classify users. Register them when constructing `FeatureFlagsApp`:
-```typescript
-const segments = {
-  "admin-users": (user) => user.admin === true,
-  "oauth-users": (user) => Boolean(user.oauthProvider),
-  "high-usage": (user) => user.totalActions > 1000,
-  "internal-team": (user) => user.email?.endsWith("@mycompany.com"),
-};
-new FeatureFlagsApp({segments});
-```
-Segment names can be referenced in flag rules via the admin UI.
-## Environment Variables
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `FEATURE_FLAGS_DEBUG` | Set to `"false"` to disable evaluation debug logs | Enabled |