@terreno/mcp 0.21.0

package/src/docs/templates/bootstrap/frontend/store/openApiSdk.template.md

@@ -0,0 +1,49 @@
+// THIS FILE IS AUTO-GENERATED. DO NOT EDIT.
+// Run "bun run sdk" to regenerate this file from the backend OpenAPI spec.
+
+import {emptySplitApi as api} from "@terreno/rtk";
+export const addTagTypes = ["Users", "Auth"] as const;
+const injectedRtkApi = api
+  .enhanceEndpoints({
+    addTagTypes,
+  })
+  .injectEndpoints({
+    endpoints: (build) => ({
+      emailLogin: build.mutation<EmailLoginRes, EmailLoginArgs>({
+        query: (queryArg) => ({
+          body: queryArg,
+          method: "POST",
+          url: `/auth/login`,
+        }),
+      }),
+      emailSignUp: build.mutation<EmailSignUpRes, EmailSignUpArgs>({
+        query: (queryArg) => ({
+          body: queryArg,
+          method: "POST",
+          url: `/auth/signup`,
+        }),
+      }),
+    }),
+    overrideExisting: false,
+  });
+export {injectedRtkApi as openapi};
+export type EmailLoginArgs = {
+  email: string;
+  password: string;
+};
+export type EmailLoginRes = {
+  token: string;
+  refreshToken: string;
+  userId: string;
+};
+export type EmailSignUpArgs = {
+  email: string;
+  password: string;
+  name: string;
+};
+export type EmailSignUpRes = {
+  token: string;
+  refreshToken: string;
+  userId: string;
+};
+export const {useEmailLoginMutation, useEmailSignUpMutation} = injectedRtkApi;

package/src/docs/templates/bootstrap/frontend/store/sdk.template.md

@@ -0,0 +1,78 @@
+import {generateTags} from "@terreno/rtk";
+import startCase from "lodash/startCase";
+
+import {addTagTypes, openapi} from "./openApiSdk";
+
+export interface ProfileResponse {
+  data: {
+    _id: string;
+    id: string;
+    email: string;
+    name: string;
+  };
+}
+
+export interface UpdateProfileRequest {
+  name?: string;
+  email?: string;
+  password?: string;
+}
+
+export const terrenoApi = openapi
+  .injectEndpoints({
+    endpoints: (builder) => ({
+      getMe: builder.query<ProfileResponse, void>({
+        providesTags: ["profile"],
+        query: () => ({
+          method: "GET",
+          url: "/auth/me",
+        }),
+      }),
+      patchMe: builder.mutation<ProfileResponse, UpdateProfileRequest>({
+        invalidatesTags: ["profile"],
+        query: (body) => ({
+          body,
+          method: "PATCH",
+          url: "/auth/me",
+        }),
+      }),
+    }),
+  })
+  .enhanceEndpoints({
+    addTagTypes: ["profile"],
+    endpoints: {
+      ...generateTags(openapi, [...addTagTypes]),
+    },
+  });
+
+export const {
+  useEmailLoginMutation,
+  useEmailSignUpMutation,
+  useGetMeQuery,
+  usePatchMeMutation,
+} = terrenoApi;
+export * from "./openApiSdk";
+
+type OpenApiEndpoints = Record<string, unknown>;
+
+export const getSdkHook = (
+  modelName: string,
+  type: "list" | "read" | "create" | "update" | "remove"
+): Record<string, unknown> => {
+  const modelPath = startCase(modelName).replace(/\s/g, "");
+  const endpoints = openapi.endpoints as OpenApiEndpoints;
+  switch (type) {
+    case "list":
+      return endpoints[`get${modelPath}`] as Record<string, unknown>;
+    case "read":
+      return endpoints[`get${modelPath}ById`] as Record<string, unknown>;
+    case "create":
+      return endpoints[`post${modelPath}`] as Record<string, unknown>;
+    case "update":
+      return endpoints[`patch${modelPath}ById`] as Record<string, unknown>;
+    case "remove":
+      return endpoints[`delete${modelPath}ById`] as Record<string, unknown>;
+    default:
+      throw new Error(`Invalid SDK hook: ${modelName}/${type}`);
+  }
+};

package/src/docs/templates/bootstrap/frontend/utils/index.template.md

@@ -0,0 +1,11 @@
+export const captureException = (error: unknown): void => {
+  console.error("Captured exception:", error);
+};
+
+export const captureMessage = (message: string): void => {
+  console.warn("Captured message:", message);
+};
+
+export const createSentryReduxEnhancer = (): unknown => {
+  return undefined;
+};

package/src/docs/templates/tools/form.template.tsx

