@tulipes/cli 0.1.1 → 0.2.0-rc.2

package/templates/claude/skills/tulipes-settings/SKILL.md

@@ -1,111 +1,60 @@
 ---
 name: tulipes-settings
-description: Use when working with the settings module — the sysadmin console that describes every module, edits environment variables and translations, restarts the app, or streams logs. Covers the sysadmin role, where a written variable actually lands, and why some writes cannot take effect.
+description: Use when streaming an app's logs, or when deciding whether a value is a setting or an environment variable and where it lives. Covers the settings module (the log stream), the two stores, and why the old console endpoints are gone.
 ---
 
-# The settings module
-
-An infrastructure console: what every module declares, what its variables
-resolve to and from where, its translations, and a live view of the logs.
-
-Everything it reports comes from the **booted context** — `ctx.modules`,
-the variable store, the ACL, the RAI registry — so it cannot describe an
-app different from the one running.
-
-## Access is `sysadmin`, and that is a real boundary
-
-`settings:*` is granted only to `sysadmin`. This works because the auth
-module grants `admin` its namespaces **explicitly** rather than `*`:
-
-```ts
-acl.allow("admin",    "auth:*", "users:*", "hello:*");
-acl.allow("sysadmin", "auth:*", "users:*", "hello:*");   // + settings:* from settings
-```
-
-**A wildcard would reach `settings:*` like any other id**, and "sysadmin
-only" would be a label rather than a rule. When you add a feature module,
-add its namespace to *both* grants — a new module is invisible to admin
-otherwise.
-
-A fresh app seeds an `admin`, so the console is inert until someone is
-deliberately promoted to `sysadmin`.
-
-## Endpoints
+# Settings and the settings module
+
+Two layers of configuration. **Environment** is what the process needs
+before the settings store can answer — the port, the connection strings,
+the log destinations — plus secrets: declared under `tulipes.env` in a
+module's `package.json`, read with `ctx.Environment.get()`, resolved once
+at boot. **Settings** are everything else: declared with a zod schema in
+`module.config.ts`, stored per module, validated on every write,
+hot-applied, read live at `ctx.config.<module>`. The test is mechanical:
+if boot does not need it before the database answers and it is not a
+secret, it is a setting. → skills `tulipes-env-variable`, `tulipes-config`
+
+## Where settings live
+
+The app's root `package.json` selects the store. With
+`"providers": { "settings": "@tulipes/mongoose/settings" }` (the production
+preset) every namespace is one document in the `settings` collection —
+`{ _id: "<module>", values, version, updated_at, updated_by }` — a write is
+refused when its version is stale, the replaced document goes to
+`settings_history`, and other processes pick the change up through a change
+stream on a replica set or by polling otherwise. Without the declaration
+(the minimal preset) the store is `config/settings.<APP_ENV>.json`, watched
+for edits. Neither store validates: the module's schema does, in every
+process, before a value is applied — an invalid document is logged and
+ignored, never applied. `pnpm tulipes config:check` prints what the store
+holds; the `config` module serves and edits it over HTTP.
+
+## The settings module: the log stream
+
+What is left of the old console is the one thing it did that the store
+cannot: a live view of the logs.
 
 | | |
 |---|---|
-| `GET /settings/modules` | every module: manifest, variables with full spec + resolved source, config, i18n, routes |
-| `GET /settings/variables/:name` | one variable; `?reveal=true` returns a secret's value, audited |
-| `PUT /settings/variables/:name` | set a value — validated against the variable's own spec |
-| `GET`/`PUT /settings/i18n/:module/:locale` | read or replace a module's translations |
-| `POST /settings/reboot` | restart via PM2 so written values take effect |
 | `GET /settings/logs/stream` | SSE; `?process=backend\|worker&level=warn&tail=200` |
 
