@koltakov/ffa-core 0.6.0 → 0.16.0

package/dist/cli.js

@@ -63,77 +63,170 @@ async function loadConfig() {
 // src/memory-db.ts
 import { faker } from "@faker-js/faker";
 import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync2 } from "fs";
-var FIELD_NAME_MAP = {
+var OP_SUFFIXES = ["_gte", "_lte", "_gt", "_lt", "_in", "_contains", "_ne"];
+function parseFilter(filter) {
+  return Object.entries(filter).map(([key, value]) => {
+    for (const op of OP_SUFFIXES) {
+      if (key.endsWith(op)) {
+        return { field: key.slice(0, -op.length), op, value };
+      }
+    }
+    return { field: key, op: null, value };
+  });
+}
+function applyFilter(item, field, op, value) {
+  const raw = item[field];
+  if (op === null) return String(raw) === value;
+  const num = Number(value);
+  switch (op) {
+    case "_gte":
+      return Number(raw) >= num;
+    case "_lte":
+      return Number(raw) <= num;
+    case "_gt":
+      return Number(raw) > num;
+    case "_lt":
+      return Number(raw) < num;
+    case "_ne":
+      return String(raw) !== value;
+    case "_in":
+      return value.split(",").map((v) => v.trim()).includes(String(raw));
+    case "_contains":
+      return String(raw).toLowerCase().includes(value.toLowerCase());
+    default:
+      return true;
+  }
+}
+var HINT_MAP = {
+  // internet
   email: () => faker.internet.email(),
-  mail: () => faker.internet.email(),
-  name: () => faker.person.firstName(),
-  firstname: () => faker.person.firstName(),
-  first_name: () => faker.person.firstName(),
-  lastname: () => faker.person.lastName(),
-  last_name: () => faker.person.lastName(),
-  surname: () => faker.person.lastName(),
-  fullname: () => faker.person.fullName(),
-  username: () => faker.person.fullName(),
+  url: () => faker.internet.url(),
+  domain: () => faker.internet.domainName(),
+  ip: () => faker.internet.ip(),
+  username: () => faker.internet.username(),
+  // media
+  image: () => faker.image.url(),
+  avatar: () => faker.image.avatar(),
+  // person
+  firstName: () => faker.person.firstName(),
+  lastName: () => faker.person.lastName(),
+  fullName: () => faker.person.fullName(),
+  // contact
   phone: () => faker.phone.number(),
-  tel: () => faker.phone.number(),
-  mobile: () => faker.phone.number(),
+  // location
   city: () => faker.location.city(),
   country: () => faker.location.country(),
   address: () => faker.location.streetAddress(),
   zip: () => faker.location.zipCode(),
-  postal: () => faker.location.zipCode(),
-  url: () => faker.internet.url(),
-  website: () => faker.internet.url(),
-  link: () => faker.internet.url(),
-  avatar: () => faker.image.avatar(),
-  photo: () => faker.image.avatar(),
-  image: () => faker.image.avatar(),
+  locale: () => faker.location.countryCode("alpha-2"),
+  // business
   company: () => faker.company.name(),
-  title: () => faker.lorem.sentence(3),
-  heading: () => faker.lorem.sentence(3),
-  description: () => faker.lorem.paragraph(),
+  jobTitle: () => faker.person.jobTitle(),
+  department: () => faker.commerce.department(),
+  currency: () => faker.finance.currencyCode(),
+  // text
+  word: () => faker.lorem.word(),
+  slug: () => faker.helpers.slugify(faker.lorem.words(2)),
+  sentence: () => faker.lorem.sentence(),
+  paragraph: () => faker.lorem.paragraph(),
   bio: () => faker.lorem.paragraph(),
-  text: () => faker.lorem.paragraph(),
+  // visual
   color: () => faker.color.human(),
-  price: () => faker.commerce.price(),
-  cost: () => faker.commerce.price(),
-  amount: () => faker.commerce.price()
+  hexColor: () => faker.color.rgb({ format: "hex" }),
+  // id
+  uuid: () => faker.string.uuid(),
+  // number hints
+  price: () => parseFloat(faker.commerce.price()),
+  age: () => faker.number.int({ min: 18, max: 80 }),
+  rating: () => faker.number.int({ min: 1, max: 5 }),
+  percent: () => faker.number.int({ min: 0, max: 100 }),
+  lat: () => parseFloat(faker.location.latitude().toString()),
+  lng: () => parseFloat(faker.location.longitude().toString()),
+  year: () => faker.number.int({ min: 1990, max: (/* @__PURE__ */ new Date()).getFullYear() })
+};
+var FIELD_NAME_MAP = {
+  email: HINT_MAP.email,
+  mail: HINT_MAP.email,
+  name: HINT_MAP.firstName,
+  firstname: HINT_MAP.firstName,
+  first_name: HINT_MAP.firstName,
+  lastname: HINT_MAP.lastName,
+  last_name: HINT_MAP.lastName,
+  surname: HINT_MAP.lastName,
+  fullname: HINT_MAP.fullName,
+  username: HINT_MAP.username,
+  phone: HINT_MAP.phone,
+  tel: HINT_MAP.phone,
+  mobile: HINT_MAP.phone,
+  city: HINT_MAP.city,
+  country: HINT_MAP.country,
+  address: HINT_MAP.address,
+  zip: HINT_MAP.zip,
+  postal: HINT_MAP.zip,
+  url: HINT_MAP.url,
+  website: HINT_MAP.url,
+  link: HINT_MAP.url,
+  avatar: HINT_MAP.avatar,
+  photo: HINT_MAP.avatar,
+  image: HINT_MAP.image,
+  company: HINT_MAP.company,
+  title: HINT_MAP.sentence,
+  heading: HINT_MAP.sentence,
+  description: HINT_MAP.paragraph,
+  bio: HINT_MAP.bio,
+  text: HINT_MAP.paragraph,
+  color: HINT_MAP.color,
+  price: HINT_MAP.price,
+  cost: HINT_MAP.price,
+  amount: HINT_MAP.price
 };
 function generateFakeValue(def, fieldName, db) {
-  if (def.type === "enum") {
-    if (def.rules.enumValues?.length) return faker.helpers.arrayElement(def.rules.enumValues);
-    return faker.lorem.word();
-  }
+  if (def.rules.fakeHint) return HINT_MAP[def.rules.fakeHint]();
   if (def.type === "belongsTo") {
     const target = def.rules.entity;
     if (target && db[target]?.length) {
-      const items = db[target];
-      return items[Math.floor(Math.random() * items.length)].id;
+      return db[target][Math.floor(Math.random() * db[target].length)].id;
     }
     return faker.string.uuid();
   }
   if (def.type === "hasMany") {
     const target = def.rules.entity;
     if (target && db[target]?.length) {
-      const items = db[target];
-      const count = faker.number.int({ min: 1, max: Math.min(3, items.length) });
-      return [...items].sort(() => Math.random() - 0.5).slice(0, count).map((i) => i.id);
+      const count = faker.number.int({ min: 1, max: Math.min(3, db[target].length) });
+      return [...db[target]].sort(() => Math.random() - 0.5).slice(0, count).map((i) => i.id);
     }
     return [];
   }
+  if (def.type === "enum") {
+    if (def.rules.enumValues?.length) return faker.helpers.arrayElement(def.rules.enumValues);
+    return faker.lorem.word();
+  }
+  if (def.type === "object") {
+    if (!def.rules.objectFields) return {};
+    return Object.fromEntries(
+      Object.entries(def.rules.objectFields).map(([k, fieldDef]) => [
+        k,
+        generateFakeValue(fieldDef, k, db)
+      ])
+    );
+  }
+  if (def.type === "array") {
+    if (!def.rules.arrayItem) return [];
+    const [min, max] = def.rules.arrayCount ?? [1, 3];
+    const count = faker.number.int({ min, max });
+    return Array.from({ length: count }).map(() => generateFakeValue(def.rules.arrayItem, "item", db));
+  }
   const normalized = fieldName.toLowerCase().replace(/[-\s]/g, "_");
-  const mapFn = FIELD_NAME_MAP[normalized];
-  if (mapFn) return mapFn();
+  if (FIELD_NAME_MAP[normalized]) return FIELD_NAME_MAP[normalized]();
   for (const key of Object.keys(FIELD_NAME_MAP)) {
     if (normalized.includes(key)) return FIELD_NAME_MAP[key]();
   }
-  const { type, rules } = def;
-  switch (type) {
+  switch (def.type) {
     case "string":
       return faker.lorem.word();
     case "number": {
-      const min = rules.min ?? 0;
-      const max = rules.max ?? 1e3;
+      const min = def.rules.min ?? 0;
+      const max = def.rules.max ?? 1e3;
       return faker.number.int({ min, max });
     }
     case "boolean":
@@ -160,41 +253,35 @@ function createMemoryDB(entities, persistPath) {
     try {
       const raw = readFileSync2(persistPath, "utf-8");
       const saved = JSON.parse(raw);
-      for (const name in entities) {
-        db[name] = saved[name] ?? [];
-      }
+      for (const name in entities) db[name] = saved[name] ?? [];
     } catch {
     }
   }
-  function seedAll() {
+  function sortedEntityNames() {
     const names = Object.keys(entities);
-    const sorted = [
+    return [
       ...names.filter((n) => !Object.values(entities[n].fields).some((f) => f.type === "belongsTo" || f.type === "hasMany")),
       ...names.filter((n) => Object.values(entities[n].fields).some((f) => f.type === "belongsTo" || f.type === "hasMany"))
     ];
-    for (const name of sorted) {
-      const { fields, count = 10 } = entities[name];
-      db[name] = Array.from({ length: count }).map(() => generateRecord(fields, db));
-    }
   }
-  const needsSeed = Object.keys(entities).filter((n) => !db[n]);
-  if (needsSeed.length > 0) {
-    const names = Object.keys(entities);
-    const sorted = [
-      ...names.filter((n) => !Object.values(entities[n].fields).some((f) => f.type === "belongsTo" || f.type === "hasMany")),
-      ...names.filter((n) => Object.values(entities[n].fields).some((f) => f.type === "belongsTo" || f.type === "hasMany"))
-    ];
-    for (const name of sorted) {
-      if (!db[name]) {
-        const { fields, count = 10 } = entities[name];
-        db[name] = Array.from({ length: count }).map(() => generateRecord(fields, db));
-      }
-    }
+  function seedEntity(name) {
+    const { fields, count = 10, seed } = entities[name];
+    const seedItems = (seed ?? []).map((record) => ({
+      id: faker.string.uuid(),
+      ...record
+    }));
+    const generateCount = Math.max(0, count - seedItems.length);
+    const generated = Array.from({ length: generateCount }).map(() => generateRecord(fields, db));
+    db[name] = [...seedItems, ...generated];
+  }
+  function seedAll() {
+    for (const name of sortedEntityNames()) seedEntity(name);
+  }
+  for (const name of sortedEntityNames()) {
+    if (!db[name]) seedEntity(name);
   }
   function persist() {
-    if (persistPath) {
-      writeFileSync(persistPath, JSON.stringify(db, null, 2), "utf-8");
-    }
+    if (persistPath) writeFileSync(persistPath, JSON.stringify(db, null, 2), "utf-8");
   }
   return {
     list(entity, options = {}) {
@@ -206,29 +293,42 @@ function createMemoryDB(entities, persistPath) {
         );
       }
       if (options.filter) {
-        for (const [key, value] of Object.entries(options.filter)) {
-          items = items.filter((item) => String(item[key]) === value);
-        }
+        const conditions = parseFilter(options.filter);
+        items = items.filter(
+          (item) => conditions.every(({ field, op, value }) => applyFilter(item, field, op, value))
+        );
       }
       if (options.sort) {
         const sortKey = options.sort;
         const order = options.order ?? "asc";
         items.sort((a, b) => {
-          const aVal = a[sortKey];
-          const bVal = b[sortKey];
+          const aVal = a[sortKey], bVal = b[sortKey];
           if (aVal == null) return 1;
           if (bVal == null) return -1;
           const cmp = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
           return order === "desc" ? -cmp : cmp;
         });
       }
+      const entityMeta = entities[entity]?.meta;
+      const customMeta = {};
+      if (entityMeta) {
+        for (const [key, value] of Object.entries(entityMeta)) {
+          customMeta[key] = typeof value === "function" ? value(items) : value;
+        }
+      }
       const total = items.length;
       const page = options.page ?? 1;
       const limit = options.limit ?? total;
       const pages = limit > 0 ? Math.ceil(total / limit) : 1;
       const offset = (page - 1) * limit;
       const data = options.limit ? items.slice(offset, offset + limit) : items;
-      return { data, meta: { total, page, limit, pages } };
+      return {
+        data,
+        meta: {
+          pagination: { total, page, limit, pages },
+          ...customMeta
+        }
+      };
     },
     get(entity, id) {
       return db[entity]?.find((item) => item.id === id);
@@ -260,6 +360,9 @@ function createMemoryDB(entities, persistPath) {
     },
     count(entity) {
       return db[entity]?.length ?? 0;
+    },
+    snapshot() {
+      return Object.fromEntries(Object.entries(db).map(([k, v]) => [k, v.map((item) => ({ ...item }))]));
     }
   };
 }
@@ -308,6 +411,22 @@ function fieldToZod(def) {
       schema = z.array(z.string());
       break;
     }
+    case "object": {
+      if (!def.rules.objectFields) {
+        schema = z.object({});
+        break;
+      }
+      const shape = {};
+      for (const [k, fieldDef] of Object.entries(def.rules.objectFields)) {
+        shape[k] = fieldToZod(fieldDef);
+      }
+      schema = z.object(shape);
+      break;
+    }
+    case "array": {
+      schema = def.rules.arrayItem ? z.array(fieldToZod(def.rules.arrayItem)) : z.array(z.unknown());
+      break;
+    }
     default: {
       schema = z.unknown();
     }
@@ -504,6 +623,39 @@ function generateOpenApiSpec(config) {
   };
 }
 
+// src/validate-config.ts
+var c = {
+  yellow: "\x1B[33m",
+  reset: "\x1B[0m",
+  bold: "\x1B[1m"
+};
+function validateConfig(entities) {
+  const names = new Set(Object.keys(entities));
+  const warnings = [];
+  for (const [entityName, def] of Object.entries(entities)) {
+    for (const [fieldName, field] of Object.entries(def.fields)) {
+      if ((field.type === "belongsTo" || field.type === "hasMany") && field.rules.entity) {
+        if (!names.has(field.rules.entity)) {
+          warnings.push(
+            `${entityName}.${fieldName} (${field.type}) references '${field.rules.entity}' which is not defined`
+          );
+        }
+      }
+      if (field.type === "enum" && (!field.rules.enumValues || field.rules.enumValues.length === 0)) {
+        warnings.push(`${entityName}.${fieldName} is enum but has no values`);
+      }
+    }
+    if ((def.count ?? 10) < (def.seed?.length ?? 0)) {
+      warnings.push(
+        `${entityName}: seed has ${def.seed.length} records but count is ${def.count} \u2014 seed will be truncated`
+      );
+    }
+  }
+  for (const w of warnings) {
+    console.warn(`  ${c.yellow}${c.bold}\u26A0${c.reset}  ${w}`);
+  }
+}
+
 // src/server.ts
 function pluralize2(word) {
   const lower = word.toLowerCase();
@@ -530,7 +682,7 @@ async function findPort(start) {
   }
   return port;
 }
-var c = {
+var c2 = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
   dim: "\x1B[2m",
@@ -545,29 +697,30 @@ function colorMethod(method) {
   const m = method.toUpperCase().padEnd(6);
   switch (method.toUpperCase()) {
     case "GET":
-      return `${c.cyan}${m}${c.reset}`;
+      return `${c2.cyan}${m}${c2.reset}`;
     case "POST":
-      return `${c.green}${m}${c.reset}`;
+      return `${c2.green}${m}${c2.reset}`;
     case "PUT":
-      return `${c.yellow}${m}${c.reset}`;
+      return `${c2.yellow}${m}${c2.reset}`;
     case "PATCH":
-      return `${c.yellow}${m}${c.reset}`;
+      return `${c2.yellow}${m}${c2.reset}`;
     case "DELETE":
-      return `${c.red}${m}${c.reset}`;
+      return `${c2.red}${m}${c2.reset}`;
     default:
       return m;
   }
 }
 function colorStatus(code) {
   const s = String(code);
-  if (code < 300) return `${c.green}${s}${c.reset}`;
-  if (code < 400) return `${c.cyan}${s}${c.reset}`;
-  if (code < 500) return `${c.yellow}${s}${c.reset}`;
-  return `${c.red}${s}${c.reset}`;
+  if (code < 300) return `${c2.green}${s}${c2.reset}`;
+  if (code < 400) return `${c2.cyan}${s}${c2.reset}`;
+  if (code < 500) return `${c2.yellow}${s}${c2.reset}`;
+  return `${c2.red}${s}${c2.reset}`;
 }
 var currentApp = null;
 async function startServer(portOverride) {
   const config = await loadConfig();
+  validateConfig(config.entities);
   const port = await findPort(portOverride ?? config.server.port);
   const openApiSpec = generateOpenApiSpec(config);
   const app = Fastify({ logger: false });
@@ -588,6 +741,16 @@ async function startServer(portOverride) {
       await new Promise((r) => setTimeout(r, ms));
     });
   }
+  const errorRate = config.server.errorRate;
+  if (errorRate !== void 0 && errorRate > 0) {
+    const SYSTEM_ROUTES_ERR = /* @__PURE__ */ new Set(["/__reset", "/docs", "/openapi.json", "/__snapshot"]);
+    app.addHook("preHandler", async (req, reply) => {
+      if (SYSTEM_ROUTES_ERR.has(req.url) || req.url.startsWith("/docs")) return;
+      if (Math.random() < errorRate) {
+        reply.code(500).send({ error: "Simulated server error", hint: "errorRate is enabled in config" });
+      }
+    });
+  }
   app.addHook("onResponse", (req, reply, done) => {
     if (req.url.startsWith("/docs/static") || req.url === "/favicon.ico") {
       done();
@@ -596,7 +759,7 @@ async function startServer(portOverride) {
     const ms = Date.now() - (req._ffaStart ?? Date.now());
     const method = colorMethod(req.method);
     const status = colorStatus(reply.statusCode);
-    const time = `${c.gray}${ms}ms${c.reset}`;
+    const time = `${c2.gray}${ms}ms${c2.reset}`;
     console.log(`  ${method} ${req.url.padEnd(35)} ${status}  ${time}`);
     done();
   });
@@ -606,10 +769,10 @@ async function startServer(portOverride) {
   }
   const db = createMemoryDB(config.entities, persistPath);
   for (const entityName in config.entities) {
-    const base = `/${pluralize2(entityName)}`;
+    const base2 = `/${pluralize2(entityName)}`;
     const zodSchema = entityToZod(config.entities[entityName].fields);
     const entityFields = config.entities[entityName].fields;
-    app.get(base, (req, reply) => {
+    app.get(base2, (req, reply) => {
       const query = req.query;
       const page = query.page ? Number(query.page) : void 0;
       const limit = query.limit ? Number(query.limit) : void 0;
@@ -632,7 +795,7 @@ async function startServer(portOverride) {
       reply.header("X-Total-Count", String(result.meta.total));
       return result;
     });
-    app.get(`${base}/:id`, (req, reply) => {
+    app.get(`${base2}/:id`, (req, reply) => {
       const item = db.get(entityName, req.params.id);
       if (!item) return reply.code(404).send({ error: "Not found" });
       const include = req.query.include;
@@ -649,13 +812,13 @@ async function startServer(portOverride) {
       }
       return result;
     });
-    app.post(base, (req, reply) => {
+    app.post(base2, (req, reply) => {
       const result = zodSchema.safeParse(req.body);
       if (!result.success)
         return reply.code(422).send({ error: "Validation failed", issues: result.error.issues });
       return reply.code(201).send(db.create(entityName, result.data));
     });
-    app.put(`${base}/:id`, (req, reply) => {
+    app.put(`${base2}/:id`, (req, reply) => {
       const result = zodSchema.safeParse(req.body);
       if (!result.success)
         return reply.code(422).send({ error: "Validation failed", issues: result.error.issues });
@@ -663,7 +826,7 @@ async function startServer(portOverride) {
       if (!item) return reply.code(404).send({ error: "Not found" });
       return item;
     });
-    app.patch(`${base}/:id`, (req, reply) => {
+    app.patch(`${base2}/:id`, (req, reply) => {
       const result = zodSchema.partial().safeParse(req.body);
       if (!result.success)
         return reply.code(422).send({ error: "Validation failed", issues: result.error.issues });
@@ -671,7 +834,7 @@ async function startServer(portOverride) {
       if (!item) return reply.code(404).send({ error: "Not found" });
       return item;
     });
-    app.delete(`${base}/:id`, (req, reply) => {
+    app.delete(`${base2}/:id`, (req, reply) => {
       const ok = db.remove(entityName, req.params.id);
       if (!ok) return reply.code(404).send({ error: "Not found" });
       return { success: true };
@@ -681,23 +844,36 @@ async function startServer(portOverride) {
     db.reset();
     return { success: true, message: "Data reset to seed state" };
   });
+  app.get("/__snapshot", () => db.snapshot());
   app.get("/openapi.json", () => openApiSpec);
   await app.listen({ port, host: "0.0.0.0" });
-  const entityRows = Object.keys(config.entities).map((name) => {
+  const VERSION = "0.16.0";
+  const base = `http://localhost:${port}`;
+  const entityNames = Object.keys(config.entities);
+  const colEntity = Math.max(6, ...entityNames.map((n) => n.length));
+  const colRoute = Math.max(5, ...entityNames.map((n) => `/${pluralize2(n)}`.length));
+  const header = `  ${"Entity".padEnd(colEntity)}  ${"Count".padStart(5)}  Route`;
+  const divider = `  ${"\u2500".repeat(colEntity)}  ${"\u2500".repeat(5)}  ${"\u2500".repeat(colRoute + 18)}`;
+  const entityRows = entityNames.map((name) => {
     const count = db.count(name);
-    const url = `http://localhost:${port}/${pluralize2(name)}`;
-    return `  ${c.gray}\u2192${c.reset} ${name.padEnd(16)} ${c.gray}${String(count).padStart(3)} records${c.reset}   ${c.cyan}${url}${c.reset}`;
+    const route = `/${pluralize2(name)}`;
+    const methods = `${c2.cyan}GET${c2.reset} ${c2.green}POST${c2.reset}`;
+    return `  ${c2.bold}${name.padEnd(colEntity)}${c2.reset}  ${c2.gray}${String(count).padStart(5)}${c2.reset}  ${methods}  ${c2.cyan}${base}${route}${c2.reset}`;
   }).join("\n");
-  const delayInfo = delayConfig !== void 0 ? Array.isArray(delayConfig) ? `  ${c.gray}delay: ${delayConfig[0]}\u2013${delayConfig[1]}ms${c.reset}
-` : `  ${c.gray}delay: ${delayConfig}ms${c.reset}
+  const delayLine = delayConfig !== void 0 ? `  ${c2.gray}delay      ${Array.isArray(delayConfig) ? `${delayConfig[0]}\u2013${delayConfig[1]}ms` : `${delayConfig}ms`}${c2.reset}
+` : "";
+  const errorLine = errorRate !== void 0 && errorRate > 0 ? `  ${c2.yellow}errorRate  ${(errorRate * 100).toFixed(0)}% chance of 500${c2.reset}
 ` : "";
   console.log(
     `
-  ${c.bold}FFA dev server${c.reset}  ${c.gray}v0.6.0${c.reset}
+  ${c2.bold}${c2.cyan}FFA${c2.reset}${c2.bold} dev server${c2.reset}  ${c2.gray}v${VERSION}${c2.reset}
 
+${c2.gray}${header}
+${divider}${c2.reset}
 ${entityRows}
 
-${delayInfo}  ${c.gray}\u2192${c.reset} Swagger UI   ${c.cyan}http://localhost:${port}/docs${c.reset}
+${delayLine}${errorLine}  ${c2.gray}docs    ${c2.reset}${c2.cyan}${base}/docs${c2.reset}
+  ${c2.gray}reset   ${c2.reset}${c2.cyan}POST ${base}/__reset${c2.reset}
 `
   );
   return { app, port };
@@ -741,7 +917,7 @@ program.command("init").description("Create ffa.config.ts in the current directo
     console.log("  ffa.config.ts already exists!");
     process.exit(1);
   }
-  const template = `import { defineConfig, entity, string, number, boolean, enumField } from 'ffa-core'
+  const template = `import { defineConfig, entity, string, number, boolean, enumField } from '@koltakov/ffa-core'
 
 export default defineConfig({
   server: { port: 3333 },
@@ -758,6 +934,30 @@ export default defineConfig({
   writeFileSync2(tsPath, template, "utf-8");
   console.log("  ffa.config.ts created! Run: ffa dev");
 });
+program.command("snapshot").description("Export current DB state from running server to a JSON file").option("-o, --output <file>", "output file path", "ffa-snapshot.json").option("-p, --port <port>", "server port (reads from config by default)").action(async (opts) => {
+  let port = opts.port ? Number(opts.port) : void 0;
+  if (!port) {
+    try {
+      const cfg = await loadConfig();
+      port = cfg.server.port;
+    } catch {
+      port = 3e3;
+    }
+  }
+  try {
+    const res = await fetch(`http://localhost:${port}/__snapshot`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = await res.json();
+    const outPath = resolve(process.cwd(), opts.output);
+    writeFileSync2(outPath, JSON.stringify(data, null, 2), "utf-8");
+    const counts = Object.entries(data).map(([k, v]) => `${k}: ${v.length}`).join(", ");
+    console.log(`  Snapshot saved \u2192 ${outPath}`);
+    console.log(`  ${counts}`);
+  } catch {
+    console.error(`  Failed to snapshot. Is the server running on port ${port}?`);
+    process.exit(1);
+  }
+});
 program.command("reset").description("Delete persisted data file (ffa-data.json)").action(() => {
   const dataPath = resolve(process.cwd(), "ffa-data.json");
   if (!existsSync3(dataPath)) {
@@ -765,6 +965,68 @@ program.command("reset").description("Delete persisted data file (ffa-data.json)
     return;
   }
   unlinkSync(dataPath);
-  console.log("  ffa-data.json deleted. Restart the server to regenerate seed data.");
+  console.log(
+    "  ffa-data.json deleted. Restart the server to regenerate seed data."
+  );
+});
+program.command("inspect").description("Show config structure without starting the server").action(async () => {
+  const c3 = {
+    reset: "\x1B[0m",
+    bold: "\x1B[1m",
+    dim: "\x1B[2m",
+    cyan: "\x1B[36m",
+    green: "\x1B[32m",
+    yellow: "\x1B[33m",
+    blue: "\x1B[34m",
+    gray: "\x1B[90m"
+  };
+  let config;
+  try {
+    config = await loadConfig();
+  } catch (err) {
+    console.error(`  Error: ${err.message}`);
+    process.exit(1);
+  }
+  const entityNames = Object.keys(config.entities);
+  console.log(`
+  ${c3.bold}${c3.cyan}FFA${c3.reset}${c3.bold} inspect${c3.reset}  ${c3.gray}port ${config.server.port}${c3.reset}
+`);
+  for (const name of entityNames) {
+    const def = config.entities[name];
+    const count = def.count ?? 10;
+    const seedCount = def.seed?.length ?? 0;
+    const seedNote = seedCount > 0 ? `  ${c3.green}+${seedCount} seed${c3.reset}` : "";
+    console.log(`  ${c3.bold}${name}${c3.reset}  ${c3.gray}${count} records${c3.reset}${seedNote}`);
+    const fieldEntries = Object.entries(def.fields);
+    const colName = Math.max(...fieldEntries.map(([k]) => k.length));
+    for (const [fieldName, field] of fieldEntries) {
+      const req = field.rules.required ? `${c3.yellow}*${c3.reset}` : " ";
+      const ro = field.rules.readonly ? ` ${c3.gray}readonly${c3.reset}` : "";
+      const hint = field.rules.fakeHint ? ` ${c3.dim}[${field.rules.fakeHint}]${c3.reset}` : "";
+      const rel = field.rules.entity ? ` ${c3.blue}\u2192 ${field.rules.entity}${c3.reset}` : "";
+      const enums = field.rules.enumValues?.length ? ` ${c3.gray}(${field.rules.enumValues.join(" | ")})${c3.reset}` : "";
+      const nested = field.rules.objectFields ? ` ${c3.gray}{ ${Object.keys(field.rules.objectFields).join(", ")} }${c3.reset}` : "";
+      const arrOf = field.rules.arrayItem ? ` ${c3.gray}of ${field.rules.arrayItem.type}${c3.reset}` : "";
+      console.log(
+        `    ${req} ${fieldName.padEnd(colName)}  ${c3.cyan}${field.type}${c3.reset}${hint}${rel}${enums}${nested}${arrOf}${ro}`
+      );
+    }
+    if (def.meta && Object.keys(def.meta).length > 0) {
+      const metaKeys = Object.keys(def.meta);
+      console.log(`       ${c3.gray}meta: ${metaKeys.join(", ")}${c3.reset}`);
+    }
+    console.log();
+  }
+  const { delay, persist, errorRate } = config.server;
+  const info = [];
+  if (delay !== void 0)
+    info.push(`delay ${Array.isArray(delay) ? `${delay[0]}\u2013${delay[1]}ms` : `${delay}ms`}`);
+  if (persist)
+    info.push(`persist ${typeof persist === "string" ? persist : "ffa-data.json"}`);
+  if (errorRate !== void 0 && errorRate > 0)
+    info.push(`errorRate ${(errorRate * 100).toFixed(0)}%`);
+  if (info.length > 0)
+    console.log(`  ${c3.gray}${info.join("  \xB7  ")}${c3.reset}
+`);
 });
 program.parse();