@tulipes/cli 0.1.0 → 0.2.0-rc.1

package/templates/app/modules/core/helpers/cache/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Storage-agnostic cache contract. Implementations serialize values
+ * themselves; callers work with plain objects. Keep it small — add methods
+ * only when a real use case needs them.
+ */
+export interface Cache {
+  /** Returns the cached value, or `null` if absent/expired. */
+  get<T>(key: string): Promise<T | null>;
+  /** Stores a value, optionally expiring after `ttlSeconds`. */
+  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+  /** Removes a key (no-op if absent). */
+  del(key: string): Promise<void>;
+  /**
+   * Returns the cached value, or computes it with `producer`, caches it for
+   * `ttlSeconds`, and returns it (read-through).
+   */
+  wrap<T>(key: string, ttlSeconds: number, producer: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Shared read-through logic so drivers only implement storage. A driver that
+ * can do it atomically (e.g. redis with locks) is free to override.
+ */
+export abstract class BaseCache implements Cache {
+  abstract get<T>(key: string): Promise<T | null>;
+  abstract set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+  abstract del(key: string): Promise<void>;
+
+  async wrap<T>(key: string, ttlSeconds: number, producer: () => Promise<T>): Promise<T> {
+    const cached = await this.get<T>(key);
+    if (cached !== null) return cached;
+
+    const fresh = await producer();
+    await this.set(key, fresh, ttlSeconds);
+    return fresh;
+  }
+}

package/templates/app/modules/core/helpers/lazy.ts

@@ -0,0 +1,13 @@
+import type { RequestHandler } from "express";
+
+/**
+ * Middleware built on its first request rather than while the routes
+ * file runs. Inspection (`tulipes routes`, `tulipes spec`) builds every
+ * router without resolving the environment or acquiring a service, so a
+ * middleware that reads a variable or opens a client is built here, once,
+ * when a real request arrives.
+ */
+export function lazy(build: () => RequestHandler): RequestHandler {
+  let handler: RequestHandler | undefined;
+  return (req, res, next) => (handler ??= build())(req, res, next);
+}

package/templates/app/modules/core/helpers/logger/index.ts

@@ -0,0 +1,115 @@
+import { join } from "node:path";
+// Default import, not the named one: pino.transport lives on the
+// namespace that only the default export carries.
+import pino from "pino";
+import type { Logger, TransportTargetOptions } from "pino";
+import type { ProcessMode } from "@tulipes/core/boot";
+import type { Environment } from "@tulipes/core/env";
+
+/**
+ * The app's logger, shared by every module.
+ *
+ * Two destinations at once, because they answer different questions:
+ *
+ *   console  pretty and coloured, for a human watching a terminal
+ *   files    JSON lines, for grep/jq/Loki/CloudWatch — one object per
+ *            line with a stable shape, which is what makes logs queryable
+ *
+ * Files are named per process mode. Backend and worker run at the same
+ * time, and two processes rotating one file race: both notice the size
+ * limit, both rename, and one of them loses entries. Separate files cost
+ * nothing and remove the failure entirely.
+ */
+let instance: Logger | undefined;
+
+/**
+ * How the files are named and rotated. These never needed to differ per
+ * deployment, so they are constants rather than environment variables;
+ * the settings module's log stream reads the same names.
+ */
+export const LOG_FILES = Object.freeze({
+  /** Base name of the all-levels file; the process mode and date are appended. */
+  basename: "app",
+  /** Base name of the errors-only file. */
+  errorBasename: "error",
+  /** Rotate on this schedule: "daily", "hourly", or milliseconds. */
+  rotationFrequency: "daily",
+  /** Also rotate once a file reaches this size. */
+  rotationSize: "20m",
+  /** How many rotated files to keep per destination, besides the current one. */
+  retentionFiles: 14,
+});
+
+export function logger(environment: Environment, mode: ProcessMode = "backend"): Logger {
+  if (instance) return instance;
+
+  const level = String(environment.get("LOG_LEVEL"));
+  const targets: TransportTargetOptions[] = [];
+
+  if (Boolean(environment.get("LOG_CONSOLE"))) {
+    targets.push({
+      target: "pino-pretty",
+      level,
+      options: {
+        colorize: true,
+        translateTime: "SYS:HH:MM:ss.l",
+        // pid and hostname matter in aggregated files, not on the terminal
+        // of the machine that is obviously running it.
+        ignore: "pid,hostname",
+        messageFormat: "{if module}[{module}] {end}{msg}",
+      },
+    });
+  }
+
+  if (Boolean(environment.get("LOG_FILE"))) {
+    const dir = String(environment.get("LOG_DIR"));
+    const rotation = {
+      // Both limits apply: whichever trips first rotates the file.
+      frequency: LOG_FILES.rotationFrequency,
+      size: LOG_FILES.rotationSize,
+      limit: { count: LOG_FILES.retentionFiles },
+      extension: ".log",
+      dateFormat: "yyyy-MM-dd",
+      mkdir: true,
+    };
+
+    targets.push({
+      target: "pino-roll",
+      level,
+      options: { ...rotation, file: join(dir, `${LOG_FILES.basename}-${mode}`) },
+    });
+
+    // A second copy of errors only. Everything here is also in the main
+    // file; the point is a small file to open first when something breaks,
+    // instead of paging through a day of request logs.
+    targets.push({
+      target: "pino-roll",
+      level: "error",
+      options: {
+        ...rotation,
+        file: join(dir, `${LOG_FILES.errorBasename}-${mode}`),
+      },
+    });
+  }
+
+  instance = targets.length
+    ? pino({ level, base: { mode } }, pino.transport({ targets }))
+    : // Every destination disabled: still return a working logger rather
+      // than null-checking at a hundred call sites.
+      pino({ level, base: { mode } });
+
+  return instance;
+}
+
+/**
+ * A logger tagged with the module it belongs to, so a line's origin is
+ * visible in both destinations: `[users] ready` on the console, and a
+ * queryable `"module":"users"` field in the file.
+ */
+export function moduleLogger(
+  environment: Environment,
+  name: string,
+  mode: ProcessMode = "backend",
+): Logger {
+  return logger(environment, mode).child({ module: name });
+}

package/templates/app/modules/core/helpers/mongoose/index.ts

@@ -0,0 +1,27 @@
+import type { SchemaOptions } from "mongoose";
+
+export { baseModelPlugin } from "./plugins/base.plugin.ts";
+export { softDeletePlugin } from "./plugins/soft-delete.plugin.ts";
+export { timestampsPlugin } from "./plugins/timestamps.plugin.ts";
+export { registerBasePlugins } from "./register.ts";
+export type {
+  Actor,
+  BaseDocument,
+  SoftDeleteFields,
+  SoftDeleteMethods,
+  Timestamps,
+} from "./plugins/types.ts";
+
+/**
+ * Serialization conventions every model spreads into its schema options.
+ * Timestamps are NOT set here — the base plugin owns them (snake_case).
+ */
+export const baseSchemaOptions: SchemaOptions = {
+  toJSON: {
+    versionKey: false,
+    transform: (_doc, ret: Record<string, unknown>) => {
+      delete ret._id;
+      return ret;
+    },
+  },
+};

package/templates/app/modules/core/helpers/mongoose/plugins/base.plugin.ts

@@ -0,0 +1,14 @@
+import type { Schema } from "mongoose";
+
+import { softDeletePlugin } from "./soft-delete.plugin.ts";
+import { timestampsPlugin } from "./timestamps.plugin.ts";
+
+/**
+ * The base plugin every model gets. Composes the focused plugins so each
+ * stays single-responsibility; new cross-cutting behaviour (audit trail,
+ * versioning, …) slots in here without touching call sites.
+ */
+export function baseModelPlugin(schema: Schema): void {
+  schema.plugin(timestampsPlugin);
+  schema.plugin(softDeletePlugin);
+}

package/templates/app/modules/core/helpers/mongoose/plugins/soft-delete.plugin.ts

@@ -0,0 +1,124 @@
+import {
+  Schema,
+  type Aggregate,
+  type HydratedDocument,
+  type Model,
+  type Query,
+} from "mongoose";
+
+import type { Actor, SoftDeleteFields } from "./types.ts";
+
+/** Option carried on a query/aggregation to opt out of the soft-delete filter. */
+interface SoftDeleteOptions {
+  withDeleted?: boolean;
+}
+
+const deletedPatch = (by?: Actor) => ({
+  is_deleted: true,
+  deleted_at: new Date(),
+  deleted_by: by ?? null,
+});
+
+const restoredPatch = () => ({
+  is_deleted: false,
+  deleted_at: null,
+  deleted_by: null,
+});
+
+/**
+ * Hides soft-deleted documents from reads and updates. Skipped when the
+ * caller opted out via `.withDeleted()` or already targeted `is_deleted`
+ * explicitly. Uses `$ne: true` (not `=== false`) so legacy documents
+ * missing the field are still treated as live.
+ */
+function excludeDeleted(this: Query<unknown, unknown>) {
+  const { withDeleted } = this.getOptions() as SoftDeleteOptions;
+  if (withDeleted) return;
+  if (this.getFilter().is_deleted !== undefined) return;
+  this.where({ is_deleted: { $ne: true } });
+}
+
+/** The aggregation-pipeline equivalent of {@link excludeDeleted}. */
+function excludeDeletedFromAggregate(this: Aggregate<unknown[]>) {
+  const { withDeleted } = (this.options ?? {}) as SoftDeleteOptions;
+  if (withDeleted) return;
+  this.pipeline().unshift({ $match: { is_deleted: { $ne: true } } });
+}
+
+/**
+ * The `deleted_by` actor as a nested sub-schema (no own `_id`) so the whole
+ * object can be `null` while the document is live. `refPath` makes `id` a
+ * polymorphic reference resolved against the model named in
+ * `deleted_by.model`.
+ */
+const deletedBySchema = new Schema<Actor>(
+  {
+    model: { type: String, required: true },
+    id: { type: Schema.Types.ObjectId, required: true, refPath: "deleted_by.model" },
+  },
+  { _id: false },
+);
+
+/**
+ * Soft deletion: an `is_deleted` flag plus `deleted_at` and a polymorphic
+ * `deleted_by` actor. Deleted documents are transparently excluded from
+ * queries unless explicitly included.
+ *
+ *   read incl. deleted:   Model.find().withDeleted()   (or setOptions)
+ *   read only deleted:    Model.find().onlyDeleted()
+ *   delete one:           await doc.softDelete(actor)
+ *   delete many:          await Model.softDelete(filter, actor)
+ *   restore:              await doc.restore() / await Model.restore(filter)
+ */
+export function softDeletePlugin(schema: Schema): void {
+  schema.add({
+    is_deleted: { type: Boolean, default: false, index: true },
+    deleted_at: { type: Date, default: null },
+    deleted_by: { type: deletedBySchema, default: null },
+  });
+
+  // Covers find*, count*, distinct, update*, replace*. Hard deletes
+  // (deleteOne/deleteMany) stay literal on purpose — when code says
+  // delete, the framework must not silently downgrade it.
+  schema.pre(/^(count|find|distinct|update|replace)/, excludeDeleted);
+  schema.pre("aggregate", excludeDeletedFromAggregate);
+
+  const query = schema.query as Record<string, (...args: never[]) => unknown>;
+  query.withDeleted = function (this: Query<unknown, unknown>) {
+    return this.setOptions({ withDeleted: true } as SoftDeleteOptions);
+  };
+  query.onlyDeleted = function (this: Query<unknown, unknown>) {
+    return this.setOptions({ withDeleted: true } as SoftDeleteOptions).where({
+      is_deleted: true,
+    });
+  };
+
+  schema.methods.softDelete = function (
+    this: HydratedDocument<SoftDeleteFields>,
+    by?: Actor,
+  ) {
+    this.set(deletedPatch(by));
+    return this.save();
+  };
+  schema.methods.restore = function (this: HydratedDocument<SoftDeleteFields>) {
+    this.set(restoredPatch());
+    return this.save();
+  };
+
+  schema.statics.softDelete = function (
+    this: Model<unknown>,
+    filter: Record<string, unknown>,
+    by?: Actor,
+  ) {
+    return this.updateMany(filter, { $set: deletedPatch(by) });
+  };
+  schema.statics.restore = function (
+    this: Model<unknown>,
+    filter: Record<string, unknown>,
+  ) {
+    // withDeleted so the guard doesn't filter out the very docs we restore.
+    return this.updateMany(filter, { $set: restoredPatch() }).setOptions({
+      withDeleted: true,
+    } as SoftDeleteOptions);
+  };
+}

package/templates/app/modules/core/helpers/mongoose/plugins/timestamps.plugin.ts

@@ -0,0 +1,13 @@
+import type { Schema } from "mongoose";
+
+/**
+ * Mongoose-managed `created_at` / `updated_at` (snake_case, matching the
+ * API's wire format). Mongoose populates them on create/update — no manual
+ * defaults or hooks needed.
+ */
+export function timestampsPlugin(schema: Schema): void {
+  schema.set("timestamps", {
+    createdAt: "created_at",
+    updatedAt: "updated_at",
+  });
+}

package/templates/app/modules/core/helpers/mongoose/plugins/types.ts

@@ -0,0 +1,45 @@
+import type { Document, ObjectId, Types } from "mongoose";
+
+/**
+ * Who performed a soft delete — a polymorphic reference. `model` is the
+ * actor's Mongoose model name (e.g. "User") and `id` its `_id`; together
+ * they let `.populate("deleted_by.id")` resolve the actor via `refPath`.
+ */
+export interface Actor {
+  model: string;
+  id: Types.ObjectId;
+}
+
+/** Timestamp fields added by `timestampsPlugin`. */
+export interface Timestamps {
+  created_at: Date;
+  updated_at: Date;
+}
+
+/** Fields added by `softDeletePlugin`. */
+export interface SoftDeleteFields {
+  is_deleted: boolean;
+  deleted_at: Date | null;
+  deleted_by: Actor | null;
+}
+
+/** Instance methods added by `softDeletePlugin`. */
+export interface SoftDeleteMethods {
+  /** Flag this document as deleted (optionally recording the actor) and save. */
+  softDelete(by?: Actor): Promise<this>;
+  /** Clear the soft-delete flags and save. */
+  restore(): Promise<this>;
+}
+
+/**
+ * Everything the base plugin contributes to a document. Model interfaces
+ * extend this to inherit the fields and methods, typed. The `_id` type
+ * defaults to `ObjectId` but can be overridden:
+ *
+ *   export interface IUser extends BaseDocument { name: string }
+ *   export interface IApiKey extends BaseDocument<string> { name: string }
+ */
+export type BaseDocument<T = ObjectId> = Document<T> &
+  Timestamps &
+  SoftDeleteFields &
+  SoftDeleteMethods;

package/templates/app/modules/core/helpers/mongoose/register.ts

@@ -0,0 +1,20 @@
+import mongoose from "mongoose";
+
+import { baseModelPlugin } from "./plugins/base.plugin.ts";
+
+let registered = false;
+
+/**
+ * Registers the base plugin globally so EVERY schema gets timestamps + soft
+ * delete. Global plugins only affect models compiled after registration, so
+ * call this before boot() — it's the first line of app.ts and worker.ts.
+ *
+ * An explicit function, deliberately not an import side effect: the old
+ * framework's side-effect register module made correctness depend on import
+ * order, which is exactly the class of bug this framework exists to kill.
+ */
+export function registerBasePlugins(): void {
+  if (registered) return;
+  registered = true;
+  mongoose.plugin(baseModelPlugin);
+}

package/templates/app/modules/core/lib/index.ts

@@ -0,0 +1,34 @@
+/**
+ * What the core module offers the rest of the app.
+ *
+ * Other modules import these by package name — `@app/core` — never by a
+ * relative path climbing out of their own folder. That is what keeps the
+ * dependency visible: a module that uses this has to declare @app/core,
+ * so the coupling shows up in its package.json instead of hiding in an
+ * import string.
+ */
+export {
+  appCache,
+  closeCache,
+  BaseCache,
+  MemoryCache,
+  RedisCache,
+  type Cache,
+} from "../helpers/cache/index.ts";
+
+export { LOG_FILES, logger, moduleLogger } from "../helpers/logger/index.ts";
+
+export { lazy } from "../helpers/lazy.ts";
+
+export {
+  baseSchemaOptions,
+  baseModelPlugin,
+  softDeletePlugin,
+  timestampsPlugin,
+  registerBasePlugins,
+  type Actor,
+  type BaseDocument,
+  type SoftDeleteFields,
+  type SoftDeleteMethods,
+  type Timestamps,
+} from "../helpers/mongoose/index.ts";

package/templates/app/modules/core/module.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from "@tulipes/core/config";
+import { z } from "zod/v4";
+
+import { registerBasePlugins } from "./helpers/mongoose/index.ts";
+
+/**
+ * Declaration time (boot phase 4) is before models compile (phase 5), which
+ * is exactly when a global mongoose plugin has to exist: registering here
+ * makes the base plugins apply in EVERY mode — backend, worker and script
+ * alike — so a script can never read rows the API considers deleted.
+ */
+registerBasePlugins();
+
+/**
+ * The sys core module's own settings. The environment keeps only what boot
+ * needs before the store answers (the port, the connection strings, the log
+ * destinations) and the secrets; everything else is a setting like this one.
+ */
+export default defineConfig({
+  schema: z.object({
+    publicDomain: z.string().min(1).default("localhost")
+      .describe("Public hostname this API is served from; \"localhost\" means not deployed. The nginx deploy script and the generated API documents read it"),
+  }),
+});

package/templates/app/modules/core/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@app/core",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "tulipes": {
+    "tier": "sys",
+    "priority": 0,
+    "env": [
+      {
+        "name": "PORT",
+        "type": "number",
+        "group": "http",
+        "description": "HTTP port the backend process listens on",
+        "default": 3000
+      },
+      {
+        "name": "MONGO_URI",
+        "type": "url",
+        "group": "database",
+        "required": true,
+        "description": "MongoDB connection string"
+      },
+      {
+        "name": "REDIS_URL",
+        "type": "url",
+        "group": "redis",
+        "required": true,
+        "description": "Redis connection string (queues, cache)"
+      },
+      {
+        "name": "LOG_LEVEL",
+        "type": "enum",
+        "enum": [
+          "fatal",
+          "error",
+          "warn",
+          "info",
+          "debug",
+          "trace"
+        ],
+        "group": "logging",
+        "description": "Lowest level that reaches any destination",
+        "default": "info"
+      },
+      {
+        "name": "LOG_CONSOLE",
+        "type": "boolean",
+        "group": "logging",
+        "description": "Pretty coloured logs on stdout; turn off where a collector reads files only",
+        "default": true
+      },
+      {
+        "name": "LOG_FILE",
+        "type": "boolean",
+        "group": "logging",
+        "description": "Write JSON-line log files under LOG_DIR",
+        "default": true
+      },
+      {
+        "name": "LOG_DIR",
+        "type": "string",
+        "group": "logging",
+        "description": "Directory for log files, relative to the app root or absolute",
+        "default": "logs"
+      }
+    ]
+  },
+  "dependencies": {
+    "@tulipes/core": "workspace:*",
+    "ioredis": "^5",
+    "mongoose": "^8",
+    "pino": "^9",
+    "pino-pretty": "^13",
+    "pino-roll": "^3"
+  },
+  "exports": {
+    ".": "./lib/index.ts"
+  }
+}