-## Where a written variable actually lands
-
-**Always `.envs/.env.<APP_ENV>` — never `meta.variables.json`.** That file
-is the module's committed contract: rewriting a default there would change
-it for every environment and be lost on the next deploy. The env file is
-what exists to hold per-deployment values.
-
-The file is edited **surgically** — one line replaced, comments and
-ordering untouched — because these files are half explanation and a
-`stringify(parse(file))` round trip would erase all of it.
-
-### The case that catches people
-
-Precedence is `process.env` → env file → default. A variable injected by
-the **container** outranks both, so writing the file changes nothing, and
-a restart re-reads the same container environment and it wins again.
-
-When that happens the write still lands in the file *and* sets
-`process.env` live, and the response says so:
+It is `sysadmin`-only (`settings:*` is granted to that role alone, and the
+auth module never grants `admin` the `*` wildcard, which is what makes the
+boundary real). A stream outlives the request that opened it, so the
+authority behind it is re-checked while it is open — against the database,
+never the auth cache — and the stream ends on logout, password change,
+session end, role change or deletion, on `ctx.signal` at shutdown, and
+after a bounded duration and byte count. It reads the files the sys core
+module's logger writes (`LOG_DIR`, names from `LOG_FILES` in `@app/core`)
+and refuses when `LOG_FILE` is off.
 
-```jsonc
-{ "meta": { "action": "restart_required_shadowed" } }
-```
+## What is gone, and where it went
 
-That makes the change real for **this process only**. Other replicas keep
-the old value until the container's environment itself is changed.
-
-## Nothing takes effect until a restart
-
-Variables resolve once at boot, and `config.<module>` is derived from them
-by factories that also run once. A write persists; it does not move the
-running app. Every write response carries `requires_reboot: true`.
-
-`POST /settings/reboot` restarts through PM2, ordering the process serving
-the request **last** so the caller still gets its response. Under `yarn
-dev` there is no PM2, and it answers `503 NOT_SUPERVISED` rather than
-exiting a process nothing would restart.
-
-## Logs are read from files, not hooked in-process
-
-The stream tails `LOG_DIR`, which is what lets it show the **worker** —
-backend and worker are separate processes writing separate files, and an
-in-process stream could only ever show its own. The tailer is
-rotation-aware: pino-roll renames and starts a new file, and a naive watch
-on one path goes silent the moment it rolls.
-
-`LOG_FILE=false` means there are no files; the endpoint says so rather
-than streaming nothing.
-
-## Audit
-
-Every reveal, write and reboot logs at `warn` with actor, role, IP and
-old→new. **A secret's value is never recorded in either direction** — an
-audit entry that reconstructs a rotated key defeats rotating it; those
-entries carry `redacted: true` and no values.
-
-`?level=warn` on the log stream shows the audit trail and nothing else.
-
-## Rules
-
-- Never add a `settings:*` grant to another role. If someone needs part of
-  it, give them `sysadmin`, or split the ids.
-- Never widen a write to `meta.variables.json`. It is a contract, not
-  storage.
-- A new feature module needs its namespace in **both** the `admin` and
-  `sysadmin` grants.
-- Treat a `restart_required_shadowed` response as a warning to fix the
-  deployment's environment, not as a successful change.
+| 0.10 endpoint | 0.11 |
+|---|---|
+| `GET /settings/modules` | `GET /config` — the `config` module |
+| `GET`/`PUT /settings/variables/:name` | gone: no editable secrets; variables are read-only in `GET /config` |
+| `POST /settings/reboot` | gone: nothing needs a restart to take effect; a restart-tagged field says so in the write's response |
+| `GET`/`PUT /settings/i18n/:module/:locale` | gone: translations are code, edited in the repository |
+| the `.env` file editor, PM2 control, the audit of those | gone with them; the console's writes are audited by the `config` module |

package/templates/claude/skills/tulipes-spec/SKILL.md

