@terreno/mcp 0.26.0 → 0.27.0

package/dist/docs/versioned/next/reference/ui.md

@@ -10,7 +10,7 @@ React Native UI component library (88+ components). Layout (Box, Page, Card), fo
 - Actions: `Button`, `IconButton`, `Link`
 - Feedback: `Spinner`, `Modal`, `Toast`
 - Authentication: `SocialLoginButton`, `LoginScreen`, `SignUpScreen`
-- Theming: `TerrenoProvider`, `useTheme`
+- Theming: `TerrenoProvider`, `useTheme`, custom icon registry (`icons` prop)
 - **Type re-exports:** `StyleProp`, `ViewStyle` (re-exported from react-native to avoid version conflicts)
 
 ## Type Re-exports
@@ -334,21 +334,79 @@ if (isMobileDevice()) {
 
 ## Icons
 
+Terreno uses **FontAwesome 6** by default. Pass icon names via `iconName` on `Icon`, `Button`, `IconButton`, form fields, `Badge`, and other icon-aware components.
+
 ### FontAwesome Icons
 
-All 2000+ FontAwesome 6 icons available via the `Icon` component:
+All 2000+ FontAwesome 6 icons are available:
 
 ``````typescript
-import {Icon} from "@terreno/ui";
+import {Icon, Button} from "@terreno/ui";
+
+<Icon iconName="check" size="md" color="primary" />
+<Icon iconName="user" size="lg" color="secondaryDark" />
+<Icon iconName="chevron-right" size="sm" color="primary" />
 
-<Icon name="check" size={24} color="primary" />
-<Icon name="user" size={32} color="secondary" />
-<Icon name="chevron-right" size={16} color="neutral700" />
+<Button text="Save" iconName="check" onClick={handleSave} />
 ``````
 
-### Custom SVG Icons
+**Sizes:** `xs`, `sm`, `md`, `lg`, `xl`, `2xl`
+
+**Types:** `solid` (default), `regular`, `brand`, `light`, `thin`, `duotone`, `sharp`, and related variants.
+
+### Custom Icons
+
+Register your own icons (SVGs, etc.) on `TerrenoProvider` and use them by name anywhere `iconName` is accepted. Registered names take precedence over FontAwesome.
+
+**1. Create a custom icon component** that accepts `color`, `size` (pixels), and optional `testID`:
+
+``````typescript
+import type {CustomIconProps} from "@terreno/ui";
+import Svg, {Path} from "react-native-svg";
+
+export const SparkleIcon = ({color, size, testID}: CustomIconProps): React.ReactElement => (
+  <Svg fill="none" height={size} testID={testID} viewBox="0 0 24 24" width={size}>
+    <Path d="M12 2l2.4 6.6L21 11l-6.6 2.4L12 20l-2.4-6.6L3 11l6.6-2.4L12 2z" fill={color} />
+  </Svg>
+);
+``````
+
+Terreno resolves theme colors and size tokens before passing them to your component.
+
+**2. Register icons** via the `icons` prop on `TerrenoProvider`:
+
+``````typescript
+import {TerrenoProvider} from "@terreno/ui";
+import {SparkleIcon} from "./components/SparkleIcon";
+
+<TerrenoProvider icons={{sparkle: SparkleIcon}}>
+  {children}
+</TerrenoProvider>
+``````
+
+**3. Use by name** like any built-in icon:
+
+``````typescript
+<Icon iconName="sparkle" color="accent" size="lg" />
+<Button text="Sparkle" iconName="sparkle" onClick={handleClick} />
+<IconButton accessibilityLabel="Sparkle" iconName="sparkle" onClick={handleClick} />
+``````
+
+**TypeScript:** extend `CustomIconRegistry` via declaration merging for autocomplete and type-safe `iconName` values:
+
+``````typescript
+declare module "@terreno/ui" {
+  interface CustomIconRegistry {
+    sparkle: true;
+  }
+}
+``````
+
+See [`demo/components/customIcons.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/components/customIcons.tsx) for a full working example.
+
+### Built-in Status Icons
 
-@terreno/ui includes custom status icons:
+@terreno/ui also ships status indicator SVGs as standalone components (not registered via `TerrenoProvider`):
 
 ``````typescript
 import {MobileIcon, OnlineIcon, OfflineIcon, OutOfOfficeIcon} from "@terreno/ui";
@@ -393,7 +451,7 @@ const buttonStyles = toggle(isPressed, pressedStyles, defaultStyles);
 
 @terreno/ui components do not require environment variables. All configuration is done at runtime via:
 
-- **TerrenoProvider props** — Theme customization, error handlers, base URL
+- **TerrenoProvider props** — Theme customization, custom icon registry (`icons`), OpenAPI spec URL
 - **Theme hooks** — `useTheme()`, `setTheme()`, `setPrimitives()`
 - **Component props** — Direct prop overrides for individual components
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terreno/mcp",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "MCP server for Terreno - provides documentation, tools, and prompts for building full-stack apps",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "0.26.0",
+    "@terreno/api": "0.27.0",
     "minisearch": "^7.2.0",
     "mongoose": "8.23.0"
   },

package/src/docs/resources/ui.md

@@ -271,11 +271,44 @@ if (isMobileDevice()) {
 
 ## Icons
 
+FontAwesome 6 icons are used by default via `iconName`:
+
+```typescript
+import { Icon, IconButton, Button } from "@terreno/ui";
+
+<Icon iconName="check" size="md" color="primary" />
+<IconButton accessibilityLabel="Close" iconName="xmark" onClick={handleClose} />
+<Button text="Save" iconName="check" onClick={handleSave} />
+```
+
+### Custom Icons
+
+Register SVG or other custom icons on `TerrenoProvider` and use them by name anywhere `iconName` is accepted. Registered names take precedence over FontAwesome.
+
 ```typescript
-import { Icon, IconButton } from "@terreno/ui";
+import type { CustomIconProps } from "@terreno/ui";
+import { TerrenoProvider } from "@terreno/ui";
+import Svg, { Path } from "react-native-svg";
 
-<Icon name="check" size={24} color="success500" />
-<IconButton name="close" onClick={handleClose} />
+const SparkleIcon = ({ color, size, testID }: CustomIconProps) => (
+  <Svg fill="none" height={size} testID={testID} viewBox="0 0 24 24" width={size}>
+    <Path d="M12 2l2.4 6.6L21 11l-6.6 2.4L12 20l-2.4-6.6L3 11l6.6-2.4L12 2z" fill={color} />
+  </Svg>
+);
+
+<TerrenoProvider icons={{ sparkle: SparkleIcon }}>
+  <Icon iconName="sparkle" color="accent" size="lg" />
+</TerrenoProvider>
+```
+
+For TypeScript autocomplete, extend `CustomIconRegistry` via declaration merging:
+
+```typescript
+declare module "@terreno/ui" {
+  interface CustomIconRegistry {
+    sparkle: true;
+  }
+}
 ```
 
 ## Best Practices

package/src/docs/versioned/0.26.0/explanation/README.md

@@ -0,0 +1,14 @@
+# Explanation
+
+Understanding-oriented documentation: concepts, architecture, and context.
+
+## Contents
+
+- [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
+- [Authentication architecture](authentication.md) — How JWT, OAuth, and token refresh work
+- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
+- [Dependency management](dependency-management.md) — Dependabot, auto-merge, and security practices
+- [GCP hosting architecture](gcp-hosting-architecture.md) — Static site hosting with GCS and Cloud CDN
+- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
+- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
+- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels

package/src/docs/versioned/0.26.0/explanation/no-barrel-imports.md

@@ -0,0 +1,49 @@
+# No barrel imports
+
+Terreno avoids **barrel imports** — imports that resolve through an `index.ts` / `index.tsx` file that only re-exports other modules.
+
+## Why
+
+- **Clearer dependencies**: each import names the file that defines the symbol.
+- **Faster tooling**: bundlers and TypeScript do less re-export chasing.
+- **Fewer cycles**: internal barrels (especially package `index` files) are a common source of circular dependencies.
+
+## Allowed
+
+- **Published package APIs** — cross-package imports like `@terreno/api`, `@terreno/ui`, and `@terreno/rtk` use each package's public `src/index` entry. That is intentional.
+- **Package public entry files** — `api/src/index.ts`, `ui/src/index.tsx`, etc. may re-export for npm consumers. Do not import those barrels from *inside* the same package.
+- **Expo Router routes** — `app/**/index.tsx` files are route entries, not barrels.
+
+## Not allowed
+
+Internal barrel `index` files do not exist in this repo — the Biome `noBarrelFile` override bans creating them, so a directory import like `../models` has nothing to resolve to and fails to compile.
+
+Importing a directory that resolves to a re-exporting index file:
+
+```typescript
+// Bad — resolves to models/index.ts
+import {User} from "../models";
+
+// Good — imports the defining module
+import {User} from "../models/user";
+```
+
+```typescript
+// Bad — store/index.ts was a barrel of sdk/appState/utils
+import {useGetMeQuery} from "@/store";
+
+// Good
+import {useGetMeQuery} from "@/store/sdk";
+import store, {useAppDispatch} from "@/store/index";
+```
+
+## Enforcement
+
+No generation step is required — internal barrel `index` files are banned outright, so there is never a list of barrels to keep in sync.
+
+- **Biome `noBarrelFile` override** (root `biome.jsonc`): bans internal barrel `index.ts` / `index.tsx` files during lint. Package public entries (`src/index.ts[x]`) and Expo Router routes (`app/**`) are exempt.
+- **Biome plugin**: `biome/plugins/no-barrel-imports.grit` — a small static GritQL plugin that flags path-alias directory imports (`@/store`, `@components`, …) in the packages that define those aliases (`example-frontend`, `admin-spa`, `demo`).
+- **CI**: `bun run check:no-barrel-imports` — resolution-based safety net that fails if any internal barrel index file exists or any import resolves through one (see root `package.json` → `terreno.policies.noBarrelImports`).
+- **AI rules**: `.rulesync/rules/00-root.md` and package `.ai/guidelines/core.md` files
+
+When scaffolding new code (MCP bootstrap, examples), always generate direct module paths — never `models/index`, `@/store`, or `@components` without a concrete file.

package/src/docs/versioned/0.26.0/how-to/README.md

@@ -0,0 +1,21 @@
+# How-to Guides
+
+Problem-oriented, practical steps. Use these when you know what you want to do.
+
+## Contents
+
+- [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
+- [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
+- [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
+- [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
+- [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
+- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — Deploy demo and example apps to GCS with CDN
+
+## Coming Soon
+
+- [Add feature flags](add-feature-flags.md) — Add feature flags and A/B testing to your app
+- Add custom permissions
+- Implement file uploads
+- Configure email notifications
+- Customize AI workflows
+- Set up custom CI/CD pipelines

package/src/docs/versioned/0.26.0/how-to/call-external-apis.md

@@ -0,0 +1,101 @@
+# Call external APIs
+
+How to talk to third-party HTTP APIs (payment processors, health integrations, meeting providers, etc.) from a `@terreno/api` backend using the shared HTTP client utilities, instead of hand-rolling axios setup, token caching, retry, and error handling per integration.
+
+## When to use each piece
+
+| You are... | Use |
+|---|---|
+| Calling a third-party REST API that needs a bearer token, OAuth2 client-credentials, or API-key auth | `createAuthenticatedClient` |
+| Calling an external service through its own SDK (Twilio, Google APIs, Stripe) | `withApiErrorHandling` around the SDK calls — the SDK owns transport, you standardize failures |
+| Logging or classifying a caught error from any external call | `normalizeApiError` |
+| Surfacing an external failure to your API's consumers from a route handler | `withApiErrorHandling` with `rethrowAs: "apiError"` |
+| Making internal requests to your own `@terreno/api` backend | None of these — use `@terreno/rtk` on the frontend or direct function calls on the backend |
+
+**Rule of thumb:** any file that would otherwise contain `axios.create(...)` plus a token variable plus a `try/catch → axios.isAxiosError → log → throw` block should use these utilities instead.
+
+## Create a client
+
+```typescript
+import {createAuthenticatedClient} from "@terreno/api";
+
+const widgetApi = createAuthenticatedClient({
+  apiName: "widgetService", // used in logs and normalized errors; defaults to baseURL
+  auth: {
+    credentials: {clientId: process.env.WIDGET_CLIENT_ID!, clientSecret: process.env.WIDGET_CLIENT_SECRET!},
+    refreshOn401: true,
+    tokenUrl: "https://api.widgets.example/oauth/token",
+    type: "oauth2",
+  },
+  baseURL: "https://api.widgets.example/v2",
+});
+
+const response = await widgetApi.axios.get("/widgets/123");
+```
+
+Auth strategies:
+
+- `{type: "bearer", getToken}` — you supply an async token fetcher; the client caches the result until `invalidateToken()` is called.
+- `{type: "oauth2", tokenUrl, credentials, refreshOn401}` — the client performs the client-credentials grant itself (HTTP Basic auth, form-encoded). With `refreshOn401: true`, a 401 response invalidates the cached token and retries the request exactly once with a fresh one.
+- `{type: "apiKey", header, getKey}` — the key is sent on the header you name.
+
+Tokens are fetched lazily and concurrent first requests share a single fetch. Create the client once per service at module scope — not per request — so the token cache is actually shared.
+
+## What you get for free
+
+- **Retry with backoff** for transient failures (429 rate limits, 5xx, network errors), honoring `Retry-After`, capped by `maxDelayMs`. Defaults: 3 total attempts, 250ms base delay, 30s delay ceiling — override via the `retry` option.
+- **Idempotency safety**: only GET/HEAD/OPTIONS are retried by default. Retrying a failed POST can duplicate side effects (a payment, a prescription, a meeting). If a specific POST/PUT/DELETE is genuinely safe to repeat, opt it in per request:
+
+  ```typescript
+  import {markRetryUnsafe} from "@terreno/api";
+
+  // Safe to repeat: the upstream endpoint is idempotent on externalId.
+  await widgetApi.axios.post("/widgets", {externalId, name}, markRetryUnsafe());
+  ```
+
+  The request body must be replayable — JSON is fine; streams/FormData are consumed on first send.
+- **Quiet transport logging**: the client logs retries and token refreshes at debug level only and always rejects with the original axios error. Error-level logging belongs to the call site (next section) so composed usage logs each failure exactly once.
+
+## Handle failures at the call site
+
+Wrap calls with `withApiErrorHandling` to normalize, log once, and rethrow:
+
+```typescript
+import {withApiErrorHandling} from "@terreno/api";
+
+export const getWidget = async (id: string): Promise<Widget> => {
+  const response = await withApiErrorHandling(() => widgetApi.axios.get(`/widgets/${id}`), {
+    apiName: "widgetService",
+    operation: "getWidget",
+  });
+  return response.data;
+};
+```
+
+- Default (`rethrowAs: "raw"`): logs the normalized shape (status code, classification, extracted messages) and rethrows the original error for callers that need it.
+- `rethrowAs: "apiError"`: throws a terreno `APIError` (stable title, per-occurrence `detail`) so route handlers surface a clean JSONAPI error instead of a raw axios failure. In this mode the `APIError` constructor does the logging.
+
+For SDK-based integrations where `createAuthenticatedClient` doesn't apply, `withApiErrorHandling` still works — `normalizeApiError` classifies non-axios errors as `"unknown"` while preserving the message.
+
+## Sensitive response data
+
+`normalizeApiError` never logs raw payload bodies: it extracts only recognized message fields (`{message}`, JSONAPI `{errors: [{title, detail}]}`, plain strings truncated to 500 chars). If the upstream service puts sensitive data *inside* those message fields, supply a `redactError` hook (available on both `createAuthenticatedClient` and `withApiErrorHandling`):
+
+```typescript
+redactError: (normalized) => ({
+  ...normalized,
+  messages: normalized.messages.map((message) => message.replace(PATIENT_ID_PATTERN, "[redacted]")),
+}),
+```
+
+Note the hook's output classification also feeds the client's retry decision — redact messages, don't rewrite classifications, unless changing retry behavior is intended.
+
+## When not to use this
+
+- **Your own backend's routes** — use the generated `@terreno/rtk` SDK (frontend) or call the function directly (backend).
+- **SDK-managed transport** (Twilio, googleapis) — don't fight the SDK's HTTP layer; adopt only `normalizeApiError`/`withApiErrorHandling` for consistent failure handling.
+- **Webhook notifiers** — `sendSlackMessage`/`sendGoogleChatMessage`/`sendZoomMessage` already exist; see [Webhooks & Notifications](../reference/api.md#webhooks--notifications).
+
+## Related
+
+- [@terreno/api reference — HTTP Client](../reference/api.md#http-client)