@@ -0,0 +1,47 @@
+import {Box, Button, {additionalImports}} from "@terreno/ui";
+
+import type React from "react";
+import {useCallback, } from "react";
+
+interface {{Name}}FormProps {
+  initialValues?: Partial<{{Name}}FormValues>;
+  onSubmit: (_values: {{Name}}_FormValues) => Promise<void>;
+  isLoading?: boolean;
+}
+
+interface {{Name}}FormValues {interfaceFields
+}
+
+export const {{Name}}Form: React.FC<{Name}FormProps> = ({
+  initialValues,
+  onSubmit,
+  isLoading,
+}) => {stateDeclarationserrorStateDeclarations
+
+  const validate = useCallback((): boolean => {
+    const isValid = true;validationLogic
+    return isValid;
+  }, [{{validationDependencies}}]);
+
+  const _handleSubmit = useCallback(async (): Promise<void> => {
+    if (!validate()) {
+      return;
+    }
+    await onSubmit({
+{{submitValues}}
+    });
+  }, [{{submitDependencies}}]);
+
+  return (
+    <Box gap={4}>
+{{formFields}}
+      <Button
+        disabled={isLoading}
+        fullWidth
+        loading={isLoading}
+        onClick={handleSubmit}
+        text="Submit"
+      />
+    </Box>
+  );
+};

package/src/docs/templates/tools/model.template.md