@@ -18,7 +18,7 @@ router.post("/users", rai({
   name: "Create a user",
   body: z.object({ email: z.email("emailInvalid") }),
   returns: z.object({ id: z.string(), email: z.string() }),
-}), users(value => value.create())); // users is a runtime() binder
+}), users.create());
 
 ```
 
@@ -30,8 +30,8 @@ response.
 understands v4 schemas. The classic `from "zod"` import still validates but
 produces no shape in the document, and `tulipes spec` will say so.
 
-Keep schemas in `modules/<name>/schemas.ts` when a route file starts to
-sprawl; both the example's users and auth modules do.
+Keep schemas in `modules/<name>/schemas/<name>.schemas.ts` when a route file
+starts to sprawl; the example's users, auth and config modules do.
 
 ## What validation gives you
 
@@ -70,17 +70,15 @@ rai({ id: "auth:sessions", name: "List sessions", folder: "sessions" })
 ## Generating
 
 ```sh
-yarn spec     # tulipes spec --offline --openapi docs/openapi.json --postman docs/collection.json
+pnpm spec     # tulipes spec --openapi docs/openapi.json --postman docs/collection.json
 ```
 
-Offline generation builds native router factories wrapped in defineRoutes().
-Every module opts in with tulipes.offline: true; no extra declaration file is
-required. Keep schema imports pure and acquire services/controllers through
-runtime(). Use --runtime for factories requiring live configuration.
---url sets the advertised base URL. Offline defaults to http://localhost:3000
-and package.json title/version; runtime uses PORT/PUBLIC_DOMAIN and config.app.
-Install custom access checkers inside defineRoutes using routes.setAccessChecker;
-offline tooling sees the checker and makes no static role/public-access claim.
+Generation is an inspection boot: every routes file runs with nothing
+acquired, so no service, secret or `.env` is needed, and a routes file that
+touches infrastructure while building fails with its path. `--url` sets the
+advertised base URL (default `http://localhost:3000`). A custom access
+checker installed with `routes.setAccessChecker` is reported as dynamic: the
+document makes no static role or public-access claim for it.
 
 The generator lives in `@tulipes/spec`, a dev dependency. Core does not
 depend on it, so an app that never generates a spec never installs it.

package/templates/minimal/README.md

@@ -0,0 +1,21 @@
+# tulipes-example
+
+Minimal Tulipes API. Requires Node 24.x and pnpm; no MongoDB, Redis or credentials.
+
+```sh
+pnpm install
+pnpm sync
+pnpm typecheck
+pnpm check
+pnpm test
+pnpm spec
+pnpm dev
+```
+
+Open http://localhost:3000/api/v1/hello or http://localhost:3000/health.
+
+Routes declare a RAI and use res.respond. Middleware belongs to sys modules.
+Core still installs optional infrastructure libraries, but this app opens no infrastructure connections.
+The production preset adds auth, users, settings, queues and deployment examples:
+
+`tulipes init another-api --preset production`

package/templates/minimal/app.ts

@@ -0,0 +1,3 @@
+import { boot } from "@tulipes/core/boot";
+
+await boot({ rootDir: import.meta.dirname, mode: "backend" });

package/templates/minimal/config/app.config.ts

@@ -0,0 +1,16 @@
+import type { AppConfigFn } from "@tulipes/core/boot";
+
+/**
+ * App-wide values that belong to no module. `api.prefix` is where a router
+ * a routes file returns is mounted; `app.name` titles the startup banner.
+ */
+const appConfig = (() => ({
+  app: { name: "tulipes-example" },
+  api: { prefix: "/api/v1" },
+})) satisfies AppConfigFn;
+
+export default appConfig;
+
+declare module "@tulipes/core/config" {
+  interface GlobalConfig extends Partial<ReturnType<typeof appConfig>> {}
+}

package/templates/minimal/modules/agent/module.acl.ts

@@ -0,0 +1,3 @@
+import type { AclBuilder } from "@tulipes/core/acl";
+// Open to every caller: the manifest shows only what the role may call.
+export default function permissions(acl: AclBuilder) { acl.allow("guest", "agent:*"); }

