@terreno/mcp 0.24.0 → 0.26.0

package/dist/docs/versioned/0.24.0/reference/generated/api/classes/TerrenoApp.md

@@ -0,0 +1,262 @@
+Fluent API for building Express applications with Terreno framework.
+
+TerrenoApp is the supported way to assemble the Terreno Express stack.
+Build applications by registering model routers and plugins (and/or
+`configureApp`), then calling `start()` to listen.
+
+The middleware stack is configured in this order:
+1. CORS
+2. Optional `beforeJsonSetup` (configure the app before JSON parsing)
+3. Custom middleware (via addMiddleware)
+4. JSON body parser
+5. Auth routes (/auth/login, /auth/signup, etc.)
+6. JWT authentication setup
+7. Request logging
+8. Sentry scopes
+9. OpenAPI middleware (including JSON `requestId` on object responses)
+10. GitHub OAuth routes (if enabled)
+11. Configuration app (if any)
+12. Registered model routers and plugins
+13. Optional `configureApp` callback
+14. /auth/me routes
+15. Error handling middleware
+
+## Examples
+
+```typescript
+// Basic usage with model routers
+const todoRouter = modelRouter("/todos", Todo, {
+  permissions: { list: [Permissions.IsAuthenticated], ... },
+});
+
+const app = new TerrenoApp({ userModel: User })
+  .register(todoRouter)
+  .register(new HealthApp())
+  .start();
+```
+
+```typescript
+// With custom middleware
+const app = new TerrenoApp({
+  userModel: User,
+  corsOrigin: ["https://app.example.com"],
+  loggingOptions: { logRequests: true },
+  githubAuth: {
+    clientId: process.env.GITHUB_CLIENT_ID!,
+    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    callbackURL: process.env.GITHUB_CALLBACK_URL!,
+  },
+})
+  .addMiddleware((req, res, next) => {
+    res.setHeader("X-Custom-Header", "value");
+    next();
+  })
+  .register(todoRouter)
+  .register(userRouter)
+  .start();
+```
+
+## See
+
+ - TerrenoPlugin for creating reusable plugins
+ - modelRouter for creating CRUD route registrations
+
+## Constructors
+
+### Constructor
+
+> **new TerrenoApp**(`options`): `TerrenoApp`
+
+Create a new TerrenoApp builder.
+
+#### Parameters
+
+##### options
+
+[`TerrenoAppOptions`](../interfaces/TerrenoAppOptions.md)
+
+Application configuration options including user model and auth settings
+
+#### Returns
+
+`TerrenoApp`
+
+## Methods
+
+### addMiddleware()
+
+> **addMiddleware**(`fn`): `this`
+
+Add custom Express middleware to the application.
+
+Middleware is added BEFORE JSON body parsing and authentication setup,
+allowing you to modify incoming requests early in the middleware stack.
+
+#### Parameters
+
+##### fn
+
+`RequestHandler`\<`ParamsDictionary`, `any`, `any`, `ParsedQs`, `Record`\<`string`, `any`\>\> \| ((`app`) => `void`)
+
+Express middleware function or a function that configures the app
+
+#### Returns
+
+`this`
+
+This TerrenoApp instance for method chaining
+
+#### Example
+
+```typescript
+app.addMiddleware((req, res, next) => {
+  res.setHeader("X-Request-ID", req.id);
+  next();
+});
+```
+
+***
+
+### build()
+
+> **build**(): `Application`
+
+Build the Express application without starting the server.
+
+Configures the complete middleware stack including:
+- CORS, JSON parsing, authentication, logging, Sentry, OpenAPI
+- All registered model routers and plugins
+- Error handling middleware
+
+Use this method when you need the Express app instance for testing
+or custom server setup. For normal use, call `start()` instead.
+
+#### Returns
+
+`Application`
+
+Configured Express application instance
+
+#### Example
+
+```typescript
+const app = new TerrenoApp({ userModel: User })
+  .register(todoRouter)
+  .build();
+
+// Use app for testing with supertest
+await request(app).get("/todos").expect(200);
+```
+
+***
+
+### configure()
+
+> **configure**(`model`, `options?`): `this`
+
+Register a configuration model with the application.
+
+Adds configuration management endpoints that expose the model's schema
+as metadata, and provide GET/PATCH endpoints for reading and updating
+the singleton configuration document. Nested subschemas become separate
+sections in the admin UI.
+
+All configuration endpoints require admin authentication.
+
+#### Parameters
+
+##### model
+
+`Model`\<`any`, \{ \}, \{ \}, \{ \}, `any`, `any`\>
+
+Mongoose model with configurationPlugin applied
+
+##### options?
+
+`Omit`\<[`ConfigurationAppOptions`](../interfaces/ConfigurationAppOptions.md), `"model"`\>
+
+Optional configuration (basePath, fieldOverrides)
+
+#### Returns
+
+`this`
+
+This TerrenoApp instance for method chaining
+
+#### Example
+
+```typescript
+const app = new TerrenoApp({ userModel: User })
+  .configure(AppConfig)
+  .register(todoRouter)
+  .start();
+```
+
+***
+
+### register()
+
+> **register**(`registration`): `this`
+
+Register a model router or plugin with the application.
+
+Model routers are created with `modelRouter("/path", Model, options)` and
+provide CRUD endpoints. Plugins implement `TerrenoPlugin` interface and
+can register custom routes and middleware.
+
+Registrations are mounted in the order they are added.
+
+#### Parameters
+
+##### registration
+
+[`ModelRouterRegistration`](../interfaces/ModelRouterRegistration.md) \| [`TerrenoPlugin`](../interfaces/TerrenoPlugin.md)
+
+A ModelRouterRegistration from modelRouter() or a TerrenoPlugin instance
+
+#### Returns
+
+`this`
+
+This TerrenoApp instance for method chaining
+
+#### Example
+
+```typescript
+const todoRouter = modelRouter("/todos", Todo, options);
+const healthPlugin = new HealthApp({ path: "/health" });
+
+app.register(todoRouter).register(healthPlugin);
+```
+
+***
+
+### start()
+
+> **start**(): `Application`
+
+Build the Express application and start listening on the configured port.
+
+Calls `build()` to configure the application, then starts an HTTP server
+listening on the port specified by the `PORT` environment variable (default: 9000).
+If `skipListen` option is true, the app is built but the server is not started.
+
+#### Returns
+
+`Application`
+
+Configured Express application instance
+
+#### Throws
+
+Process exits with code 1 if the server fails to start
+
+#### Example
+
+```typescript
+// Start server on port 3000
+process.env.PORT = "3000";
+const app = new TerrenoApp({ userModel: User })
+  .register(todoRouter)
+  .start();
+```

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/createFeatureFlaggedLogger.md