package/templates/app/modules/core/routes/core.routes.ts

@@ -0,0 +1,24 @@
+import { randomUUID } from "node:crypto";
+import type { RequestHandler } from "express";
+import type { BackendCtx } from "@tulipes/core/boot";
+
+import { appCache } from "../helpers/cache/index.ts";
+import { lazy } from "../helpers/lazy.ts";
+
+/**
+ * The sys core module loads first, so what it mounts on `ctx.app` runs on
+ * every request of every later module: this is the global middleware slot.
+ */
+export default function coreRoutes({ app, Environment }: BackendCtx): void {
+  // The cache client opens on first use; built on the first request so
+  // inspection never touches Redis.
+  app.use(lazy(() => {
+    const cache = appCache(Environment);
+    return (async (_req, res, next) => {
+      res.setHeader("X-Request-Id", randomUUID());
+      const served = await cache.wrap("stats:served-sample", 10, async () => Date.now());
+      res.setHeader("X-Stats-Sample", String(served));
+      next();
+    }) satisfies RequestHandler;
+  }));
+}

package/templates/app/modules/core/tests/core.test.ts

@@ -0,0 +1,19 @@
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { z } from "zod/v4";
+import { afterAll, beforeAll, expect, test, vi } from "vitest";
+import { boot } from "@tulipes/core/boot";
+import { useTestApp } from "@tulipes/testing";
+
+import { testEnv, testSettings } from "../../../tests/support.ts";
+
+const rootDir = fileURLToPath(new URL("../../../", import.meta.url));
+const app = useTestApp({ rootDir, env: testEnv(), settings: testSettings() }, { beforeAll, afterAll });
+
+
+test("unknown endpoints return the error envelope", async () => {
+  const response = await fetch(app.base + "/not-a-route");
+
+  expect(response.status).toBe(404);
+  expect(await response.json()).toMatchObject({ success: false, data: null });
+});