package/templates/minimal/modules/agent/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@tulipes-example/agent",
+  "private": true,
+  "type": "module",
+  "version": "0.0.0",
+  "tulipes": {
+    "priority": 900
+  },
+  "dependencies": {
+    "@tulipes/core": "workspace:*",
+    "express": "^5",
+    "zod": "^3.25"
+  }
+}

package/templates/minimal/modules/agent/routes/agent.routes.ts

@@ -0,0 +1,20 @@
+import { Router } from "express";
+import { z } from "zod/v4";
+import type { BackendCtx } from "@tulipes/core/boot";
+import { roleOf } from "@tulipes/core/http";
+
+/** The agent door: the manifest a role may call, and the action endpoint. */
+export default function agentRoutes(ctx: BackendCtx): Router {
+  const { rai } = ctx;
+  const router = Router();
+  router.get("/agent/tools", rai({ id: "agent:tools", name: "Tools an agent may call", agent: false }), (req, res) => {
+    res.respond({ data: ctx.agent.manifest(roleOf(req)) });
+  });
+  router.post("/agent/tools/:name", rai({
+    id: "agent:invoke", name: "Run a declared action", agent: false,
+    params: z.object({ name: z.string() }), body: z.looseObject({}),
+  }), async (req, res) => {
+    res.respond({ data: await ctx.agent.invoke(String(req.params.name), req.body, { ...req.auth, role: roleOf(req) }, req) });
+  });
+  return router;
+}

package/templates/minimal/modules/core/module.acl.ts

@@ -0,0 +1,4 @@
+import type { AclBuilder } from "@tulipes/core/acl";
+export default function permissions(acl: AclBuilder) {
+  acl.defineRole("guest").allow("guest", "core:health");
+}

package/templates/minimal/modules/core/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@tulipes-example/core",
+  "private": true,
+  "type": "module",
+  "version": "0.0.0",
+  "tulipes": {
+    "tier": "sys",
+    "priority": 0,
+    "env": [
+      {
+        "name": "PORT",
+        "type": "number",
+        "default": 3000,
+        "description": "HTTP listener port"
+      }
+    ]
+  },
+  "dependencies": {
+    "@tulipes/core": "workspace:*"
+  }
+}

package/templates/minimal/modules/hello/i18n/en.json

@@ -0,0 +1,3 @@
+{
+  "greeting": "Hello"
+}

package/templates/minimal/modules/hello/module.acl.ts

@@ -0,0 +1,2 @@
+import type { AclBuilder } from "@tulipes/core/acl";
+export default function permissions(acl: AclBuilder) { acl.allow("guest", "hello:read"); }

package/templates/minimal/modules/hello/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@tulipes-example/hello",
+  "private": true,
+  "type": "module",
+  "version": "0.0.0",
+  "dependencies": {
+    "@tulipes/core": "workspace:*",
+    "express": "^5",
+    "zod": "^3.25"
+  }
+}

package/templates/minimal/modules/hello/routes/health.routes.ts

@@ -0,0 +1,9 @@
+import { Router } from "express";
+import type { BackendCtx } from "@tulipes/core/boot";
+export default function healthRoutes({ rai, routes }: BackendCtx): void {
+  const router = Router();
+  router.get("/health", rai({ id: "core:health", name: "Health" }), (_req, res) => {
+    res.respond({ data: { status: "ok" } });
+  });
+  routes.mount(router, "");
+}

package/templates/minimal/modules/hello/routes/hello.routes.ts

@@ -0,0 +1,10 @@
+import { Router } from "express";
+import { z } from "zod/v4";
+import type { BackendCtx } from "@tulipes/core/boot";
+export default function helloRoutes({ rai }: BackendCtx): Router {
+  const router = Router();
+  router.get("/hello", rai({ id: "hello:read", name: "Hello", returns: z.object({ message: z.string() }) }), (req, res) => {
+    res.respond({ data: { message: req.t("greeting") } });
+  });
+  return router;
+}

