@terreno/api 0.3.1 → 0.4.0

package/dist/openApiCompat.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Patches the Express router stack to add `.regexp` on layers for
+ * compatibility with @wesleytodd/openapi, which expects Express 4-style
+ * layers with `.regexp.fast_slash`.
+ *
+ * In Express 5 (router@2.x), layers use `.slash` (boolean) and `.matchers`
+ * (array of functions) instead of `.regexp`.
+ *
+ * @see https://github.com/wesleytodd/express-openapi/issues/70
+ */
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openApiCompatMiddleware = exports.patchAppUse = void 0;
+var MOUNT_PATH_KEY = "__openApiMountPath";
+/**
+ * Extract Express 4-style keys from a path string.
+ * Parses `:paramName` and `*paramName` segments into `{name, optional}` objects
+ * that @wesleytodd/openapi expects.
+ */
+var extractKeysFromPath = function (path) {
+    var keys = [];
+    var paramRegex = /[:*](\w+)\??/g;
+    var match;
+    // biome-ignore lint/suspicious/noAssignInExpressions: standard regex exec loop
+    while ((match = paramRegex.exec(path)) !== null) {
+        keys.push({ name: match[1], optional: match[0].endsWith("?") });
+    }
+    return keys;
+};
+/**
+ * Build an Express 4-style regexp from a path string for the openapi parser.
+ *
+ * For paths without params (e.g., `/food`), produces a simple escaped regexp
+ * that the `split()` function in @wesleytodd/openapi can parse directly.
+ *
+ * For paths with `:params` (e.g., `/food/:id`), replaces each param with the
+ * Express 4-style capture group `(?:([^\/]+?))` so that `processComplexMatch()`
+ * in the openapi library can map them to `{paramName}` using `layer.keys`.
+ */
+var buildRegexpForPath = function (pathStr, isMount) {
+    // Replace :param segments with Express 4-style capture groups, then escape the rest
+    var parts = pathStr.split("/").map(function (segment) {
+        if (segment.startsWith(":")) {
+            return "(?:([^\\/]+?))";
+        }
+        return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    });
+    var pattern = parts.join("\\/");
+    if (isMount) {
+        return new RegExp("^".concat(pattern, "\\/?(?=\\/|$)"));
+    }
+    return new RegExp("^".concat(pattern, "\\/?$"));
+};
+var patchRouterStack = function (stack) {
+    var e_1, _a;
+    var _b, _c, _d, _e;
+    try {
+        for (var stack_1 = __values(stack), stack_1_1 = stack_1.next(); !stack_1_1.done; stack_1_1 = stack_1.next()) {
+            var layer = stack_1_1.value;
+            if (layer.regexp !== undefined) {
+                continue;
+            }
+            // Determine the path string for this layer
+            var pathStr = void 0;
+            var isMount = layer.name === "router" || !!((_b = layer.handle) === null || _b === void 0 ? void 0 : _b.stack);
+            if (layer.slash) {
+                // Express 5 layers use .slash instead of .regexp.fast_slash
+                layer.regexp = { fast_slash: true };
+            }
+            else if (layer[MOUNT_PATH_KEY]) {
+                pathStr = layer[MOUNT_PATH_KEY];
+                layer.regexp = buildRegexpForPath(pathStr, isMount);
+            }
+            else if (layer.path && typeof layer.path === "string") {
+                pathStr = layer.path;
+                layer.regexp = buildRegexpForPath(pathStr, false);
+            }
+            else if (((_c = layer.route) === null || _c === void 0 ? void 0 : _c.path) && typeof layer.route.path === "string") {
+                pathStr = layer.route.path;
+                layer.regexp = buildRegexpForPath(pathStr, false);
+            }
+            else {
+                layer.regexp = /^\/?$/;
+            }
+            // Populate keys in Express 4 format: [{name, optional}]
+            // @wesleytodd/openapi reads layer.keys[i].name for path parameters
+            if (!layer.keys || (Array.isArray(layer.keys) && layer.keys.length === 0)) {
+                if (pathStr) {
+                    layer.keys = extractKeysFromPath(pathStr);
+                }
+                else {
+                    layer.keys = [];
+                }
+            }
+            else if (Array.isArray(layer.keys) && typeof layer.keys[0] === "string") {
+                // Express 5 stores keys as plain strings after match() — convert to objects
+                layer.keys = layer.keys.map(function (k) { return ({ name: k, optional: false }); });
+            }
+            // Recursively patch nested stacks
+            if ((_d = layer.handle) === null || _d === void 0 ? void 0 : _d.stack) {
+                patchRouterStack(layer.handle.stack);
+            }
+            if ((_e = layer.route) === null || _e === void 0 ? void 0 : _e.stack) {
+                patchRouterStack(layer.route.stack);
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (stack_1_1 && !stack_1_1.done && (_a = stack_1.return)) _a.call(stack_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+};
+/**
+ * Wraps an Express app's `use` method to record the mount path on each
+ * layer added to the router stack. This runs at setup time so that
+ * `patchRouterStack` can read the original path later.
+ *
+ * Must be called before any routes are registered.
+ */
+var patchAppUse = function (app) {
+    var originalUse = app.use.bind(app);
+    app.use = function patchedUse() {
+        var _a, _b;
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        // Track stack length before the call
+        var router = app._router || app.router;
+        var stackBefore = (_b = (_a = router === null || router === void 0 ? void 0 : router.stack) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0;
+        var result = originalUse.apply(void 0, __spreadArray([], __read(args), false));
+        // After use(), check if new layers were added and annotate them
+        var routerAfter = app._router || app.router;
+        if (routerAfter === null || routerAfter === void 0 ? void 0 : routerAfter.stack) {
+            var stackAfter = routerAfter.stack.length;
+            // The first arg is the mount path if it's a string
+            var mountPath = typeof args[0] === "string" ? args[0] : undefined;
+            if (mountPath && mountPath !== "/") {
+                for (var i = stackBefore; i < stackAfter; i++) {
+                    routerAfter.stack[i][MOUNT_PATH_KEY] = mountPath.replace(/\/+$/, "");
+                }
+            }
+        }
+        return result;
+    };
+};
+exports.patchAppUse = patchAppUse;
+/**
+ * Express middleware that patches the router stack before OpenAPI doc
+ * generation. Must be mounted before the openapi middleware.
+ */
+var openApiCompatMiddleware = function (req, _res, next) {
+    var router = req.app._router || req.app.router;
+    if (router === null || router === void 0 ? void 0 : router.stack) {
+        patchRouterStack(router.stack);
+    }
+    next();
+};
+exports.openApiCompatMiddleware = openApiCompatMiddleware;

package/dist/scriptRunner.d.ts

@@ -0,0 +1,52 @@
+import mongoose, { type Document, type Model } from "mongoose";
+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 declare class TaskCancelledError extends Error {
+    constructor(taskId: string);
+}
+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;
+export declare const BackgroundTask: BackgroundTaskModel;
+export {};

package/dist/scriptRunner.js

@@ -0,0 +1,231 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackgroundTask = exports.TaskCancelledError = void 0;
+var luxon_1 = require("luxon");
+var mongoose_1 = __importStar(require("mongoose"));
+var plugins_1 = require("./plugins");
+var TaskCancelledError = /** @class */ (function (_super) {
+    __extends(TaskCancelledError, _super);
+    function TaskCancelledError(taskId) {
+        var _this = _super.call(this, "Task ".concat(taskId, " was cancelled")) || this;
+        _this.name = "TaskCancelledError";
+        return _this;
+    }
+    return TaskCancelledError;
+}(Error));
+exports.TaskCancelledError = TaskCancelledError;
+var progressSchema = new mongoose_1.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 });
+var logSchema = new mongoose_1.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 });
+var backgroundTaskSchema = new mongoose_1.Schema({
+    completedAt: {
+        description: "When the task completed (success or failure)",
+        type: Date,
+    },
+    createdBy: {
+        description: "The user who created this task",
+        ref: "User",
+        type: mongoose_1.default.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 = {
+    addLog: function (level, message) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!this.logs) {
+                            this.logs = [];
+                        }
+                        this.logs.push({
+                            level: level,
+                            message: message,
+                            timestamp: luxon_1.DateTime.now().toJSDate(),
+                        });
+                        return [4 /*yield*/, this.save()];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    },
+    updateProgress: function (percentage, stage, message) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        this.progress = {
+                            message: message !== null && message !== void 0 ? message : (_a = this.progress) === null || _a === void 0 ? void 0 : _a.message,
+                            percentage: percentage,
+                            stage: stage !== null && stage !== void 0 ? stage : (_b = this.progress) === null || _b === void 0 ? void 0 : _b.stage,
+                        };
+                        return [4 /*yield*/, this.save()];
+                    case 1:
+                        _c.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    },
+};
+backgroundTaskSchema.statics = {
+    checkCancellation: function (taskId) {
+        return __awaiter(this, void 0, void 0, function () {
+            var task;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.findById(taskId).select("status").lean()];
+                    case 1:
+                        task = _a.sent();
+                        if ((task === null || task === void 0 ? void 0 : task.status) === "cancelled") {
+                            throw new TaskCancelledError(taskId);
+                        }
+                        return [2 /*return*/];
+                }
+            });
+        });
+    },
+};
+backgroundTaskSchema.index({ createdBy: 1, status: 1 });
+backgroundTaskSchema.index({ status: 1 });
+backgroundTaskSchema.index({ status: 1, taskType: 1 });
+backgroundTaskSchema.plugin(plugins_1.createdUpdatedPlugin);
+backgroundTaskSchema.plugin(plugins_1.isDeletedPlugin);
+backgroundTaskSchema.plugin(plugins_1.findOneOrNone);
+backgroundTaskSchema.plugin(plugins_1.findExactlyOne);
+exports.BackgroundTask = mongoose_1.default.model("BackgroundTask", backgroundTaskSchema);

package/dist/secretProviders.d.ts

@@ -0,0 +1,47 @@
+import type { SecretProvider } from "./configurationPlugin";
+/**
+ * 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 declare class EnvSecretProvider implements SecretProvider {
+    name: string;
+    getSecret(secretName: string): Promise<string | null>;
+}
+/**
+ * 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 declare class GcpSecretProvider implements SecretProvider {
+    name: string;
+    private projectId;
+    private client;
+    constructor(options: GcpSecretProviderOptions);
+    private getClient;
+    getSecret(secretName: string): Promise<string | null>;
+}