@yrest/cli 0.5.3

package/dist/cli/index.js

@@ -0,0 +1,1514 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/cli/index.ts
+var import_commander = require("commander");
+var import_module = require("module");
+
+// src/cli/commands/init.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/cli/commands/templates/basic.ts
+var basicTemplate = `users:
+  - id: 1
+    name: Ana
+    email: ana@test.com
+  - id: 2
+    name: Luis
+    email: luis@test.com
+
+products:
+  - id: 1
+    name: Laptop
+    price: 999
+  - id: 2
+    name: Phone
+    price: 499
+`;
+
+// src/cli/commands/templates/relational.ts
+var relationalTemplate = `_rel:
+  posts:
+    userId: users
+  comments:
+    postId: posts
+
+users:
+  - id: 1
+    name: Ana
+    email: ana@test.com
+  - id: 2
+    name: Luis
+    email: luis@test.com
+
+posts:
+  - id: 1
+    title: First post
+    body: Content of the first post
+    userId: 1
+  - id: 2
+    title: Second post
+    body: Content of the second post
+    userId: 1
+
+comments:
+  - id: 1
+    body: Great post!
+    postId: 1
+  - id: 2
+    body: Thanks for sharing
+    postId: 1
+`;
+
+// src/cli/commands/templates/index.ts
+var SAMPLES = ["basic", "relational"];
+var templates = {
+  basic: basicTemplate,
+  relational: relationalTemplate
+};
+
+// src/cli/commands/init.ts
+var CONFIG_TEMPLATE = `# yrest configuration
+# All options can be overridden with CLI flags
+
+file: db.yml        # YAML database file
+port: 3070          # Port to listen on
+host: localhost     # Host to bind
+# base: /api        # Base path prefix for all routes
+# watch: false      # Reload db file on change
+# readonly: false   # Block write operations (POST, PUT, PATCH, DELETE)
+# delay: 0          # Simulated network latency in milliseconds
+# pageable: false   # Wrap GET collections in { data, pagination }. Use true (limit 10) or a number
+# snapshot: false   # Save initial db state and expose /_snapshot endpoints (GET / POST save / POST reset)
+# handlers: ./yrest.handlers.js  # JS file exporting handler functions for custom routes
+`;
+function registerInit(program2) {
+  program2.command("init").description("Create a sample db.yml and yrest.config.yml in the current directory").option("-f, --file <name>", "Output filename", "db.yml").option("-s, --sample <name>", `Sample data to use (${SAMPLES.join(", ")})`, "basic").action((flags) => {
+    if (!SAMPLES.includes(flags.sample)) {
+      console.error(`Error: unknown sample "${flags.sample}". Available: ${SAMPLES.join(", ")}`);
+      process.exit(1);
+    }
+    const target = (0, import_node_path.resolve)(process.cwd(), flags.file);
+    if ((0, import_node_fs.existsSync)(target)) {
+      console.error(`Error: ${flags.file} already exists.`);
+      process.exit(1);
+    }
+    (0, import_node_fs.writeFileSync)(target, templates[flags.sample], "utf8");
+    console.log(`Created ${flags.file} (sample: ${flags.sample})`);
+    const configTarget = (0, import_node_path.resolve)(process.cwd(), "yrest.config.yml");
+    if (!(0, import_node_fs.existsSync)(configTarget)) {
+      (0, import_node_fs.writeFileSync)(configTarget, CONFIG_TEMPLATE, "utf8");
+      console.log("Created yrest.config.yml");
+    }
+    console.log(`Run: npx @yrest/cli serve`);
+  });
+}
+
+// src/cli/commands/serve.ts
+var import_node_fs5 = require("fs");
+var import_node_path3 = require("path");
+
+// src/storage/yamlStorage.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var import_node_crypto = require("crypto");
+var import_yaml = require("yaml");
+
+// src/utils/deepCopy.ts
+function deepCopyData(source) {
+  return Object.fromEntries(
+    Object.entries(source).map(([k, v]) => [k, v.map((item) => ({ ...item }))])
+  );
+}
+
+// src/storage/yamlStorage.ts
+function createYamlStorage(filePath) {
+  const absPath = (0, import_node_path2.resolve)(filePath);
+  const raw = (0, import_yaml.parse)((0, import_node_fs2.readFileSync)(absPath, "utf8")) ?? {};
+  const relations = raw["_rel"] ?? {};
+  const routes = Array.isArray(raw["_routes"]) ? raw["_routes"] : [];
+  const data = Object.fromEntries(
+    Object.entries(raw).filter(([key]) => key !== "_rel" && key !== "_routes")
+  );
+  let snapshot = {
+    data: deepCopyData(data),
+    relations: { ...relations },
+    savedAt: /* @__PURE__ */ new Date()
+  };
+  return {
+    getData() {
+      return data;
+    },
+    getRelations() {
+      return relations;
+    },
+    getRoutes() {
+      return routes;
+    },
+    getCollection(name) {
+      return data[name];
+    },
+    setCollection(name, items) {
+      data[name] = items;
+    },
+    persist() {
+      const payload = {};
+      if (Object.keys(relations).length > 0) payload._rel = relations;
+      if (routes.length > 0) payload._routes = routes;
+      Object.assign(payload, data);
+      const tmp = (0, import_node_path2.resolve)((0, import_node_path2.dirname)(absPath), `.yrest-${(0, import_node_crypto.randomUUID)()}.tmp`);
+      (0, import_node_fs2.writeFileSync)(tmp, (0, import_yaml.stringify)(payload), "utf8");
+      (0, import_node_fs2.renameSync)(tmp, absPath);
+    },
+    reload() {
+      const fresh = (0, import_yaml.parse)((0, import_node_fs2.readFileSync)(absPath, "utf8")) ?? {};
+      const freshRelations = fresh["_rel"] ?? {};
+      const freshData = Object.fromEntries(
+        Object.entries(fresh).filter(([key]) => key !== "_rel" && key !== "_routes")
+      );
+      for (const key of Object.keys(data)) delete data[key];
+      Object.assign(data, freshData);
+      for (const key of Object.keys(relations)) delete relations[key];
+      Object.assign(relations, freshRelations);
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    saveSnapshot() {
+      snapshot = {
+        data: deepCopyData(data),
+        relations: { ...relations },
+        savedAt: /* @__PURE__ */ new Date()
+      };
+    },
+    resetToSnapshot() {
+      const snap = deepCopyData(snapshot.data);
+      for (const key of Object.keys(data)) delete data[key];
+      Object.assign(data, snap);
+      for (const key of Object.keys(relations)) delete relations[key];
+      Object.assign(relations, { ...snapshot.relations });
+      this.persist();
+    }
+  };
+}
+
+// src/server/createServer.ts
+var import_fastify = __toESM(require("fastify"));
+var import_cors = __toESM(require("@fastify/cors"));
+
+// src/utils/interpolate.ts
+var import_node_crypto2 = require("crypto");
+function getPath(obj, path) {
+  return path.split(".").reduce((acc, key) => {
+    if (acc != null && typeof acc === "object") return acc[key];
+    return void 0;
+  }, obj);
+}
+function resolveVar(path, ctx) {
+  if (path === "now") return (/* @__PURE__ */ new Date()).toISOString();
+  if (path === "uuid") return (0, import_node_crypto2.randomUUID)();
+  if (path === "body") return ctx.body;
+  if (path.startsWith("body.")) return getPath(ctx.body, path.slice(5));
+  if (path.startsWith("params.")) return ctx.params[path.slice(7)] ?? "";
+  if (path.startsWith("query.")) {
+    const val = ctx.query[path.slice(6)];
+    return Array.isArray(val) ? val[0] : val ?? "";
+  }
+  if (path.startsWith("headers.")) {
+    const val = ctx.headers[path.slice(8)];
+    return Array.isArray(val) ? val[0] : val ?? "";
+  }
+  return "";
+}
+function interpolateString(str, ctx) {
+  const exact = str.match(/^\{\{([^}]+)\}\}$/);
+  if (exact) return resolveVar(exact[1].trim(), ctx);
+  return str.replace(/\{\{([^}]+)\}\}/g, (_, path) => {
+    const val = resolveVar(path.trim(), ctx);
+    return val == null ? "" : String(val);
+  });
+}
+function interpolate(template, ctx) {
+  if (typeof template === "string") return interpolateString(template, ctx);
+  if (Array.isArray(template)) return template.map((item) => interpolate(item, ctx));
+  if (template !== null && typeof template === "object") {
+    return Object.fromEntries(
+      Object.entries(template).map(([k, v]) => [k, interpolate(v, ctx)])
+    );
+  }
+  return template;
+}
+function hasTemplates(value) {
+  return typeof value === "string" ? value.includes("{{") : JSON.stringify(value).includes("{{");
+}
+
+// src/router/templates/about.template.ts
+var METHOD_COLOR = {
+  GET: "#3fb950",
+  POST: "#58a6ff",
+  PUT: "#d29922",
+  PATCH: "#a371f7",
+  DELETE: "#f85149",
+  fn: "#f0883e"
+};
+function badge(label, color, bg) {
+  return `<span class="badge" style="background:${bg};color:${color};border:1px solid ${color}40">${label}</span>`;
+}
+function methodBadge(method) {
+  const color = METHOD_COLOR[method] ?? "#7d8590";
+  return badge(method, color, `${color}18`);
+}
+function endpointRow(method, path, desc) {
+  return `
+    <tr>
+      <td class="method-cell">${methodBadge(method)}</td>
+      <td class="path-cell"><code>${path}</code></td>
+      <td class="desc-cell">${desc}</td>
+    </tr>`;
+}
+function resourceAccordion(name, base, isOpen) {
+  const p = `${base}/${name}`;
+  const singular = name.endsWith("s") ? name.slice(0, -1) : name;
+  const rows = [
+    endpointRow(
+      "GET",
+      p,
+      `List all ${name}. Supports filters, sort, pagination and <code>?_expand</code>.`
+    ),
+    endpointRow(
+      "POST",
+      p,
+      `Create a new ${singular}. Auto-assigns <code>id</code> if not provided.`
+    ),
+    endpointRow("GET", `${p}/:id`, `Get a single ${singular} by id.`),
+    endpointRow(
+      "PUT",
+      `${p}/:id`,
+      `Fully replace a ${singular}. Original <code>id</code> is always preserved.`
+    ),
+    endpointRow(
+      "PATCH",
+      `${p}/:id`,
+      `Partially update a ${singular} \u2014 only provided fields change.`
+    ),
+    endpointRow("DELETE", `${p}/:id`, `Delete a ${singular} and return it as confirmation.`)
+  ].join("");
+  return `
+  <details class="resource-card" ${isOpen ? "open" : ""}>
+    <summary>
+      <span class="resource-name">/${name}</span>
+      <span class="route-count">6 routes</span>
+    </summary>
+    <table>
+      <tbody>${rows}</tbody>
+    </table>
+  </details>`;
+}
+function examplesBlock(collections, relations, base, host, options, firstCustomRoute) {
+  const examples = [];
+  const firstCol = collections[0];
+  if (firstCol) {
+    const p = `${host}${base}/${firstCol}`;
+    const singular = firstCol.endsWith("s") ? firstCol.slice(0, -1) : firstCol;
+    examples.push(
+      `# List all ${firstCol}
+curl ${p}`,
+      `# Filter by field
+curl "${p}?name=value"`,
+      `# Sort and paginate
+curl "${p}?_sort=id&_order=desc&_page=1&_limit=5"`,
+      `# Get single ${singular}
+curl ${p}/1`,
+      `# Create ${singular}
+curl -X POST ${p} \\
+  -H "Content-Type: application/json" \\
+  -d '{"name":"example"}'`,
+      `# Partially update ${singular}
+curl -X PATCH ${p}/1 \\
+  -H "Content-Type: application/json" \\
+  -d '{"name":"updated"}'`,
+      `# Delete ${singular}
+curl -X DELETE ${p}/1`
+    );
+  }
+  const firstRel = Object.entries(relations)[0];
+  if (firstRel) {
+    const [child, fields] = firstRel;
+    const fk = Object.keys(fields)[0];
+    const expandKey = fk.replace(/Id$/i, "");
+    examples.push(
+      `# Embed parent with ?_expand
+curl "${host}${base}/${child}/1?_expand=${expandKey}"`
+    );
+  }
+  const firstRelEntry = Object.entries(relations)[0];
+  if (firstRelEntry) {
+    const [child, fields] = firstRelEntry;
+    const parent = Object.values(fields)[0];
+    if (parent) {
+      examples.push(`# Nested resource
+curl ${host}${base}/${parent}/1/${child}`);
+    }
+  }
+  if (options.pageable.enabled && firstCol) {
+    examples.push(`# Pageable envelope
+curl "${host}${base}/${firstCol}?_page=2"`);
+  }
+  const firstParentRel = Object.entries(relations).find(
+    ([, fields]) => Object.values(fields).includes(firstCol ?? "")
+  );
+  if (firstCol) {
+    examples.push(
+      `# Project fields with ?_fields
+curl "${host}${base}/${firstCol}?_fields=id,name"`
+    );
+  }
+  if (firstParentRel && firstCol) {
+    const [childName] = firstParentRel;
+    examples.push(
+      `# Embed child collection with ?_embed
+curl "${host}${base}/${firstCol}/1?_embed=${childName}"`
+    );
+  }
+  if (options.snapshot) {
+    examples.push(
+      `# Snapshot endpoints
+curl ${host}/_snapshot
+curl -X POST ${host}/_snapshot/save
+curl -X POST ${host}/_snapshot/reset`
+    );
+  }
+  if (firstCustomRoute) {
+    const method = firstCustomRoute.method?.toUpperCase() ?? "GET";
+    const fullPath = `${host}${base}${firstCustomRoute.path}`;
+    const curlFlag = method === "GET" ? "" : `-X ${method} `;
+    examples.push(`# Custom route
+curl ${curlFlag}${fullPath}`);
+  }
+  const highlighted = examples.map((e) => e.replace(/^(#.+)$/gm, '<span class="cm">$1</span>')).join("\n\n");
+  return `<pre>${highlighted}</pre>`;
+}
+function generateAboutHtml(storage, options, handlers = /* @__PURE__ */ new Map()) {
+  const collections = Object.keys(storage.getData());
+  const relations = storage.getRelations();
+  const base = options.base;
+  const host = `http://${options.host}:${options.port}`;
+  const modes = [];
+  if (options.watch) modes.push(badge("watch", "#38bdf8", "#38bdf818"));
+  if (options.readonly) modes.push(badge("readonly", "#94a3b8", "#94a3b818"));
+  if (options.delay > 0) modes.push(badge(`delay \xB7 ${options.delay}ms`, "#fb923c", "#fb923c18"));
+  if (options.pageable.enabled)
+    modes.push(badge(`pageable \xB7 limit ${options.pageable.limit}`, "#34d399", "#34d39918"));
+  if (options.snapshot) modes.push(badge("snapshot", "#c084fc", "#c084fc18"));
+  if (handlers.size > 0) modes.push(badge(`handlers \xB7 ${handlers.size}`, "#f0883e", "#f0883e18"));
+  const accordions = collections.map((col, i) => resourceAccordion(col, base, i === 0)).join("");
+  const nestedRows = [];
+  for (const [child, fields] of Object.entries(relations)) {
+    for (const [, parent] of Object.entries(fields)) {
+      const nestedPath = `${base}/${parent}/:id/${child}`;
+      const parentSingular = parent.endsWith("s") ? parent.slice(0, -1) : parent;
+      nestedRows.push(
+        endpointRow("GET", nestedPath, `List ${child} belonging to a ${parentSingular}.`)
+      );
+    }
+  }
+  const nestedAccordion = nestedRows.length ? `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">Nested routes</span>
+      <span class="route-count">${nestedRows.length} route${nestedRows.length !== 1 ? "s" : ""}</span>
+    </summary>
+    <table><tbody>${nestedRows.join("")}</tbody></table>
+  </details>` : "";
+  const snapshotAccordion = options.snapshot ? `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">/_snapshot</span>
+      <span class="route-count">3 routes</span>
+    </summary>
+    <table><tbody>
+      ${endpointRow("GET", "/_snapshot", "Returns metadata of the current snapshot: <code>savedAt</code> and item counts per collection.")}
+      ${endpointRow("POST", "/_snapshot/save", "Replaces the stored snapshot with the current database state.")}
+      ${endpointRow("POST", "/_snapshot/reset", "Restores the database to the last saved snapshot and persists to disk.")}
+    </tbody></table>
+  </details>` : "";
+  const customRoutes = storage.getRoutes();
+  const customRoutesAccordion = customRoutes.length ? `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">Custom routes</span>
+      <span class="route-count">${customRoutes.length} route${customRoutes.length !== 1 ? "s" : ""}</span>
+    </summary>
+    <table><tbody>
+      ${customRoutes.map((r) => {
+    const fullPath = `${base}${r.path}`;
+    let desc;
+    if (r.handler) {
+      const found = handlers.has(r.handler);
+      desc = found ? `Handler \u2014 <code>${r.handler}()</code>` : `Handler \u2014 <code>${r.handler}()</code> <span style="color:#f85149">(not loaded)</span>`;
+    } else if (r.response?.body != null && hasTemplates(r.response.body)) {
+      desc = `Dynamic body \u2014 <code>{{\u2026}}</code>`;
+    } else {
+      const status = r.response?.status ?? 200;
+      desc = `Static \u2014 <code>${status}</code>${r.response?.headers ? ` + custom headers` : ""}`;
+    }
+    return endpointRow(r.method?.toUpperCase() ?? "GET", fullPath, desc);
+  }).join("")}
+    </tbody></table>
+  </details>` : "";
+  const routesByHandler = /* @__PURE__ */ new Map();
+  for (const r of customRoutes) {
+    if (r.handler) {
+      const list = routesByHandler.get(r.handler) ?? [];
+      list.push({ method: (r.method ?? "GET").toUpperCase(), path: `${base}${r.path}` });
+      routesByHandler.set(r.handler, list);
+    }
+  }
+  const handlersAccordion = handlers.size > 0 ? `
+  <details class="resource-card nested-card">
+    <summary>
+      <span class="resource-name">Handlers</span>
+      <span class="route-count">${handlers.size} function${handlers.size !== 1 ? "s" : ""}</span>
+    </summary>
+    <table><tbody>
+      ${[...handlers.keys()].map((name) => {
+    const routes = routesByHandler.get(name);
+    const routeDesc = routes ? routes.map((r) => `<code>${r.method} ${r.path}</code>`).join(", ") : `<span style="color:var(--text-muted)">not referenced in _routes</span>`;
+    return endpointRow("fn", name + "()", routeDesc);
+  }).join("")}
+    </tbody></table>
+  </details>` : "";
+  const paginationDesc = options.pageable.enabled ? `Pageable mode active \u2014 default limit <code>${options.pageable.limit}</code>. Response wrapped in <code>{ data, pagination }</code>.` : `Returns the requested slice. <code>X-Total-Count</code> header reflects the total before pagination.`;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>yrest \u2014 API Overview</title>
+  <style>
+    :root {
+      --bg:        #0d1117;
+      --bg-card:   #161b22;
+      --bg-hover:  #1c2128;
+      --bg-inset:  #0d1117;
+      --border:    #30363d;
+      --border-hi: #3d444d;
+      --text:      #e6edf3;
+      --text-muted:#7d8590;
+      --accent:    #58a6ff;
+      --radius:    8px;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { background: var(--bg); color: var(--text); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; font-size: 14px; line-height: 1.6; }
+
+    /* \u2500\u2500 Banner \u2500\u2500 */
+    .banner {
+      width: 100%;
+      background: linear-gradient(135deg, #0d1117 0%, #161b22 40%, #1a2332 100%);
+      border-bottom: 1px solid var(--border);
+      padding: 48px 32px 40px;
+    }
+    .banner-inner { max-width: 1100px; margin: 0 auto; }
+    .banner h1 { font-size: clamp(36px, 6vw, 60px); font-weight: 800; letter-spacing: -2px; line-height: 1; }
+    .banner h1 .y { color: var(--text); }
+    .banner h1 .rest { color: var(--accent); }
+    .banner p { color: var(--text-muted); margin-top: 10px; font-size: 15px; }
+    .banner-meta { display: flex; gap: 24px; margin-top: 20px; flex-wrap: wrap; }
+    .banner-meta span { color: var(--text-muted); font-size: 13px; }
+    .banner-meta span strong { color: var(--text); font-family: monospace; }
+
+    /* \u2500\u2500 Layout \u2500\u2500 */
+    .wrap { max-width: 1100px; margin: 0 auto; padding: 32px 24px 48px; }
+    h2 { font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: .08em; color: var(--text-muted); margin: 32px 0 12px; }
+
+    /* \u2500\u2500 Cards \u2500\u2500 */
+    .card { background: var(--bg-card); border: 1px solid var(--border); border-radius: var(--radius); padding: 20px 24px; }
+    .two-col { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+    @media (max-width: 600px) { .two-col { grid-template-columns: 1fr; } }
+
+    /* \u2500\u2500 Server info grid \u2500\u2500 */
+    .info-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 16px; }
+    .stat label { font-size: 10px; text-transform: uppercase; letter-spacing: .07em; color: var(--text-muted); display: block; margin-bottom: 3px; }
+    .stat value { font-size: 15px; font-weight: 600; font-family: monospace; color: var(--text); }
+
+    /* \u2500\u2500 Mode badges \u2500\u2500 */
+    .modes { display: flex; gap: 8px; flex-wrap: wrap; min-height: 28px; align-items: center; }
+    .badge { display: inline-block; padding: 3px 10px; border-radius: 20px; font-size: 12px; font-weight: 600; white-space: nowrap; }
+
+    /* \u2500\u2500 Endpoints grid (2 cols on wide, 1 col on narrow) \u2500\u2500 */
+    .endpoints-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 10px; }
+    @media (max-width: 860px) { .endpoints-grid { grid-template-columns: 1fr; } }
+    .nested-card { grid-column: 1 / -1; }
+
+    /* \u2500\u2500 Accordion (details/summary) \u2500\u2500 */
+    .resource-card {
+      background: var(--bg-card);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      overflow: hidden;
+      transition: border-color .15s;
+    }
+    .resource-card[open] { border-color: var(--border-hi); }
+    .resource-card summary {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 13px 18px;
+      cursor: pointer;
+      user-select: none;
+      list-style: none;
+      gap: 8px;
+    }
+    .resource-card summary::-webkit-details-marker { display: none; }
+    .resource-card summary::before {
+      content: "\u203A";
+      color: var(--text-muted);
+      font-size: 18px;
+      line-height: 1;
+      transition: transform .2s;
+      margin-right: 4px;
+      flex-shrink: 0;
+    }
+    .resource-card[open] summary::before { transform: rotate(90deg); }
+    .resource-card summary:hover { background: var(--bg-hover); }
+    .resource-name { font-family: monospace; font-size: 14px; font-weight: 600; color: var(--accent); flex: 1; }
+    .route-count { font-size: 11px; color: var(--text-muted); background: var(--bg-inset); border: 1px solid var(--border); padding: 2px 8px; border-radius: 12px; white-space: nowrap; }
+
+    /* \u2500\u2500 Tables \u2500\u2500 */
+    table { width: 100%; border-collapse: collapse; }
+    td { padding: 8px 12px; border-top: 1px solid var(--border); vertical-align: top; font-size: 13px; }
+    .method-cell { width: 78px; white-space: nowrap; }
+    .path-cell { width: 44%; white-space: nowrap; }
+    .desc-cell { color: var(--text-muted); }
+    code { font-family: "SF Mono", "Fira Code", monospace; font-size: 12px; background: #58a6ff15; color: var(--accent); padding: 1px 5px; border-radius: 3px; }
+
+    /* \u2500\u2500 Query params table \u2500\u2500 */
+    .param-table th { text-align: left; padding: 8px 12px; font-size: 10px; text-transform: uppercase; letter-spacing: .06em; color: var(--text-muted); border-bottom: 1px solid var(--border); }
+    .param-table td:first-child { white-space: nowrap; width: 160px; }
+    .param-table td:nth-child(2) { white-space: nowrap; width: 200px; }
+
+    /* \u2500\u2500 Code block \u2500\u2500 */
+    pre { background: #010409; border: 1px solid var(--border); color: #e6edf3; padding: 20px 24px; border-radius: var(--radius); font-size: 12.5px; line-height: 1.8; overflow-x: auto; font-family: "SF Mono", "Fira Code", monospace; }
+    .cm { color: #3d444d; }
+
+    /* \u2500\u2500 Warning \u2500\u2500 */
+    .warn { background: #2d1f0e; border-left: 3px solid #d29922; padding: 10px 14px; border-radius: 0 6px 6px 0; font-size: 13px; color: #d29922; margin-top: 12px; }
+
+    /* \u2500\u2500 Footer \u2500\u2500 */
+    footer { margin-top: 48px; text-align: center; font-size: 11px; color: var(--text-muted); padding-bottom: 16px; }
+    footer a { color: var(--accent); text-decoration: none; }
+  </style>
+</head>
+<body>
+
+  <div class="banner">
+    <div class="banner-inner">
+      <h1><span class="y">y</span><span class="rest">rest</span></h1>
+      <p>Zero-config REST API mock server</p>
+      <div class="banner-meta">
+        <span>URL <strong>${host}</strong></span>
+        <span>Base <strong>${base || "/"}</strong></span>
+        <span>File <strong>${options.file}</strong></span>
+        <span>Collections <strong>${collections.length}</strong></span>
+      </div>
+    </div>
+  </div>
+
+  <div class="wrap">
+
+    <h2>Active Modes</h2>
+    <div class="card">
+      <div class="modes">${modes.length ? modes.join(" ") : `<span style="color:var(--text-muted);font-size:13px">none</span>`}</div>
+      ${options.watch ? `<div class="warn">\u26A0 <strong>Watch mode:</strong> data changes in existing collections reload automatically. Adding or removing entire collections requires a server restart.</div>` : ""}
+    </div>
+
+    <h2>Endpoints</h2>
+    <div class="endpoints-grid">
+      ${accordions}
+      ${nestedAccordion}
+      ${snapshotAccordion}
+      ${customRoutesAccordion}
+      ${handlersAccordion}
+    </div>
+
+    <h2>Query Parameters</h2>
+    <div class="card">
+      <table class="param-table">
+        <thead><tr><th>Param</th><th>Example</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td><code>?field=value</code></td><td><code>?name=Ana&amp;role=admin</code></td><td>Filter by any field. Multiple params are ANDed.</td></tr>
+          <tr><td><code>?field_gte / _lte</code></td><td><code>?price_gte=10&amp;price_lte=50</code></td><td>Numeric or lexicographic range. Works with any comparable field.</td></tr>
+          <tr><td><code>?field_ne</code></td><td><code>?status_ne=inactive</code></td><td>Exclude items where the field equals the value.</td></tr>
+          <tr><td><code>?field_like</code></td><td><code>?name_like=ana</code></td><td>Case-insensitive substring match.</td></tr>
+          <tr><td><code>?field_start</code></td><td><code>?name_start=A</code></td><td>Case-insensitive prefix match.</td></tr>
+          <tr><td><code>?field_regex</code></td><td><code>?email_regex=gmail</code></td><td>Case-insensitive regular expression match.</td></tr>
+          <tr><td><code>?_q</code></td><td><code>?_q=ana</code></td><td>Full-text search across all scalar fields (case-insensitive substring).</td></tr>
+          <tr><td><code>?_sort &amp; ?_order</code></td><td><code>?_sort=name&amp;_order=desc</code></td><td>Sort by field. <code>_order</code>: <code>asc</code> (default) or <code>desc</code>.</td></tr>
+          <tr><td><code>?_page &amp; ?_limit</code></td><td><code>?_page=2&amp;_limit=10</code></td><td>${paginationDesc}</td></tr>
+          <tr><td><code>?_expand</code></td><td><code>?_expand=user</code></td><td>Embed a related parent object inline. Requires <code>_rel</code> in the YAML file.</td></tr>
+          <tr><td><code>?_embed</code></td><td><code>?_embed=posts</code></td><td>Embed child collections into each parent item. Requires <code>_rel</code> in the YAML file.</td></tr>
+          <tr><td><code>?_fields</code></td><td><code>?_fields=id,name</code></td><td>Return only the specified fields. Applied last \u2014 can include embedded/expanded keys.</td></tr>
+        </tbody>
+      </table>
+    </div>
+
+    ${collections.length ? `<h2>Examples</h2><div class="card">${examplesBlock(collections, relations, base, host, options, customRoutes[0])}</div>` : ""}
+
+    <footer>
+      Powered by <a href="https://github.com/aggiovato/yaml-rest" target="_blank">@aggiovato/yrest</a> &nbsp;\xB7&nbsp; <a href="/_about">/_about</a>
+    </footer>
+
+  </div>
+</body>
+</html>`;
+}
+
+// src/router/routes/about.routes.ts
+var AboutRouteCommand = class {
+  constructor(storage, options, handlers = /* @__PURE__ */ new Map()) {
+    this.storage = storage;
+    this.options = options;
+    this.handlers = handlers;
+  }
+  storage;
+  options;
+  handlers;
+  register(server) {
+    server.get("/_about", (_req, reply) => {
+      reply.header("Content-Type", "text/html; charset=utf-8");
+      return reply.send(generateAboutHtml(this.storage, this.options, this.handlers));
+    });
+  }
+};
+
+// src/utils/params.ts
+function nextId(items) {
+  const ids = items.map((i) => i["id"]).filter((id) => typeof id === "number");
+  return ids.length > 0 ? Math.max(...ids) + 1 : 1;
+}
+function firstParam(value) {
+  if (value === void 0) return void 0;
+  return Array.isArray(value) ? value[0] : value;
+}
+
+// src/services/query.service.ts
+var OPERATORS = ["_gte", "_lte", "_ne", "_like", "_start", "_regex"];
+function applyOperator(itemValue, op, filterValue) {
+  const strItem = String(itemValue);
+  const numItem = Number(itemValue);
+  const numFilter = Number(filterValue);
+  const numeric = !isNaN(numItem) && !isNaN(numFilter) && filterValue.trim() !== "";
+  switch (op) {
+    case "_gte":
+      return numeric ? numItem >= numFilter : strItem >= filterValue;
+    case "_lte":
+      return numeric ? numItem <= numFilter : strItem <= filterValue;
+    case "_ne":
+      return strItem !== filterValue;
+    case "_like":
+      return strItem.toLowerCase().includes(filterValue.toLowerCase());
+    case "_start":
+      return strItem.toLowerCase().startsWith(filterValue.toLowerCase());
+    case "_regex": {
+      try {
+        return new RegExp(filterValue, "i").test(strItem);
+      } catch {
+        return false;
+      }
+    }
+  }
+}
+function filterByQuery(items, query) {
+  const filters = Object.entries(query).filter(([key]) => !key.startsWith("_"));
+  if (filters.length === 0) return items;
+  return items.filter(
+    (item) => filters.every(([key, value]) => {
+      const op = OPERATORS.find((o) => key.endsWith(o));
+      if (op) {
+        const field = key.slice(0, -op.length);
+        if (item[field] === void 0) return false;
+        const filterVal = Array.isArray(value) ? value[0] : value;
+        return applyOperator(item[field], op, filterVal);
+      }
+      if (item[key] === void 0) return false;
+      const itemStr = String(item[key]);
+      return Array.isArray(value) ? value.includes(itemStr) : itemStr === value;
+    })
+  );
+}
+function fullTextSearch(items, term) {
+  const lower = term.toLowerCase();
+  return items.filter(
+    (item) => Object.values(item).some((val) => {
+      if (val === null || val === void 0 || typeof val === "object") return false;
+      return String(val).toLowerCase().includes(lower);
+    })
+  );
+}
+function sortBy(items, field, order) {
+  const direction = order === "desc" ? -1 : 1;
+  return [...items].sort((a, b) => {
+    const av = a[field];
+    const bv = b[field];
+    if (av === void 0) return 1;
+    if (bv === void 0) return -1;
+    if (typeof av === "number" && typeof bv === "number") return (av - bv) * direction;
+    return String(av).localeCompare(String(bv), void 0, { sensitivity: "base" }) * direction;
+  });
+}
+function projectFields(input, fields) {
+  if (fields.length === 0) return input;
+  const project = (item) => Object.fromEntries(fields.filter((f) => f in item).map((f) => [f, item[f]]));
+  return Array.isArray(input) ? input.map(project) : project(input);
+}
+function paginate(items, page, limit) {
+  const start = (page - 1) * limit;
+  return items.slice(start, start + limit);
+}
+
+// src/services/resource.service.ts
+function findById(items, id) {
+  return items.find((i) => String(i["id"]) === id);
+}
+function findIndexById(items, id) {
+  return items.findIndex((i) => String(i["id"]) === id);
+}
+function createItem(storage, resource, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const item = {
+    id: body["id"] !== void 0 ? body["id"] : nextId(collection),
+    ...body
+  };
+  storage.setCollection(resource, [...collection, item]);
+  storage.persist();
+  return item;
+}
+function replaceItem(storage, resource, id, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const updated = { ...body, id: collection[idx]["id"] };
+  collection[idx] = updated;
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return updated;
+}
+function patchItem(storage, resource, id, body) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const updated = { ...collection[idx], ...body };
+  collection[idx] = updated;
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return updated;
+}
+function deleteItem(storage, resource, id) {
+  const collection = storage.getCollection(resource) ?? [];
+  const idx = findIndexById(collection, id);
+  if (idx === -1) return void 0;
+  const [deleted] = collection.splice(idx, 1);
+  storage.setCollection(resource, collection);
+  storage.persist();
+  return deleted;
+}
+
+// src/services/expand.service.ts
+function expandItems(input, query, resource, storage) {
+  const isArray = Array.isArray(input);
+  const items = isArray ? input : [input];
+  const expandParam = query["_expand"];
+  if (!expandParam) return isArray ? items : input;
+  const keys = (Array.isArray(expandParam) ? expandParam : [expandParam]).flatMap((v) => v.split(",")).map((k) => k.trim()).filter(Boolean);
+  const resourceRelations = storage.getRelations()[resource] ?? {};
+  const expansions = /* @__PURE__ */ new Map();
+  for (const expandKey of keys) {
+    for (const [field, parentCollection] of Object.entries(resourceRelations)) {
+      const derivedKey = field.replace(/Id$/i, "");
+      if (derivedKey === expandKey || parentCollection === expandKey || parentCollection === `${expandKey}s`) {
+        expansions.set(expandKey, { field, parentCollection });
+        break;
+      }
+    }
+  }
+  if (expansions.size === 0) return isArray ? items : input;
+  const expanded = items.map((item) => {
+    const result = { ...item };
+    for (const [expandKey, { field, parentCollection }] of expansions) {
+      const foreignKeyValue = item[field];
+      if (foreignKeyValue === void 0) continue;
+      const parent = (storage.getCollection(parentCollection) ?? []).find(
+        (p) => String(p["id"]) === String(foreignKeyValue)
+      );
+      if (parent !== void 0) result[expandKey] = parent;
+    }
+    return result;
+  });
+  return isArray ? expanded : expanded[0];
+}
+function embedItems(input, query, resource, storage) {
+  const isArray = Array.isArray(input);
+  const items = isArray ? input : [input];
+  const embedParam = query["_embed"];
+  if (!embedParam) return isArray ? items : input;
+  const keys = (Array.isArray(embedParam) ? embedParam : [embedParam]).flatMap((v) => v.split(",")).map((k) => k.trim()).filter(Boolean);
+  const relations = storage.getRelations();
+  const embeds = /* @__PURE__ */ new Map();
+  for (const embedKey of keys) {
+    outer: for (const [childCollection, fields] of Object.entries(relations)) {
+      for (const [fkField, parentCollection] of Object.entries(fields)) {
+        if (parentCollection === resource && childCollection === embedKey) {
+          embeds.set(embedKey, { childCollection, fkField });
+          break outer;
+        }
+      }
+    }
+  }
+  if (embeds.size === 0) return isArray ? items : input;
+  const result = items.map((item) => {
+    const out = { ...item };
+    for (const [embedKey, { childCollection, fkField }] of embeds) {
+      out[embedKey] = (storage.getCollection(childCollection) ?? []).filter(
+        (child) => String(child[fkField]) === String(item["id"])
+      );
+    }
+    return out;
+  });
+  return isArray ? result : result[0];
+}
+
+// src/router/routes/collection.routes.ts
+var CollectionRouteCommand = class {
+  constructor(storage, resource, base, options) {
+    this.storage = storage;
+    this.resource = resource;
+    this.base = base;
+    this.options = options;
+  }
+  storage;
+  resource;
+  base;
+  options;
+  register(server) {
+    server.get(this.base, (req, reply) => {
+      const collection = this.storage.getCollection(this.resource) ?? [];
+      const filtered = filterByQuery(collection, req.query);
+      const searchTerm = firstParam(req.query["_q"]);
+      const searched = searchTerm ? fullTextSearch(filtered, searchTerm) : filtered;
+      const fields = (firstParam(req.query["_fields"]) ?? "").split(",").map((f) => f.trim()).filter(Boolean);
+      const sortField = firstParam(req.query["_sort"]);
+      const sortOrder = firstParam(req.query["_order"]) === "desc" ? "desc" : "asc";
+      const sorted = sortField ? sortBy(searched, sortField, sortOrder) : searched;
+      if (this.options.pageable.enabled) {
+        const defaultLimit = this.options.pageable.limit;
+        const page = Math.max(1, parseInt(firstParam(req.query["_page"]) ?? "1", 10) || 1);
+        const limit = Math.max(
+          1,
+          parseInt(firstParam(req.query["_limit"]) ?? String(defaultLimit), 10) || defaultLimit
+        );
+        const totalItems = sorted.length;
+        const totalPages = Math.ceil(totalItems / limit) || 1;
+        const data = projectFields(
+          embedItems(
+            expandItems(paginate(sorted, page, limit), req.query, this.resource, this.storage),
+            req.query,
+            this.resource,
+            this.storage
+          ),
+          fields
+        );
+        const pagination = {
+          page,
+          limit,
+          totalItems,
+          totalPages,
+          isFirst: page === 1,
+          isLast: page >= totalPages,
+          hasNext: page < totalPages,
+          hasPrev: page > 1
+        };
+        return reply.send({ data, pagination });
+      }
+      const rawPage = firstParam(req.query["_page"]);
+      const rawLimit = firstParam(req.query["_limit"]);
+      let result;
+      if (!rawPage && !rawLimit) {
+        result = sorted;
+      } else {
+        const page = Math.max(1, parseInt(rawPage ?? "1", 10) || 1);
+        const limit = Math.max(1, parseInt(rawLimit ?? "10", 10) || 10);
+        reply.header("X-Total-Count", String(sorted.length));
+        result = paginate(sorted, page, limit);
+      }
+      return projectFields(
+        embedItems(
+          expandItems(result, req.query, this.resource, this.storage),
+          req.query,
+          this.resource,
+          this.storage
+        ),
+        fields
+      );
+    });
+    server.post(this.base, (req, reply) => {
+      if (!req.body || typeof req.body !== "object" || Array.isArray(req.body)) {
+        return reply.status(400).send({ error: "Request body must be a JSON object" });
+      }
+      const item = createItem(this.storage, this.resource, req.body);
+      return reply.status(201).send(expandItems(item, req.query, this.resource, this.storage));
+    });
+  }
+};
+
+// src/router/routes/custom.routes.ts
+var CustomRouteCommand = class {
+  constructor(storage, base, handlers = /* @__PURE__ */ new Map()) {
+    this.storage = storage;
+    this.base = base;
+    this.handlers = handlers;
+  }
+  storage;
+  base;
+  handlers;
+  register(server) {
+    for (const route of this.storage.getRoutes()) {
+      const method = route.method?.toUpperCase();
+      const path = route.path;
+      if (!method || !path) continue;
+      const url = `${this.base}${path}`;
+      const status = route.response?.status ?? 200;
+      const rawBody = route.response?.body ?? null;
+      const headers = route.response?.headers ?? {};
+      const dynamic = rawBody !== null && hasTemplates(rawBody);
+      const handlerName = route.handler;
+      server.route({
+        method,
+        url,
+        handler: async (req, reply) => {
+          for (const [key, value] of Object.entries(headers)) {
+            reply.header(key, value);
+          }
+          if (handlerName) {
+            const fn = this.handlers.get(handlerName);
+            if (!fn) {
+              return reply.status(501).send({ error: `Handler "${handlerName}" is not defined in the handlers file` });
+            }
+            try {
+              const ctx = {
+                params: req.params,
+                query: req.query,
+                body: req.body,
+                headers: req.headers
+              };
+              const result = await fn(ctx);
+              const resStatus = result.status ?? 200;
+              for (const [k, v] of Object.entries(result.headers ?? {})) {
+                reply.header(k, v);
+              }
+              if (!result.body && resStatus === 204) return reply.status(resStatus).send();
+              return reply.status(resStatus).send(result.body ?? null);
+            } catch (err) {
+              const msg = err instanceof Error ? err.message : String(err);
+              return reply.status(500).send({ error: `Handler "${handlerName}" threw an error: ${msg}` });
+            }
+          }
+          const body = dynamic ? interpolate(rawBody, {
+            params: req.params,
+            query: req.query,
+            body: req.body,
+            headers: req.headers
+          }) : rawBody;
+          if (body === null && status === 204) return reply.status(status).send();
+          return reply.status(status).send(body);
+        }
+      });
+    }
+  }
+};
+
+// src/router/routes/item.routes.ts
+var ItemRouteCommand = class {
+  constructor(storage, resource, base) {
+    this.storage = storage;
+    this.resource = resource;
+    this.base = base;
+  }
+  storage;
+  resource;
+  base;
+  register(server) {
+    server.get(`${this.base}/:id`, (req, reply) => {
+      const item = findById(this.storage.getCollection(this.resource) ?? [], req.params.id);
+      if (!item) return reply.status(404).send({ error: "Not found" });
+      const fields = (req.query["_fields"] ?? "").split(",").map((f) => f.trim()).filter(Boolean);
+      return projectFields(
+        embedItems(
+          expandItems(item, req.query, this.resource, this.storage),
+          req.query,
+          this.resource,
+          this.storage
+        ),
+        fields
+      );
+    });
+    server.put(`${this.base}/:id`, (req, reply) => {
+      if (!req.body || typeof req.body !== "object" || Array.isArray(req.body)) {
+        return reply.status(400).send({ error: "Request body must be a JSON object" });
+      }
+      const item = replaceItem(this.storage, this.resource, req.params.id, req.body);
+      if (!item) return reply.status(404).send({ error: "Not found" });
+      return expandItems(item, req.query, this.resource, this.storage);
+    });
+    server.patch(`${this.base}/:id`, (req, reply) => {
+      if (!req.body || typeof req.body !== "object" || Array.isArray(req.body)) {
+        return reply.status(400).send({ error: "Request body must be a JSON object" });
+      }
+      const item = patchItem(this.storage, this.resource, req.params.id, req.body);
+      if (!item) return reply.status(404).send({ error: "Not found" });
+      return expandItems(item, req.query, this.resource, this.storage);
+    });
+    server.delete(`${this.base}/:id`, (req, reply) => {
+      const item = deleteItem(this.storage, this.resource, req.params.id);
+      if (!item) return reply.status(404).send({ error: "Not found" });
+      return expandItems(item, req.query, this.resource, this.storage);
+    });
+  }
+};
+
+// src/router/routes/nested.routes.ts
+var NestedRouteCommand = class {
+  constructor(storage, relations, base) {
+    this.storage = storage;
+    this.relations = relations;
+    this.base = base;
+  }
+  storage;
+  relations;
+  base;
+  register(server) {
+    for (const [child, fields] of Object.entries(this.relations)) {
+      for (const [field, parent] of Object.entries(fields)) {
+        const collectionPath = `${this.base}/${parent}/:id/${child}`;
+        const itemPath = `${this.base}/${parent}/:id/${child}/:childId`;
+        server.get(collectionPath, (req, reply) => {
+          const parentCollection = this.storage.getCollection(parent) ?? [];
+          const parentItem = findById(parentCollection, req.params.id);
+          if (!parentItem) return reply.status(404).send({ error: "Not found" });
+          const children = (this.storage.getCollection(child) ?? []).filter(
+            (item) => String(item[field]) === req.params.id
+          );
+          return children;
+        });
+        server.get(itemPath, (req, reply) => {
+          const parentCollection = this.storage.getCollection(parent) ?? [];
+          const parentItem = findById(parentCollection, req.params.id);
+          if (!parentItem) return reply.status(404).send({ error: "Not found" });
+          const childItem = (this.storage.getCollection(child) ?? []).find(
+            (item) => String(item[field]) === req.params.id && String(item["id"]) === req.params.childId
+          );
+          if (!childItem) return reply.status(404).send({ error: "Not found" });
+          return childItem;
+        });
+      }
+    }
+  }
+};
+
+// src/router/routes/snapshot.routes.ts
+var SnapshotRouteCommand = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  storage;
+  register(server) {
+    server.get("/_snapshot", (_req, reply) => {
+      const { data, savedAt } = this.storage.getSnapshot();
+      return reply.send({
+        savedAt: savedAt.toISOString(),
+        collections: Object.fromEntries(
+          Object.entries(data).map(([name, items]) => [name, items.length])
+        )
+      });
+    });
+    server.post("/_snapshot/save", (_req, reply) => {
+      this.storage.saveSnapshot();
+      const { data, savedAt } = this.storage.getSnapshot();
+      return reply.send({
+        message: "Snapshot saved",
+        savedAt: savedAt.toISOString(),
+        collections: Object.fromEntries(
+          Object.entries(data).map(([name, items]) => [name, items.length])
+        )
+      });
+    });
+    server.post("/_snapshot/reset", (_req, reply) => {
+      this.storage.resetToSnapshot();
+      const { data, savedAt } = this.storage.getSnapshot();
+      return reply.send({
+        message: "Database restored to snapshot",
+        savedAt: savedAt.toISOString(),
+        collections: Object.fromEntries(
+          Object.entries(data).map(([name, items]) => [name, items.length])
+        )
+      });
+    });
+  }
+};
+
+// src/router/resource.router.ts
+function buildResourceRouteCommands(storage, options) {
+  const commands = [];
+  for (const resource of Object.keys(storage.getData())) {
+    const resourceBase = `${options.base}/${resource}`;
+    commands.push(new CollectionRouteCommand(storage, resource, resourceBase, options));
+    commands.push(new ItemRouteCommand(storage, resource, resourceBase));
+  }
+  commands.push(new NestedRouteCommand(storage, storage.getRelations(), options.base));
+  return commands;
+}
+
+// src/server/createServer.ts
+var MUTATING_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+async function createServer(storage, options, handlers = /* @__PURE__ */ new Map()) {
+  const server = (0, import_fastify.default)();
+  await server.register(import_cors.default, {
+    exposedHeaders: ["X-Total-Count"]
+  });
+  server.setErrorHandler((err, _req, reply) => {
+    const status = err.statusCode ?? 500;
+    const message = status < 500 ? err.message || "Request error" : "Internal server error";
+    reply.status(status).send({ error: message });
+  });
+  if (options.readonly) {
+    server.addHook("onRequest", (_req, reply, done) => {
+      if (MUTATING_METHODS.has(_req.method)) {
+        reply.status(405).header("Allow", "GET, HEAD, OPTIONS").send({ error: "Server is running in readonly mode" });
+      }
+      done();
+    });
+  }
+  if (options.delay > 0) {
+    server.addHook("onSend", (_req, _reply, payload, done) => {
+      setTimeout(() => done(null, payload), options.delay);
+    });
+  }
+  const commands = [
+    new AboutRouteCommand(storage, options, handlers),
+    ...options.snapshot ? [new SnapshotRouteCommand(storage)] : [],
+    new CustomRouteCommand(storage, options.base, handlers),
+    ...buildResourceRouteCommands(storage, options)
+  ];
+  for (const command of commands) {
+    command.register(server);
+  }
+  return server;
+}
+
+// src/config/loadOptions.ts
+var import_zod = require("zod");
+var serverOptionsSchema = import_zod.z.object({
+  /** Path to the YAML database file. Must be a non-empty string. */
+  file: import_zod.z.string().min(1),
+  /** TCP port the server listens on. Accepts string input and coerces to number. */
+  port: import_zod.z.coerce.number().int().positive().default(3070),
+  /** Hostname or IP address to bind. */
+  host: import_zod.z.string().default("localhost"),
+  /**
+   * URL prefix prepended to every route (e.g. `/api`).
+   * A leading slash is added automatically if omitted.
+   */
+  base: import_zod.z.string().default("").transform((v) => v && !v.startsWith("/") ? `/${v}` : v),
+  /** When `true`, the server reloads the YAML file automatically on disk changes. */
+  watch: import_zod.z.boolean().default(false),
+  /**
+   * When `true`, saves a snapshot of the initial database state on startup.
+   * Exposes `/_snapshot` endpoints to inspect, restore or update the snapshot.
+   */
+  snapshot: import_zod.z.boolean().default(false),
+  /** When `true`, all mutating requests (POST, PUT, PATCH, DELETE) are rejected with 405. */
+  readonly: import_zod.z.boolean().default(false),
+  /** Milliseconds to delay every response, simulating network latency. `0` = disabled. */
+  delay: import_zod.z.coerce.number().int().min(0).default(0),
+  /**
+   * Path to a JavaScript file exporting handler functions for custom routes.
+   * When set, functions are loaded at startup and referenced by name via `handler:` in `_routes`.
+   */
+  handlers: import_zod.z.string().optional(),
+  /**
+   * Wraps GET collection responses in a `{ data, pagination }` envelope.
+   * Accepts `true` (default limit 10), `false` (disabled), or a positive integer (custom limit).
+   */
+  pageable: import_zod.z.union([import_zod.z.boolean(), import_zod.z.coerce.number().int().positive()]).default(false).transform((v) => ({
+    enabled: v !== false,
+    limit: v === false || v === true ? 10 : v
+  }))
+});
+
+// src/config/loadConfigFile.ts
+var import_node_fs3 = require("fs");
+var import_yaml2 = require("yaml");
+function loadConfigFile(configPath) {
+  if (!(0, import_node_fs3.existsSync)(configPath)) return {};
+  const raw = (0, import_node_fs3.readFileSync)(configPath, "utf8");
+  return (0, import_yaml2.parse)(raw) ?? {};
+}
+
+// src/utils/handlers.ts
+var import_node_fs4 = require("fs");
+async function loadHandlers(filePath) {
+  if (!(0, import_node_fs4.existsSync)(filePath)) return /* @__PURE__ */ new Map();
+  try {
+    const mod = await import(filePath);
+    const map = /* @__PURE__ */ new Map();
+    for (const [name, value] of Object.entries(mod)) {
+      if (typeof value === "function") map.set(name, value);
+    }
+    return map;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`  \x1B[31m[handlers] failed to load ${filePath} \u2014 ${msg}\x1B[0m`);
+    return /* @__PURE__ */ new Map();
+  }
+}
+
+// src/cli/commands/serve.ts
+function registerServe(program2) {
+  program2.command("serve").description("Start the mock server using a YAML file as database").argument("[file]", "Path to the YAML database file", "db.yml").option("-p, --port <number>", "Port to listen on", "3070").option("-H, --host <host>", "Host to bind", "localhost").option("-b, --base <path>", "Base path prefix for all routes", "").option("-w, --watch", "Reload db.yml automatically when it changes on disk").option("-r, --readonly", "Reject all write operations (POST, PUT, PATCH, DELETE) with 405").option(
+    "-d, --delay <ms>",
+    "Add a fixed delay (ms) to all responses to simulate network latency",
+    "0"
+  ).option(
+    "--pageable [limit]",
+    "Wrap GET collection responses in { data, pagination } envelope. Optionally set default page size (default: 10)"
+  ).option(
+    "--snapshot",
+    "Save a snapshot of the initial database state and expose /_snapshot endpoints"
+  ).option(
+    "--handlers <file>",
+    "Path to a JavaScript file exporting custom route handler functions"
+  ).action(async (file, flags, cmd) => {
+    const fileConfig = loadConfigFile((0, import_node_path3.join)(process.cwd(), "yrest.config.yml"));
+    const cliOverrides = Object.fromEntries(
+      Object.entries(flags).filter(([key]) => cmd.getOptionValueSource(key) === "cli")
+    );
+    const merged = {
+      file,
+      ...fileConfig,
+      ...cmd.args.length > 0 ? { file } : {},
+      ...cliOverrides
+    };
+    const options = serverOptionsSchema.parse(merged);
+    let storage;
+    try {
+      storage = createYamlStorage(options.file);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`Error: cannot load "${options.file}" \u2014 ${msg}`);
+      process.exit(1);
+    }
+    const handlers = options.handlers ? await loadHandlers((0, import_node_path3.resolve)(options.handlers)) : /* @__PURE__ */ new Map();
+    const server = await createServer(storage, options, handlers);
+    await server.listen({ port: options.port, host: options.host });
+    const collections = Object.keys(storage.getData());
+    const customRoutes = storage.getRoutes();
+    const base = options.base || "/";
+    const b = (s) => `\x1B[1m${s}\x1B[0m`;
+    const dim = (s) => `\x1B[2m${s}\x1B[0m`;
+    const green = (s) => `\x1B[32m${s}\x1B[0m`;
+    const methodStr = (m) => {
+      const colors = {
+        GET: "\x1B[32m",
+        POST: "\x1B[33m",
+        PUT: "\x1B[34m",
+        PATCH: "\x1B[36m",
+        DELETE: "\x1B[31m"
+      };
+      const u = m.toUpperCase();
+      return `${colors[u] ?? ""}${u.padEnd(7)}\x1B[0m`;
+    };
+    console.log(
+      `
+  ${b("yrest")}  ${dim("\xB7")}  ${green(`http://${options.host}:${options.port}`)}
+`
+    );
+    console.log(`  ${b("Collections")} ${dim(`(base: ${base})`)}:`);
+    for (const name of collections) {
+      console.log(`    ${dim("CRUD")}  ${options.base}/${name}`);
+    }
+    console.log(`
+  ${b("Meta")}:`);
+    console.log(`    ${methodStr("GET")}${dim("/_about")}`);
+    if (options.snapshot) {
+      console.log(`    ${methodStr("GET")}${dim("/_snapshot")}`);
+      console.log(`    ${methodStr("POST")}${dim("/_snapshot/save")}`);
+      console.log(`    ${methodStr("POST")}${dim("/_snapshot/reset")}`);
+    }
+    if (customRoutes.length > 0) {
+      console.log(`
+  ${b("Custom routes")}:`);
+      for (const route of customRoutes) {
+        const method = (route.method ?? "GET").toUpperCase();
+        const label = route.handler ? dim(`\u2192 ${route.handler}()`) : "";
+        console.log(`    ${methodStr(method)}${options.base}${route.path}  ${label}`);
+      }
+    }
+    if (handlers.size > 0) {
+      console.log(`
+  ${b("Handlers")} ${dim(`(${options.handlers})`)}:`);
+      for (const name of handlers.keys()) {
+        console.log(`    ${dim("fn")}     ${name}`);
+      }
+    }
+    const modes = [];
+    if (options.readonly) modes.push("readonly");
+    if (options.delay > 0) modes.push(`delay ${options.delay}ms`);
+    if (options.pageable.enabled) modes.push(`pageable (limit ${options.pageable.limit})`);
+    if (options.snapshot) modes.push("snapshot");
+    if (modes.length > 0) console.log(`
+  ${dim(modes.map((m) => `[${m}]`).join("  "))}`);
+    console.log("");
+    if (options.watch) {
+      const absFile = (0, import_node_path3.resolve)(options.file);
+      let debounce;
+      (0, import_node_fs5.watchFile)(absFile, { interval: 300 }, (curr, prev) => {
+        if (curr.mtimeMs === prev.mtimeMs) return;
+        clearTimeout(debounce);
+        debounce = setTimeout(() => {
+          try {
+            storage.reload();
+            console.log(`  \x1B[2m[watch] reloaded ${options.file}\x1B[0m`);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`  \x1B[31m[watch] failed to reload ${options.file} \u2014 ${msg}\x1B[0m`);
+          }
+        }, 100);
+      });
+      console.log(`  \x1B[2m[watch] watching ${options.file} for changes\x1B[0m
+`);
+    }
+  });
+}
+
+// src/cli/commands/handler.ts
+var import_node_fs6 = require("fs");
+var import_node_path4 = require("path");
+var import_yaml3 = require("yaml");
+var HANDLERS_FILE_HEADER = `// yrest handlers \u2014 loaded via "handlers:" in yrest.config.yml
+// Handler signature: (req: HandlerRequest) => HandlerResponse | Promise<HandlerResponse>
+// See https://github.com/aggiovato/yaml-rest for full documentation
+`;
+function buildStub(name, method, path) {
+  const tag = method && path ? `Handler for ${method.toUpperCase()} ${path}` : `yrest handler function`;
+  return [
+    "",
+    `/**`,
+    ` * ${tag}`,
+    ` * @param {import('@yrest/cli').HandlerRequest} req`,
+    ` * @returns {Promise<import('@yrest/cli').HandlerResponse>}`,
+    ` */`,
+    `export async function ${name}(req) {`,
+    `  // TODO: implement handler logic`,
+    `  return { status: 200, body: null };`,
+    `}`,
+    ""
+  ].join("\n");
+}
+function registerHandler(program2) {
+  program2.command("handler").description("Scaffold a handler function stub in the handlers file").argument("<name>", "Name of the handler function to create").option("-m, --method <method>", "HTTP method hint for the stub JSDoc (e.g. POST)").option("-p, --path <path>", "Route path hint for the stub JSDoc (e.g. /login)").option(
+    "--register",
+    "Also add a _routes entry to db.yml linking this handler to method + path"
+  ).action((name, flags) => {
+    const fileConfig = loadConfigFile((0, import_node_path4.join)(process.cwd(), "yrest.config.yml"));
+    const handlersPath = (0, import_node_path4.resolve)(
+      fileConfig.handlers ?? "yrest.handlers.js"
+    );
+    const dbPath = (0, import_node_path4.resolve)(fileConfig.file ?? "db.yml");
+    if (!(0, import_node_fs6.existsSync)(handlersPath)) {
+      (0, import_node_fs6.writeFileSync)(
+        handlersPath,
+        HANDLERS_FILE_HEADER + buildStub(name, flags.method, flags.path),
+        "utf8"
+      );
+      console.log(`  Created ${(0, import_node_path4.basename)(handlersPath)}`);
+    } else {
+      const existing = (0, import_node_fs6.readFileSync)(handlersPath, "utf8");
+      if (existing.includes(`function ${name}(`)) {
+        console.error(`  Error: handler "${name}" already exists in ${(0, import_node_path4.basename)(handlersPath)}`);
+        process.exit(1);
+      }
+      (0, import_node_fs6.appendFileSync)(handlersPath, buildStub(name, flags.method, flags.path), "utf8");
+      console.log(`  Added handler "${name}" to ${(0, import_node_path4.basename)(handlersPath)}`);
+    }
+    if (flags.register) {
+      if (!flags.method || !flags.path) {
+        console.error("  Error: --register requires --method and --path");
+        process.exit(1);
+      }
+      if (!(0, import_node_fs6.existsSync)(dbPath)) {
+        console.error(`  Error: database file not found at ${dbPath}`);
+        process.exit(1);
+      }
+      const raw = (0, import_yaml3.parse)((0, import_node_fs6.readFileSync)(dbPath, "utf8")) ?? {};
+      if (!Array.isArray(raw["_routes"])) raw["_routes"] = [];
+      const routes = raw["_routes"];
+      const alreadyRegistered = routes.some((r) => r["handler"] === name);
+      if (!alreadyRegistered) {
+        routes.push({ method: flags.method.toUpperCase(), path: flags.path, handler: name });
+        (0, import_node_fs6.writeFileSync)(dbPath, (0, import_yaml3.stringify)(raw), "utf8");
+        console.log(`  Added _routes entry to ${(0, import_node_path4.basename)(dbPath)}`);
+      } else {
+        console.log(`  Handler "${name}" already in _routes \u2014 skipped`);
+      }
+    }
+    console.log(`
+  Next steps:`);
+    if (!fileConfig.handlers) {
+      console.log(`    1. Add  handlers: ${(0, import_node_path4.basename)(handlersPath)}  to yrest.config.yml`);
+      console.log(`    2. Implement the "${name}" function in ${(0, import_node_path4.basename)(handlersPath)}`);
+    } else {
+      console.log(`    1. Implement the "${name}" function in ${(0, import_node_path4.basename)(handlersPath)}`);
+    }
+    if (!flags.register) {
+      console.log(
+        `    ${fileConfig.handlers ? "2" : "3"}. Add a _routes entry with  handler: ${name}  in your db.yml`
+      );
+      console.log(`       (or re-run with --register --method <METHOD> --path <path>)`);
+    }
+  });
+}
+
+// src/cli/index.ts
+var require2 = (0, import_module.createRequire)(importMetaUrl);
+var { version } = require2("../../package.json");
+import_commander.program.name("yrest").description("Zero-config REST API mock server powered by a YAML file").version(version);
+registerInit(import_commander.program);
+registerServe(import_commander.program);
+registerHandler(import_commander.program);
+import_commander.program.parse();