package/templates/minimal/modules/security/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@tulipes-example/security",
+  "private": true,
+  "type": "module",
+  "version": "0.0.0",
+  "tulipes": {
+    "tier": "sys",
+    "priority": 10
+  },
+  "dependencies": {
+    "@tulipes/core": "workspace:*",
+    "express": "^5",
+    "helmet": "^8"
+  }
+}

package/templates/minimal/modules/security/routes/security.routes.ts

@@ -0,0 +1,8 @@
+import express from "express";
+import helmet from "helmet";
+import type { BackendCtx } from "@tulipes/core/boot";
+export default function securityRoutes({ app }: BackendCtx): void {
+  app.disable("x-powered-by");
+  app.use(helmet());
+  app.use(express.json({ limit: "100kb" }));
+}

package/templates/minimal/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "tulipes-example",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@10.28.0",
+  "engines": {
+    "node": ">=24.0.0 <25"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "scripts": {
+    "dev": "tulipes dev",
+    "start": "node app.ts",
+    "sync": "tulipes sync",
+    "check": "tulipes env:check",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "spec": "tulipes spec --openapi docs/openapi.json --postman docs/collection.json"
+  },
+  "dependencies": {
+    "@tulipes/core": "workspace:*",
+    "express": "^5",
+    "zod": "^3.25"
+  },
+  "devDependencies": {
+    "@tulipes/cli": "workspace:*",
+    "@tulipes/spec": "workspace:*",
+    "@tulipes/testing": "workspace:*",
+    "@types/express": "^5",
+    "@types/node": "^24",
+    "typescript": "^7",
+    "vite": "^8.2.2",
+    "vitest": "^5.0.0"
+  }
+}

package/templates/minimal/tests/app.test.ts

@@ -0,0 +1,52 @@
+import { fileURLToPath } from "node:url";
+
+import { afterAll, beforeAll, expect, test } from "vitest";
+import { boot } from "@tulipes/core/boot";
+import { extract, toOpenApi, toPostman } from "@tulipes/spec";
+import { useTestApp } from "@tulipes/testing";
+
+/**
+ * Boots the app once for this file on a free port, with no services: the
+ * minimal preset declares none. Module tests live in modules/<name>/tests/
+ * and boot the same way.
+ */
+const rootDir = fileURLToPath(new URL("../", import.meta.url));
+const app = useTestApp({ rootDir }, { beforeAll, afterAll });
+
+test("hello responds through the declared public endpoint", async () => {
+  const response = await app.get<{ message: string }>(app.api("/hello"));
+
+  expect(response.status).toBe(200);
+  expect(response.body).toMatchObject({ success: true, errors: [] });
+  expect(response.data?.message).toBeTypeOf("string");
+});
+
+test("unknown endpoints return the error envelope", async () => {
+  const response = await app.get("/not-a-route");
+
+  expect(response.status).toBe(404);
+  expect(response.body).toMatchObject({ success: false, data: null });
+});
+
+test("an inspection boot describes the same routes and schemas as the running app", async () => {
+  const inspection = await boot({ rootDir, mode: "backend", inspect: true, handleSignals: false });
+
+  try {
+    const inspected = { ...extract(inspection.ctx), app: { name: "parity" } };
+    const runtime = { ...extract(app.ctx), app: { name: "parity" } };
+
+    expect(await toOpenApi(inspected)).toEqual(await toOpenApi(runtime));
+    expect(await toPostman(inspected)).toEqual(await toPostman(runtime));
+  } finally {
+    await inspection.shutdown();
+  }
+});
+
+test("health needs no external infrastructure", async () => {
+  expect(app.ctx.models).toBeUndefined();
+  expect(app.ctx.queues).toBeUndefined();
+
+  const response = await app.get<{ status: string }>("/health");
+
+  expect(response.data).toEqual({ status: "ok" });
+});

package/templates/minimal/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "erasableSyntaxOnly": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": [
+    "app.ts",
+    "modules",
+    "types",
+    "config",
+    "tests"
+  ]
+}

