@terreno/api 0.3.1 → 0.4.2

package/src/scriptRunner.ts

@@ -0,0 +1,219 @@
+import {DateTime} from "luxon";
+import mongoose, {type Document, type Model, Schema} from "mongoose";
+
+import {createdUpdatedPlugin, findExactlyOne, findOneOrNone, isDeletedPlugin} from "./plugins";
+
+// --- Script Runner Types & BackgroundTask Model ---
+
+export interface ScriptResult {
+  success: boolean;
+  results: string[];
+}
+
+export interface ScriptContext {
+  /** Check if the task has been cancelled. Throws TaskCancelledError if so. */
+  checkCancellation: () => Promise<void>;
+  /** Add a log entry to the task. */
+  addLog: (level: "info" | "warn" | "error", message: string) => Promise<void>;
+  /** Update progress on the task. */
+  updateProgress: (percentage: number, stage?: string, message?: string) => Promise<void>;
+}
+
+export type ScriptRunner = (wetRun: boolean, ctx?: ScriptContext) => Promise<ScriptResult>;
+
+export class TaskCancelledError extends Error {
+  constructor(taskId: string) {
+    super(`Task ${taskId} was cancelled`);
+    this.name = "TaskCancelledError";
+  }
+}
+
+// --- BackgroundTask Model ---
+
+interface BackgroundTaskProgress {
+  percentage: number;
+  stage?: string;
+  message?: string;
+}
+
+interface BackgroundTaskLog {
+  timestamp: Date;
+  level: "info" | "warn" | "error";
+  message: string;
+}
+
+export type BackgroundTaskMethods = {
+  addLog: (
+    this: BackgroundTaskDocument,
+    level: "info" | "warn" | "error",
+    message: string
+  ) => Promise<void>;
+  updateProgress: (
+    this: BackgroundTaskDocument,
+    percentage: number,
+    stage?: string,
+    message?: string
+  ) => Promise<void>;
+};
+
+export type BackgroundTaskDocument = Document &
+  BackgroundTaskMethods & {
+    taskType: string;
+    status: "pending" | "running" | "completed" | "failed" | "cancelled";
+    progress?: BackgroundTaskProgress;
+    createdBy?: mongoose.Types.ObjectId;
+    isDryRun: boolean;
+    result?: string[];
+    error?: string;
+    logs: BackgroundTaskLog[];
+    startedAt?: Date;
+    completedAt?: Date;
+    created: Date;
+    updated: Date;
+    deleted: boolean;
+  };
+
+export type BackgroundTaskStatics = {
+  checkCancellation: (taskId: string) => Promise<void>;
+};
+
+export type BackgroundTaskModel = Model<
+  BackgroundTaskDocument,
+  Record<string, never>,
+  BackgroundTaskMethods
+> &
+  BackgroundTaskStatics;
+
+const progressSchema = new Schema(
+  {
+    message: {description: "Human-readable progress message", type: String},
+    percentage: {description: "Progress percentage from 0 to 100", max: 100, min: 0, type: Number},
+    stage: {description: "Current stage of the task", type: String},
+  },
+  {_id: false}
+);
+
+const logSchema = new Schema(
+  {
+    level: {
+      description: "Log level",
+      enum: ["info", "warn", "error"],
+      required: true,
+      type: String,
+    },
+    message: {description: "Log message", required: true, type: String},
+    timestamp: {description: "When this log entry was created", required: true, type: Date},
+  },
+  {_id: false}
+);
+
+const backgroundTaskSchema = new Schema<
+  BackgroundTaskDocument,
+  BackgroundTaskModel,
+  BackgroundTaskMethods
+>(
+  {
+    completedAt: {
+      description: "When the task completed (success or failure)",
+      type: Date,
+    },
+    createdBy: {
+      description: "The user who created this task",
+      ref: "User",
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    error: {
+      description: "Error message if the task failed",
+      type: String,
+    },
+    isDryRun: {
+      default: false,
+      description: "Whether this is a dry run that does not make real changes",
+      type: Boolean,
+    },
+    logs: {
+      default: [],
+      description: "Log entries for the task execution",
+      type: [logSchema],
+    },
+    progress: {
+      description: "Progress information for the task",
+      type: progressSchema,
+    },
+    result: {
+      description: "Result strings when the task completes",
+      type: [String],
+    },
+    startedAt: {
+      description: "When the task started executing",
+      type: Date,
+    },
+    status: {
+      default: "pending",
+      description: "Current status of the task",
+      enum: ["pending", "running", "completed", "failed", "cancelled"],
+      type: String,
+    },
+    taskType: {
+      description: "The type or name of the background task",
+      required: true,
+      type: String,
+    },
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+backgroundTaskSchema.methods = {
+  async addLog(
+    this: BackgroundTaskDocument,
+    level: "info" | "warn" | "error",
+    message: string
+  ): Promise<void> {
+    if (!this.logs) {
+      this.logs = [];
+    }
+    this.logs.push({
+      level,
+      message,
+      timestamp: DateTime.now().toJSDate(),
+    });
+    await this.save();
+  },
+
+  async updateProgress(
+    this: BackgroundTaskDocument,
+    percentage: number,
+    stage?: string,
+    message?: string
+  ): Promise<void> {
+    this.progress = {
+      message: message ?? this.progress?.message,
+      percentage,
+      stage: stage ?? this.progress?.stage,
+    };
+    await this.save();
+  },
+};
+
+backgroundTaskSchema.statics = {
+  async checkCancellation(this: BackgroundTaskModel, taskId: string): Promise<void> {
+    const task = await this.findById(taskId).select("status").lean();
+    if (task?.status === "cancelled") {
+      throw new TaskCancelledError(taskId);
+    }
+  },
+};
+
+backgroundTaskSchema.index({createdBy: 1, status: 1});
+backgroundTaskSchema.index({status: 1});
+backgroundTaskSchema.index({status: 1, taskType: 1});
+
+backgroundTaskSchema.plugin(createdUpdatedPlugin);
+backgroundTaskSchema.plugin(isDeletedPlugin);
+backgroundTaskSchema.plugin(findOneOrNone);
+backgroundTaskSchema.plugin(findExactlyOne);
+
+export const BackgroundTask = mongoose.model<BackgroundTaskDocument, BackgroundTaskModel>(
+  "BackgroundTask",
+  backgroundTaskSchema
+);

package/src/secretProviders.ts

@@ -0,0 +1,109 @@
+import type {SecretProvider} from "./configurationPlugin";
+import {logger} from "./logger";
+
+/**
+ * Secret provider that reads secrets from environment variables.
+ * Useful for local development and testing.
+ *
+ * Maps secret names to environment variable names by converting to SCREAMING_SNAKE_CASE.
+ * e.g., "openai-api-key" → process.env.OPENAI_API_KEY
+ *
+ * @example
+ * ```typescript
+ * const provider = new EnvSecretProvider();
+ * // reads process.env.OPENAI_API_KEY
+ * const key = await provider.getSecret("openai-api-key");
+ * ```
+ */
+export class EnvSecretProvider implements SecretProvider {
+  name = "env";
+
+  async getSecret(secretName: string): Promise<string | null> {
+    // Convert secret name to env var format: "openai-api-key" → "OPENAI_API_KEY"
+    const envKey = secretName.replace(/[-.]/g, "_").toUpperCase();
+    const value = process.env[envKey] ?? null;
+    if (value === null) {
+      logger.debug(`EnvSecretProvider: no env var found for ${secretName} (tried ${envKey})`);
+    }
+    return value;
+  }
+}
+
+/**
+ * Options for GcpSecretProvider.
+ */
+export interface GcpSecretProviderOptions {
+  /** GCP project ID. Required for short secret names. */
+  projectId: string;
+}
+
+/**
+ * Secret provider that reads secrets from Google Cloud Secret Manager.
+ *
+ * Requires `@google-cloud/secret-manager` to be installed.
+ * Resolves short names like "openai-api-key" to the full resource path
+ * `projects/{projectId}/secrets/{secretName}/versions/latest`.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GcpSecretProvider({ projectId: "my-project" });
+ * const key = await provider.getSecret("openai-api-key");
+ * ```
+ */
+export class GcpSecretProvider implements SecretProvider {
+  name = "gcp";
+  private projectId: string;
+  private client: any = null;
+
+  constructor(options: GcpSecretProviderOptions) {
+    this.projectId = options.projectId;
+  }
+
+  private async getClient(): Promise<any> {
+    if (!this.client) {
+      try {
+        // Dynamic import — @google-cloud/secret-manager is an optional peer dependency
+        const moduleName = "@google-cloud/secret-manager";
+        const mod: any = await import(/* webpackIgnore: true */ moduleName);
+        const SecretManagerServiceClient =
+          mod.SecretManagerServiceClient ?? mod.default?.SecretManagerServiceClient;
+        this.client = new SecretManagerServiceClient();
+      } catch {
+        throw new Error(
+          "GcpSecretProvider requires @google-cloud/secret-manager. Install it with: bun add @google-cloud/secret-manager"
+        );
+      }
+    }
+    return this.client;
+  }
+
+  async getSecret(secretName: string): Promise<string | null> {
+    const client = await this.getClient();
+
+    let resourceName: string;
+    if (secretName.startsWith("projects/")) {
+      resourceName = secretName.endsWith("/versions/latest")
+        ? secretName
+        : `${secretName}/versions/latest`;
+    } else {
+      resourceName = `projects/${this.projectId}/secrets/${secretName}/versions/latest`;
+    }
+
+    try {
+      const [version] = await client.accessSecretVersion({name: resourceName});
+      const payload = version.payload?.data;
+      if (!payload) {
+        logger.warn(`GcpSecretProvider: secret ${secretName} has no payload`);
+        return null;
+      }
+      return typeof payload === "string" ? payload : new TextDecoder().decode(payload);
+    } catch (error: any) {
+      if (error?.code === 5) {
+        // NOT_FOUND
+        logger.warn(`GcpSecretProvider: secret ${secretName} not found`);
+        return null;
+      }
+      throw error;
+    }
+  }
+}

package/src/terrenoApp.ts

@@ -6,10 +6,12 @@ import qs from "qs";
 
 import type {ModelRouterRegistration} from "./api";
 import {addAuthRoutes, addMeRoutes, setupAuth, type UserModel as UserMongooseModel} from "./auth";
+import {ConfigurationApp, type ConfigurationAppOptions} from "./configurationApp";
 import {apiErrorMiddleware, apiUnauthorizedMiddleware} from "./errors";
 import {type AuthOptions, logRequests} from "./expressServer";
 import {addGitHubAuthRoutes, type GitHubAuthOptions, setupGitHubAuth} from "./githubAuth";
 import {type LoggingOptions, logger, setupLogging} from "./logger";
+import {openApiCompatMiddleware, patchAppUse} from "./openApiCompat";
 import {openApiEtagMiddleware} from "./openApiEtag";
 import type {TerrenoPlugin} from "./terrenoPlugin";
 
@@ -114,6 +116,7 @@ export class TerrenoApp {
   private options: TerrenoAppOptions;
   private registrations: (ModelRouterRegistration | TerrenoPlugin)[] = [];
   private middlewareFns: (express.RequestHandler | ((app: express.Application) => void))[] = [];
+  private configurationApp: ConfigurationApp | null = null;
 
   /**
    * Create a new TerrenoApp builder.
@@ -171,6 +174,36 @@ export class TerrenoApp {
     return 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.
+   *
+   * @param model - Mongoose model with configurationPlugin applied
+   * @param options - Optional configuration (basePath, fieldOverrides)
+   * @returns This TerrenoApp instance for method chaining
+   *
+   * @example
+   * ```typescript
+   * const app = new TerrenoApp({ userModel: User })
+   *   .configure(AppConfig)
+   *   .register(todoRouter)
+   *   .start();
+   * ```
+   */
+  configure(
+    model: import("mongoose").Model<any>,
+    options?: Omit<ConfigurationAppOptions, "model">
+  ): this {
+    this.configurationApp = new ConfigurationApp({model, ...options});
+    return this;
+  }
+
   /**
    * Build the Express application without starting the server.
    *
@@ -200,6 +233,9 @@ export class TerrenoApp {
     const app = express();
     const options = this.options;
 
+    // Record mount paths on layers for Express 5 → OpenAPI compat
+    patchAppUse(app);
+
     app.set("query parser", (str: string) =>
       qs.parse(str, {arrayLimit: options.arrayLimit ?? 200})
     );
@@ -217,7 +253,7 @@ export class TerrenoApp {
       }
     }
 
-    app.use(express.json());
+    app.use(express.json({limit: "50mb"}));
 
     // Auth routes (login/signup/refresh_token) before JWT middleware
     addAuthRoutes(app, options.userModel as any, options.authOptions);
@@ -234,7 +270,7 @@ export class TerrenoApp {
     });
 
     // Sentry scopes
-    app.all("*", (req: any, _res: any, next: any) => {
+    app.use((req: any, _res: any, next: any) => {
       const transactionId = req.header("X-Transaction-ID");
       const sessionId = req.header("X-Session-ID");
       if (transactionId) {
@@ -250,6 +286,7 @@ export class TerrenoApp {
     });
 
     // OpenAPI
+    app.use(openApiCompatMiddleware);
     app.use(openApiEtagMiddleware);
     const oapi = openapi({
       info: {
@@ -273,6 +310,11 @@ export class TerrenoApp {
       addGitHubAuthRoutes(app, options.userModel as any, options.githubAuth, options.authOptions);
     }
 
+    // Mount configuration app if configured
+    if (this.configurationApp) {
+      this.configurationApp.register(app);
+    }
+
     // Mount registered model routers and plugins
     for (const registration of this.registrations) {
       if (this.isModelRouterRegistration(registration)) {

package/src/tests.ts

@@ -1,10 +1,12 @@
 import express, {type Express} from "express";
 import mongoose, {type Model, model, Schema} from "mongoose";
 import passportLocalMongoose from "passport-local-mongoose";
+import qs from "qs";
 import supertest from "supertest";
 import type TestAgent from "supertest/lib/agent";
 
 import {logger} from "./logger";
+import {patchAppUse} from "./openApiCompat";
 import {createdUpdatedPlugin, DateOnly, isDisabledPlugin} from "./plugins";
 
 export interface User {
@@ -162,8 +164,17 @@ export const RequiredModel = model<RequiredField>("Required", requiredSchema);
 
 export function getBaseServer(): Express {
   const app = express();
+  app.set("query parser", (str: string) => qs.parse(str, {arrayLimit: 200}));
 
-  app.all("/*", (req, res, next) => {
+  // Express 5 defaults to 'simple' query parser (Node querystring) which doesn't
+  // support nested bracket notation like name[$regex]=Green. Use qs to match
+  // what setupServer() configures.
+  app.set("query parser", (str: string) => qs.parse(str, {arrayLimit: 200}));
+
+  // Record mount paths on layers for Express 5 → OpenAPI compat
+  patchAppUse(app);
+
+  app.use((req, res, next) => {
     res.header("Access-Control-Allow-Origin", "*");
     res.header("Access-Control-Allow-Headers", "*");
     // intercepts OPTIONS method