@aggiovato/yrest 0.1.1 → 0.2.0

package/dist/cli/index.js

@@ -90,16 +90,22 @@ var templates = {
 };
 
 // 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
+`;
 function registerInit(program2) {
-  program2.command("init").description("Create a sample db.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) => {
+  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(", ")}`
-      );
+      console.error(`Error: unknown sample "${flags.sample}". Available: ${SAMPLES.join(", ")}`);
       process.exit(1);
     }
     const target = (0, import_node_path.resolve)(process.cwd(), flags.file);
@@ -109,10 +115,19 @@ function registerInit(program2) {
     }
     (0, import_node_fs.writeFileSync)(target, templates[flags.sample], "utf8");
     console.log(`Created ${flags.file} (sample: ${flags.sample})`);
-    console.log(`Run: npx @aggiovato/yrest serve ${flags.file}`);
+    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 @aggiovato/yrest serve`);
   });
 }
 
+// src/cli/commands/serve.ts
+var import_node_fs4 = require("fs");
+var import_node_path3 = require("path");
+
 // src/storage/yamlStorage.ts
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
@@ -143,6 +158,17 @@ function createYamlStorage(filePath) {
       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")
+      );
+      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);
     }
   };
 }
@@ -192,17 +218,68 @@ function patchItem(storage, resource, id, body) {
   storage.persist();
   return updated;
 }
+function firstParam(value) {
+  if (value === void 0) return void 0;
+  return Array.isArray(value) ? value[0] : value;
+}
 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]) => item[key] !== void 0 && String(item[key]) === value)
+    (item) => filters.every(([key, value]) => {
+      if (item[key] === void 0) return false;
+      const itemStr = String(item[key]);
+      return Array.isArray(value) ? value.includes(itemStr) : itemStr === value;
+    })
   );
 }
+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 paginate(items, page, limit) {
   const start = (page - 1) * limit;
   return items.slice(start, start + limit);
 }
+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 deleteItem(storage, resource, id) {
   const collection = storage.getCollection(resource) ?? [];
   const idx = findIndexById(collection, id);
@@ -214,104 +291,513 @@ function deleteItem(storage, resource, id) {
 }
 
 // src/router/routes/collection.routes.ts
-function registerCollectionRoutes(server, storage, resource, prefix) {
-  server.get(prefix, (req, reply) => {
+var registerCollectionRoutes = (server, storage, resource, base, options) => {
+  server.get(base, (req, reply) => {
     const collection = storage.getCollection(resource) ?? [];
     const filtered = filterByQuery(collection, req.query);
-    const rawPage = req.query["_page"];
-    const rawLimit = req.query["_limit"];
-    if (!rawPage && !rawLimit) return filtered;
-    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(filtered.length));
-    return paginate(filtered, page, limit);
+    const sortField = firstParam(req.query["_sort"]);
+    const sortOrder = firstParam(req.query["_order"]) === "desc" ? "desc" : "asc";
+    const sorted = sortField ? sortBy(filtered, sortField, sortOrder) : filtered;
+    if (options.pageable.enabled) {
+      const defaultLimit = 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 = expandItems(paginate(sorted, page, limit), req.query, resource, storage);
+      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 expandItems(result, req.query, resource, storage);
   });
-  server.post(prefix, (req, reply) => {
+  server.post(base, (req, reply) => {
     const item = createItem(storage, resource, req.body);
-    return reply.status(201).send(item);
+    return reply.status(201).send(expandItems(item, req.query, resource, storage));
   });
-}
+};
 
 // src/router/routes/item.routes.ts
-function registerItemRoutes(server, storage, resource, prefix) {
-  server.get(`${prefix}/:id`, (req, reply) => {
+var registerItemRoutes = (server, storage, resource, base) => {
+  server.get(`${base}/:id`, (req, reply) => {
     const item = findById(storage.getCollection(resource) ?? [], req.params.id);
     if (!item) return reply.status(404).send({ error: "Not found" });
-    return item;
+    return expandItems(item, req.query, resource, storage);
   });
-  server.put(`${prefix}/:id`, (req, reply) => {
+  server.put(`${base}/:id`, (req, reply) => {
     const item = replaceItem(storage, resource, req.params.id, req.body);
     if (!item) return reply.status(404).send({ error: "Not found" });
-    return item;
+    return expandItems(item, req.query, resource, storage);
   });
-  server.patch(`${prefix}/:id`, (req, reply) => {
+  server.patch(`${base}/:id`, (req, reply) => {
     const item = patchItem(storage, resource, req.params.id, req.body);
     if (!item) return reply.status(404).send({ error: "Not found" });
-    return item;
+    return expandItems(item, req.query, resource, storage);
   });
-  server.delete(`${prefix}/:id`, (req, reply) => {
+  server.delete(`${base}/:id`, (req, reply) => {
     const item = deleteItem(storage, resource, req.params.id);
     if (!item) return reply.status(404).send({ error: "Not found" });
-    return item;
+    return expandItems(item, req.query, resource, storage);
   });
-}
+};
 
 // src/router/routes/nested.routes.ts
-function registerNestedRoutes(server, storage, relations, base) {
+var registerNestedRoutes = (server, storage, relations, base) => {
   for (const [child, fields] of Object.entries(relations)) {
     for (const [field, parent] of Object.entries(fields)) {
-      server.get(
-        `${base}/${parent}/:id/${child}`,
-        (req, reply) => {
-          const parentCollection = storage.getCollection(parent) ?? [];
-          const parentItem = findById(parentCollection, req.params.id);
-          if (!parentItem) return reply.status(404).send({ error: "Not found" });
-          const children = (storage.getCollection(child) ?? []).filter(
-            (item) => String(item[field]) === req.params.id
-          );
-          return children;
-        }
-      );
+      server.get(`${base}/${parent}/:id/${child}`, (req, reply) => {
+        const parentCollection = storage.getCollection(parent) ?? [];
+        const parentItem = findById(parentCollection, req.params.id);
+        if (!parentItem) return reply.status(404).send({ error: "Not found" });
+        const children = (storage.getCollection(child) ?? []).filter(
+          (item) => String(item[field]) === req.params.id
+        );
+        return children;
+      });
     }
   }
-}
+};
 
 // src/router/resource.router.ts
-function registerResourceRoutes(server, storage, base) {
+function registerResourceRoutes(server, storage, options) {
   for (const resource of Object.keys(storage.getData())) {
-    const prefix = `${base}/${resource}`;
-    registerCollectionRoutes(server, storage, resource, prefix);
-    registerItemRoutes(server, storage, resource, prefix);
+    const resourceBase = `${options.base}/${resource}`;
+    registerCollectionRoutes(server, storage, resource, resourceBase, options);
+    registerItemRoutes(server, storage, resource, resourceBase, options);
+  }
+  registerNestedRoutes(server, storage, storage.getRelations(), options.base);
+}
+
+// src/router/templates/about.template.ts
+var METHOD_COLOR = {
+  GET: "#3fb950",
+  POST: "#58a6ff",
+  PUT: "#d29922",
+  PATCH: "#a371f7",
+  DELETE: "#f85149"
+};
+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) {
+  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}"`
+    );
+  }
+  for (const [child, fields] of Object.entries(relations)) {
+    for (const [, parent] of Object.entries(fields)) {
+      examples.push(`# Nested resource
+curl ${host}${base}/${parent}/1/${child}`);
+      break;
+    }
+    break;
+  }
+  if (options.pageable.enabled && firstCol) {
+    examples.push(`# Pageable envelope
+curl "${host}${base}/${firstCol}?_page=2"`);
+  }
+  const highlighted = examples.map((e) => e.replace(/^(#.+)$/gm, '<span class="cm">$1</span>')).join("\n\n");
+  return `<pre>${highlighted}</pre>`;
+}
+function generateAboutHtml(storage, options) {
+  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"));
+  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}.`)
+      );
+    }
   }
-  registerNestedRoutes(server, storage, storage.getRelations(), base);
+  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 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}
+    </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>?_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>
+        </tbody>
+      </table>
+    </div>
+
+    ${collections.length ? `<h2>Examples</h2><div class="card">${examplesBlock(collections, relations, base, host, options)}</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
+function registerAboutRoute(server, storage, options) {
+  server.get("/_about", (_req, reply) => {
+    reply.header("Content-Type", "text/html; charset=utf-8");
+    return reply.send(generateAboutHtml(storage, options));
+  });
 }
 
 // src/server/createServer.ts
+var MUTATING_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 async function createServer(storage, options) {
   const server = (0, import_fastify.default)();
   await server.register(import_cors.default);
-  registerResourceRoutes(server, storage, options.base);
+  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);
+    });
+  }
+  registerAboutRoute(server, storage, options);
+  registerResourceRoutes(server, storage, options);
   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"),