package/templates/minimal/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from "vitest/config";
+
+// Node strips types natively, so the app's own files import without a loader.
+// Every file boots the app once (@tulipes/testing), so files run one after another.
+export default defineConfig({ test: { include: ["tests/**/*.test.ts", "modules/*/tests/**/*.test.ts"], fileParallelism: false } });

package/templates/overlays/no-queues/ecosystem.config.cjs

@@ -0,0 +1,52 @@
+// PM2 definitions for both Tulipes processes in all three modes.
+//
+//   pnpm pm2:start              development
+//   pnpm pm2:start:staging      staging
+//   pnpm pm2:start:production   production
+//   pnpm pm2:stop | pm2:restart | pm2:delete | pm2:logs | pm2:status
+//
+// CommonJS on purpose: this app is an ESM package, and PM2 reads its
+// config with require().
+
+/**
+ * Each block repeats both variables rather than relying on PM2 merging
+ * env_<name> over env: a half-applied environment (right APP_ENV, wrong
+ * PROCESS_MODE) would start the wrong process against the wrong config,
+ * and the repetition is cheap insurance against that.
+ */
+const modes = (processMode) => ({
+  env: { APP_ENV: "development", PROCESS_MODE: processMode },
+  env_staging: { APP_ENV: "staging", PROCESS_MODE: processMode },
+  env_production: { APP_ENV: "production", PROCESS_MODE: processMode },
+});
+
+/** Shared by both apps. */
+const common = {
+  cwd: __dirname,
+  // Node 24 strips types natively, so PM2 runs the TypeScript entrypoints
+  // with node itself: no loader, no build step, nothing to point elsewhere.
+  interpreter: "node",
+  // Fork, not cluster: Socket.IO needs sticky sessions or the Redis
+  // adapter before a second instance is safe, and bootstrap tasks would
+  // run once per instance. Scale out only after wiring the adapter.
+  exec_mode: "fork",
+  instances: 1,
+  autorestart: true,
+  max_memory_restart: "512M",
+  // Graceful shutdown drains queues and closes mongo and redis. PM2's
+  // default 1.6s SIGKILL would cut that short and lose in-flight jobs.
+  kill_timeout: 10000,
+};
+
+module.exports = {
+  apps: [
+    {
+      ...common,
+      name: "tulipes-example",
+      script: "app.ts",
+      error_file: "logs/backend-error.log",
+      out_file: "logs/backend-out.log",
+      ...modes("backend"),
+    },
+  ],
+};

package/templates/overlays/no-queues/modules/hello/controllers/greetings.controllers.ts

@@ -0,0 +1,41 @@
+import type { Request, RequestHandler, Response } from "express";
+import { requireModels, type Ctx } from "@tulipes/core/boot";
+import { HttpError } from "@tulipes/core/http";
+
+export class GreetingsController {
+  readonly #ctx: Ctx;
+
+  constructor(ctx: Ctx) {
+    this.#ctx = ctx;
+  }
+
+  list(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      // ?page and ?per_page, already clamped by config.pagination — so
+      // every list endpoint in every module paginates the same way.
+      const { per_page, skip } = req.page;
+      const Greeting = requireModels(this.#ctx).get("Greeting");
+
+      const [greetings, total_items] = await Promise.all([
+        Greeting.find().select("name message times_used -_id")
+          .skip(skip).limit(per_page).lean(),
+        Greeting.countDocuments(),
+      ]);
+
+      // Passing total_items is what marks this a page: respond fills in
+      // page, per_page and total_pages from the request and the count.
+      res.respond({ data: greetings, meta: { total_items } });
+    };
+  }
+
+  use(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const name = String(req.params.name);
+      const greeting = await requireModels(this.#ctx).get("Greeting").findOne({ name }).lean();
+      if (!greeting) throw new HttpError(404, "noSuchGreeting", { vars: { name } });
+      // Without a queues provider the count is updated in the request itself.
+      await requireModels(this.#ctx).get("Greeting").updateOne({ name }, { $inc: { times_used: 1 } });
+      res.respond({ data: { name, message: greeting.message } });
+    };
+  }
+}