package/templates/app/modules/hello/agent/hello.agent.ts

@@ -0,0 +1,33 @@
+import { action, defineAgent } from "@tulipes/core/agent";
+import { requireModels } from "@tulipes/core/boot";
+import { z } from "zod/v4";
+
+/**
+ * What an agent sees of this module. Every route is a tool already — its
+ * rai() gives the name, description, input schema and permission — so this
+ * file adds what cannot be derived: the summary, which routes to expose,
+ * and an action that is not an endpoint. A module without this file
+ * exposes every route; `pnpm tulipes agent manifest` prints the result.
+ */
+export default defineAgent({
+  summary: "Greets callers and counts how often each greeting is used.",
+  tools: [
+    { route: "hello:greet", description: "A greeting in the caller's language" },
+    { route: "hello:greet-name" },
+    { route: "hello:list-greetings", description: "The stored greetings, with how often each was used" },
+    { route: "hello:use-greeting" },
+
+    // An action: the id is a permission like any route's, granted to
+    // admin through hello:* in the auth module's ACL. The ACL decides,
+    // then the schema validates, then this runs.
+    action({
+      id: "hello:reset-counts",
+      description: "Reset the usage counter of every greeting to zero",
+      input: z.object({ confirm: z.literal(true).describe("Set to true to confirm the reset") }),
+      handler: async (ctx) => {
+        const { modifiedCount } = await requireModels(ctx).get("Greeting").updateMany({}, { times_used: 0 });
+        return { reset: modifiedCount };
+      },
+    }),
+  ],
+});

package/templates/app/modules/hello/bootstrap/seed-greetings.bootstrap.ts

@@ -0,0 +1,27 @@
+import type { DatabaseCtx } from "@tulipes/core/boot";
+
+/**
+ * Runs after settings, translations and ACL and before the server accepts
+ * traffic — the place for indexes, seed rows and defaults.
+ *
+ * MUST be idempotent: it runs on every boot of every process, backend and
+ * worker alike. Upsert; never blind-insert.
+ */
+export default async function seedGreetings({ models, mode }: DatabaseCtx): Promise<void> {
+  if (mode === "script") return; // a one-off script reads; it does not seed
+  const Greeting = models.get("Greeting");
+
+  try {
+    await Greeting.updateOne(
+      { name: "world" },
+      { $setOnInsert: { name: "world", message: "Hello, world!" } },
+      { upsert: true },
+    );
+  } catch (error) {
+    // Bootstrap tasks run in EVERY process, and backend and worker
+    // start together — concurrent upserts on a unique index race by
+    // design, and the loser gets a duplicate-key error. The row
+    // exists either way, which is all this task wanted.
+    if ((error as { code?: number }).code !== 11000) throw error;
+  }
+}