@@ -0,0 +1,24 @@
+import mongoose from "mongoose";
+import {addDefaultPlugins{{softDeleteImport}}} from "@terreno/api";
+
+interface {{Name}}Document extends mongoose.Document {
+{{interfaceFields}}
+}
+
+interface {{Name}}Model extends mongoose.Model<{{Name}}Document> {
+  findOneOrNone(query: mongoose.FilterQuery<{{Name}}Document>): Promise<{{Name}}Document | null>;
+  findExactlyOne(query: mongoose.FilterQuery<{{Name}}Document>): Promise<{{Name}}Document>;
+}
+
+const {{lowerName}}Schema = new mongoose.Schema<{{Name}}Document, {{Name}}Model>(
+  {
+{{schemaFields}}
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+addDefaultPlugins({{lowerName}}Schema);
+{{softDeletePlugin}}
+
+export const {{Name}} = mongoose.model<{{Name}}Document, {{Name}}Model>("{{Name}}", {{lowerName}}Schema);
+export type {{{Name}}Document, {{Name}}Model};

package/src/docs/templates/tools/route.template.md

@@ -0,0 +1,26 @@
+import {Permissions, type ModelRouterOptions, modelRouter{{additionalImports}}} from "@terreno/api";
+import type {Router} from "express";
+import {{{Name}}} from "../models";
+import type {{{Name}}Document} from "../types";
+
+export const add{{Name}}Routes = (
+  router: Router,
+  options?: Partial<ModelRouterOptions<{{Name}}Document>>
+): void => {
+  router.use(
+    "/{{routePath}}",
+    modelRouter({{Name}}, {
+      ...options,
+      permissions: {
+        create: [{{createPermissions}}],
+        delete: [{{deletePermissions}}],
+        list: [{{listPermissions}}],
+        read: [{{readPermissions}}],
+        update: [{{updatePermissions}}],
+      },
+      {{queryFilter}}
+      queryFields: [{{queryFields}}],
+      sort: "{{sort}}",
+    })
+  );
+};

package/src/docs/templates/tools/screen.template.tsx

@@ -0,0 +1,38 @@
+import {Box, Page, Text, Spinner{additionalImports}} from "@terreno/ui";
+
+import type React from "react";
+
+{hookImports}{sdkHooks}} from "@/store";
+
+const {{Name}}Screen: React.FC = () => {queryHooks
+
+  if (isLoading) {
+    return (
+      <Page navigation={undefined} title="{{title}}">
+        <Box alignItems="center" flex="grow" justifyContent="center" padding={4}>
+          <Spinner />
+        </Box>
+      </Page>
+    );
+  }
+
+  if (error) {
+    return (
+      <Page navigation={undefined} title="{{title}}">
+        <Box padding={4}>
+          <Text color="error">Failed to load {{lowerName}}</Text>
+        </Box>
+      </Page>
+    );
+  }
+
+  return (
+    <Page navigation={undefined} title="{{title}}">
+      <Box gap={4} padding={4}>
+        {{screenContent}}
+      </Box>
+    </Page>
+  );
+};
+
+export default {{Name}}Screen;

package/src/docs/templates/tools/validation.template.md

@@ -0,0 +1,12 @@
+export const validate{{Name}} = (values: {{Name}}FormValues): Record<string, string> => {
+  const errors: Record<string, string> = {};
+
+{{validationRules}}
+
+  return errors;
+};
+
+export const isValid{{Name}} = (values: {{Name}}FormValues): boolean => {
+  const errors = validate{{Name}}(values);
+  return Object.keys(errors).length === 0;
+};

package/src/docs/ui-types-documentation.json

@@ -0,0 +1,33 @@
+{
+  "children": [
+    {
+      "name": "Common",
+      "children": [
+        {
+          "name": "ButtonProps",
+          "kind": 256,
+          "children": [
+            {
+              "name": "text",
+              "type": {"type": "intrinsic", "name": "string"},
+              "flags": {},
+              "comment": {"summary": [{"text": "Button text"}]}
+            },
+            {
+              "name": "onClick",
+              "type": {
+                "type": "reflection",
+                "declaration": {"signatures": [{}]}
+              },
+              "flags": {"isOptional": true}
+            }
+          ]
+        },
+        {
+          "name": "NotAnInterface",
+          "kind": 128
+        }
+      ]
+    }
+  ]
+}

package/src/docs/upgrades/0.20.0.md

@@ -0,0 +1,8 @@
+# 0.20.0
+
+Terreno packages move in lockstep. Review the consolidated changelog for this release and run:
+
+- `bun run compile` and `bun run lint` at the repo root
+- `cd example-frontend && bun run sdk` after any `@terreno/api` route or model surface change
+
+For Expo SDK bumps, use the official Expo `upgrading-expo` skill (`expo/skills`) for SDK-specific steps; keep Terreno-specific notes in this file for `@terreno/ui`, `@terreno/rtk`, and `@terreno/api` breaking changes.

package/src/docs/upgrades/0.21.0.md

@@ -0,0 +1,59 @@
+# 0.21.0
+
+Terreno packages move in lockstep. Review the consolidated changelog for this release and run:
+
+- `bun run compile` and `bun run lint` at the repo root
+- `cd example-frontend && bun run sdk` after any `@terreno/api` route or model surface change
+
+## `@terreno/api` — migrate off `setupServer`
+
+`setupServer` and `initializeRoutes` were removed. Use `TerrenoApp` only:
+
+```typescript
+// Before
+setupServer({
+  userModel: User,
+  addRoutes: (router, options) => {
+    router.use("/todos", modelRouter(Todo, options));
+  },
+  addMiddleware: (app) => {
+    app.use(sessionMiddleware);
+  },
+});
+
+// After
+new TerrenoApp({
+  userModel: User,
+  configureApp: (router, { openApi }) => {
+    router.use("/todos", modelRouter(Todo, { openApi }));
+  },
+  beforeJsonSetup: (app) => {
+    app.use(sessionMiddleware);
+  },
+})
+  .register(todoRouter)
+  .start();
+```
+
+- `configureApp` runs after registered plugins/model routers and before `/auth/me`.
+- `beforeJsonSetup` runs after CORS and before the JSON parser — same slot as the old `addMiddleware` on `setupServer`.
+
+See `example-backend/src/server.ts` and `api/src/example.ts` for current patterns.
+
+## `@terreno/api` — `requestId` on JSON object responses
+
+`TerrenoApp` injects `requestId` into plain-object JSON response bodies (aligned with the `X-Request-ID` header). This does **not** apply to:
+
+- JSON arrays (list endpoints still return `{ data, page, limit, total, more }` with `requestId` on the wrapper object)
+- `GET /openapi.json`
+- Primitive JSON bodies
+
+If your client validates response shapes strictly, allow an optional `requestId` string on object payloads.
+
+## `@terreno/admin-backend` — Admin UI v2 config
+
+`GET /admin/config` now includes `schemaVersion: 2` and richer per-model metadata. Legacy v1 fields (`models`, `listFields`, `fields`, …) are unchanged — existing admin clients keep working. New endpoints: `POST {route}/bulk-patch` and `POST /admin/background-tasks`.
+
+## `@terreno/ui` — Card visual changes
+
+`Card` no longer applies shadow by default. The `display` variant adds title, description, optional action button, size, and cover image with responsive row/column layout. Review screens that relied on the old bordered-box-only Card appearance.

package/src/docs/versioned/0.19.0/README.md

@@ -0,0 +1,29 @@
+# Terreno Documentation
+
+Documentation for the Terreno monorepo: shared packages for full-stack applications with React Native and Express/Mongoose.
+
+## Structure
+
+- **[Tutorials](tutorials/)** — Learning-oriented, hands-on lessons
+- **[How-to guides](how-to/)** — Problem-oriented, practical steps
+- **[Reference](reference/)** — Technical reference for APIs and packages
+- **[Explanation](explanation/)** — Concepts and context
+- **[Implementation Plans](implementationPlans/)** — Forward-looking plans for major features
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [@terreno/api](reference/api.md) | REST API framework (Express/Mongoose) |
+| [@terreno/ui](reference/ui.md) | React Native UI component library |
+| [@terreno/rtk](reference/rtk.md) | RTK Query utilities for API backends |
+| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin |
+| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens |
+| [@terreno/api-health](reference/api-health.md) | Health check endpoint plugin |
+| [@terreno/mcp-server](reference/mcp-server.md) | AI coding assistant integration (MCP) |
+
+## Quick links
+
+- [Getting started](tutorials/getting-started.md)
+- [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
+- [.cursorrules](../.cursorrules) — Project and code style rules

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

@@ -0,0 +1,13 @@
+# 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