-  base: import_zod.z.string().default("").transform((v) => v && !v.startsWith("/") ? `/${v}` : v)
+  /**
+   * 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`, 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),
+  /**
+   * 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/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", "").action(async (file, flags) => {
-    const options = serverOptionsSchema.parse({
+  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)"
+  ).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,
-      port: flags["port"],
-      host: flags["host"],
-      base: flags["base"]
-    });
+      ...fileConfig,
+      ...cmd.args.length > 0 ? { file } : {},
+      ...cliOverrides
+    };
+    const options = serverOptionsSchema.parse(merged);
     const storage = createYamlStorage(options.file);
     const server = await createServer(storage, options);
     await server.listen({ port: options.port, host: options.host });
@@ -319,12 +805,36 @@ function registerServe(program2) {
     const baseLabel = options.base || "/";
     console.log(`
 yrest running at http://${options.host}:${options.port}`);
+    if (options.readonly) console.log("[readonly] write operations are disabled");
+    if (options.delay > 0) console.log(`[delay] ${options.delay}ms added to all responses`);
+    if (options.pageable.enabled)
+      console.log(
+        `[pageable] responses wrapped in { data, pagination } (limit: ${options.pageable.limit})`
+      );
     console.log(`
 Resources (base: ${baseLabel}):`);
     for (const name of collections) {
       console.log(`  /${name}`);
     }
     console.log("");
+    if (options.watch) {
+      const absFile = (0, import_node_path3.resolve)(options.file);
+      let debounce;
+      (0, import_node_fs4.watchFile)(absFile, { interval: 300 }, (curr, prev) => {
+        if (curr.mtimeMs === prev.mtimeMs) return;
+        clearTimeout(debounce);
+        debounce = setTimeout(() => {
+          try {
+            storage.reload();
+            console.log(`[watch] reloaded ${options.file}`);
+          } catch {
+            console.error(`[watch] failed to reload ${options.file} \u2014 check YAML syntax`);
+          }
+        }, 100);
+      });
+      console.log(`[watch] watching ${options.file} for changes
+`);
+    }
   });
 }