@@ -0,0 +1,53 @@
+> **createFeatureFlaggedLogger**(`options`): [`ScopedLogger`](../interfaces/ScopedLogger.md)
+
+Wraps a [ScopedLogger](../interfaces/ScopedLogger.md) so all `debug` / `info` / `warn` / `error` traffic is dropped while
+`isEnabled()` returns false. Use it to keep verbose diagnostics in the code but silent until a
+flag turns them on — no redeploy required.
+
+`isEnabled` is evaluated on **every** call, so it can read any feature-flag source: an
+environment variable, a cached/remote flag map, or a call into `@terreno/feature-flags` from your
+app. (`@terreno/api` deliberately does not import `@terreno/feature-flags` to avoid a package
+cycle — you supply the predicate.)
+
+## Parameters
+
+### options
+
+[`CreateFeatureFlaggedLoggerOptions`](../interfaces/CreateFeatureFlaggedLoggerOptions.md)
+
+The `isEnabled` predicate plus an optional `target` logger and `gateCatch`.
+
+## Returns
+
+[`ScopedLogger`](../interfaces/ScopedLogger.md)
+
+A scoped logger that forwards to `target` only while the flag is enabled.
+
+## See
+
+[createScopedLogger](createScopedLogger.md) for the usual `target`.
+
+## Examples
+
+**Gate a scoped logger behind an env var (flips live, no restart)**
+
+```typescript
+import {createFeatureFlaggedLogger, createScopedLogger} from "@terreno/api";
+
+const jobLog = createFeatureFlaggedLogger({
+  isEnabled: () => process.env.JOB_TRACE_LOGS === "true",
+  target: createScopedLogger({prefix: "[Job]", labels: {jobName: "nightly-sync"}}),
+});
+
+jobLog.info("step 1"); // silent unless JOB_TRACE_LOGS=true
+```
+
+**Drive it from \`@terreno/feature-flags\` in app code**
+
+```typescript
+const debugLog = createFeatureFlaggedLogger({
+  isEnabled: () => flags.isEnabled("debug.billing"),
+  target: createScopedLogger({prefix: "[Billing]"}),
+  gateCatch: true, // also silence `catch` while the flag is off (default: false)
+});
+```

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/createScopedLogger.md

@@ -0,0 +1,53 @@
+> **createScopedLogger**(`options?`): [`ScopedLogger`](../interfaces/ScopedLogger.md)
+
+Creates a [ScopedLogger](../interfaces/ScopedLogger.md) that prefixes every message and/or attaches stable `labels` to
+every line, so multi-step workflows are easy to group and search.
+
+- `prefix` is prepended to the human-readable message (easy grep / Log Explorer text search) and
+  also stored as the Winston metadata field `terrenoLogPrefix`.
+- `labels` are normalized to strings and stored as the Winston metadata field `terrenoLabels`.
+  They appear in the plain-text ` key=value` suffix (see [formatLogContextSuffix](formatLogContextSuffix.md)) and as
+  discrete fields on structured transports such as `@google-cloud/logging-winston`.
+
+Both ride on a Winston **child logger**, so they merge with — and never overwrite — the
+request/job correlation fields that AsyncLocalStorage injects (`requestId`, `userId`,
+`terrenoRequestLog`, etc.). Avoid label keys that collide with those framework fields:
+`requestId`, `jobId`, `sessionId`, `userId`, `traceId`, `spanId`, `terrenoLogPrefix`,
+`terrenoRequestLog`, `terrenoLabels`.
+
+If both `prefix` and `labels` are empty, the global [logger](../variables/logger.md) is returned unchanged.
+
+## Parameters
+
+### options?
+
+[`CreateScopedLoggerOptions`](../interfaces/CreateScopedLoggerOptions.md) = `{}`
+
+Optional `prefix` token and/or `labels` dimensions for this scope.
+
+## Returns
+
+[`ScopedLogger`](../interfaces/ScopedLogger.md)
+
+A scoped logger sharing the same methods as the global [logger](../variables/logger.md).
+
+## See
+
+[createFeatureFlaggedLogger](createFeatureFlaggedLogger.md) to gate a scoped logger behind a feature flag.
+
+## Example
+
+**Reuse one instance for a whole workflow so every line shares identifiers**
+
+```typescript
+import {createScopedLogger} from "@terreno/api";
+
+const log = createScopedLogger({
+  prefix: "[InvoicePay]",
+  labels: {invoiceId: invoice._id.toString(), attempt: String(attemptNumber)},
+});
+
+log.info("Starting capture");        // -> "[InvoicePay] Starting capture invoiceId=... attempt=1 requestId=..."
+log.warn("Stripe rate limited, backing off");
+await capture(invoice).catch(log.catch);
+```

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/createScriptArgs.md

@@ -0,0 +1,33 @@
+> **createScriptArgs**(`__namedParameters`): `object`
+
+Build a [ScriptArgs](../interfaces/ScriptArgs.md) accessor from a raw values map and optional declarations.
+Applies declared defaults, coerces declared types, and validates required args.
+Returns the accessor plus any validation errors (callers decide how to surface them).
+
+## Parameters
+
+### \_\_namedParameters
+
+#### defs?
+
+[`ScriptArgDef`](../interfaces/ScriptArgDef.md)[] = `[]`
+
+#### positional?
+
+`string`[] = `[]`
+
+#### values
+
+`Record`\<`string`, [`ScriptArgValue`](../type-aliases/ScriptArgValue.md)\>
+
+## Returns
+
+`object`
+
+### args
+
+> **args**: [`ScriptArgs`](../interfaces/ScriptArgs.md)
+
+### errors
+
+> **errors**: `string`[]

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/defaultResponseHandler.md

@@ -0,0 +1,32 @@
+> **defaultResponseHandler**\<`T`\>(`doc`, `method`, `request`, `options`): `Promise`\<`Partial`\<`T`\> \| (`Partial`\<`T`\> \| `undefined`)[] \| `null` \| `undefined`\>
+
+Default response handler for modelRouter. Calls toObject on each doc and returns the result,
+using transformers.serializer if provided.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### doc
+
+`Document`\<`unknown`, `unknown`, `unknown`, `Record`\<`string`, `any`\>, \{ \}\> & `T` \| `Document`\<`unknown`, `unknown`, `unknown`, `Record`\<`string`, `any`\>, \{ \}\> & `T`[] \| `null`
+
+### method
+
+`"read"` \| `"list"` \| `"create"` \| `"update"`
+
+### request
+
+`Request`
+
+### options
+
+[`ModelRouterOptions`](../interfaces/ModelRouterOptions.md)\<`T`\>
+
+## Returns
+
+`Promise`\<`Partial`\<`T`\> \| (`Partial`\<`T`\> \| `undefined`)[] \| `null` \| `undefined`\>

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/formatLogContextSuffix.md

@@ -0,0 +1,17 @@
+> **formatLogContextSuffix**(`fields`): `string`
+
+Builds the ` key=value ...` suffix appended to console/file log lines after the message.
+Request-scoped fields come from AsyncLocalStorage via Winston metadata; `terrenoLabels` and
+`terrenoLogPrefix` come from [createScopedLogger](createScopedLogger.md). Nested `terrenoRequestLog`
+(`requestId` + `userId` including `null` when anonymous) is attached on the Winston info
+object for structured transports only, not repeated in this suffix.
+
+## Parameters
+
+### fields
+
+[`LogContextFields`](../interfaces/LogContextFields.md)
+
+## Returns
+
+`string`

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/getCurrentLogContext.md

@@ -0,0 +1,9 @@
+> **getCurrentLogContext**(): `Partial`\<[`RequestContext`](../interfaces/RequestContext.md)\>
+
+Returns the active correlation fields as a plain object (empty when outside a scope). This is the
+shape attached to Sentry log attributes and is handy when you need to log or forward the current
+context yourself.
+
+## Returns
+
+`Partial`\<[`RequestContext`](../interfaces/RequestContext.md)\>

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/getCurrentRequestContext.md

@@ -0,0 +1,8 @@
+> **getCurrentRequestContext**(): [`RequestContext`](../interfaces/RequestContext.md) \| `undefined`
+
+Returns the full [RequestContext](../interfaces/RequestContext.md) for the active AsyncLocalStorage scope, or `undefined`
+when called outside any request/job scope. The logger uses this to enrich each line.
+
+## Returns
+
+[`RequestContext`](../interfaces/RequestContext.md) \| `undefined`

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/getCurrentRequestContextAttributes.md

@@ -0,0 +1,15 @@
+> **getCurrentRequestContextAttributes**(`overrides?`): [`RequestContextAttributes`](../type-aliases/RequestContextAttributes.md)
+
+Serializes the active correlation context into HTTP header attributes (keyed by
+[REQUEST\_CONTEXT\_ATTRIBUTE\_NAMES](../variables/REQUEST_CONTEXT_ATTRIBUTE_NAMES.md)) so it can be propagated on outbound requests to other
+services, keeping the same `requestId`/`traceId` across service boundaries.
+
+## Parameters
+
+### overrides?
+
+`Partial`\<[`RequestContext`](../interfaces/RequestContext.md)\> = `{}`
+
+## Returns
+
+[`RequestContextAttributes`](../type-aliases/RequestContextAttributes.md)

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/jsonResponseRequestIdMiddleware.md

@@ -0,0 +1,24 @@
+> **jsonResponseRequestIdMiddleware**(`req`, `res`, `next`): `void`
+
+TerrenoApp middleware: augments `res.json` so plain-object payloads include
+`requestId` for client correlation. Skips OpenAPI tooling GET JSON routes
+(`/openapi.json`, `/openapi/components/...json`, `/openapi/validate`) so
+machine-consumed payloads stay valid. Does not wrap arrays or primitives.
+
+## Parameters
+
+### req
+
+`Request`
+
+### res
+
+`Response`
+
+### next
+
+`NextFunction`
+
+## Returns
+
+`void`

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/logRequests.md

@@ -0,0 +1,19 @@
+> **logRequests**(`req`, `res`, `next`): `void`
+
+## Parameters
+
+### req
+
+`LoggableRequest`
+
+### res
+
+`LoggableResponse`
+
+### next
+
+`NextFunction`
+
+## Returns
+
+`void`

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/matchesQuery.md

@@ -0,0 +1,23 @@
+> **matchesQuery**(`doc`, `query`): `boolean`
+
+Check if a document matches a MongoDB-style query in memory.
+
+## Parameters
+
+### doc
+
+`Record`\<`string`, `unknown`\>
+
+The document to test (plain object or Mongoose document)
+
+### query
+
+`Record`\<`string`, `unknown`\>
+
+MongoDB-style query object
+
+## Returns
+
+`boolean`
+
+true if the document matches all query conditions

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/parseScriptArgs.md

@@ -0,0 +1,35 @@
+> **parseScriptArgs**(`tokens`, `defs?`): `object`
+
+Parse CLI-style tokens into a [ScriptArgs](../interfaces/ScriptArgs.md) accessor. Supports a flexible set
+of conventions so callers and scripts do not need to agree on a rigid format:
+
+- `--name=value` and `--name value`
+- `--flag` (boolean true) and `--no-flag` (boolean false)
+- short aliases `-x` (treated like `--x`)
+- repeated flags collapse into a string array
+- bare tokens become positional arguments
+
+When [declarations](../interfaces/ScriptArgDef.md) are supplied, values are coerced to the
+declared type, defaults are applied, and required args are validated.
+
+## Parameters
+
+### tokens
+
+`string`[]
+
+### defs?
+
+[`ScriptArgDef`](../interfaces/ScriptArgDef.md)[] = `[]`
+
+## Returns
+
+`object`
+
+### args
+
+> **args**: [`ScriptArgs`](../interfaces/ScriptArgs.md)
+
+### errors
+
+> **errors**: `string`[]

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/requestContextMiddleware.md

@@ -0,0 +1,26 @@
+> **requestContextMiddleware**(`req`, `res`, `next`): `void`
+
+Express middleware that opens a correlation scope for the request. Mounted early by `TerrenoApp` /
+`setupServer`, it resolves a `requestId` (from request-id/correlation headers, Cloud Trace, or
+W3C `traceparent`, else a new UUID), captures any `jobId`/`sessionId`/trace fields, echoes
+`X-Request-ID` back to the client, and runs the remaining middleware inside the scope so all
+downstream logs are correlated. A later auth-aware pass ([updateRequestContextFromRequest](updateRequestContextFromRequest.md))
+fills in `userId`/`sessionId`.
+
+## Parameters
+
+### req
+
+`Request`
+
+### res
+
+`Response`
+
+### next
+
+`NextFunction`
+
+## Returns
+
+`void`

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/runWithRequestContext.md

@@ -0,0 +1,38 @@
+> **runWithRequestContext**\<`T`\>(`context`, `callback`): `T`
+
+Runs `callback` inside a fresh correlation scope so every log line it emits shares the same
+identifiers — the manual equivalent of [requestContextMiddleware](requestContextMiddleware.md) for background jobs,
+cron tasks, scripts, queue consumers, etc. A `requestId` is generated when not supplied, and the
+context is mirrored to Sentry.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### context
+
+`Partial`\<[`RequestContext`](../interfaces/RequestContext.md)\>
+
+### callback
+
+() => `T`
+
+## Returns
+
+`T`
+
+## Example
+
+```typescript
+import {createScopedLogger, runWithRequestContext} from "@terreno/api";
+
+await runWithRequestContext({jobId: "nightly-sync"}, async () => {
+  const log = createScopedLogger({prefix: "[NightlySync]"});
+  log.info("started"); // includes jobId + a generated requestId on every line
+  await sync();
+});
+```

package/dist/docs/versioned/0.24.0/reference/generated/api/functions/runWithRequestContextAttributes.md

@@ -0,0 +1,25 @@
+> **runWithRequestContextAttributes**\<`T`\>(`attributes?`, `callback`): `T`
+
+Like [runWithRequestContext](runWithRequestContext.md), but seeds the scope from raw header attributes (for example
+those received on an incoming message or forwarded by another service). Parses Cloud Trace / W3C
+`traceparent` into `traceId`/`spanId` via [getRequestContextFromAttributes](getRequestContextFromAttributes.md).
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### attributes?
+
+`Record`\<`string`, `string` \| `undefined`\> = `{}`
+
+### callback
+
+() => `T`
+
+## Returns
+
+`T`