@xirconsss/zero-mock 1.1.0 → 1.2.1

package/README.md

@@ -4,11 +4,22 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue?logo=typescript&logoColor=white)](tsconfig.json)
 [![npm version](https://img.shields.io/npm/v/@xirconsss/zero-mock.svg)](https://www.npmjs.com/package/@xirconsss/zero-mock)
 
-**zero-mock** is a zero-config Node.js CLI that turns a JSON file into a local REST API. Point it at a file whose top-level keys are **collection names** and whose values are **arrays of records**—it serves full CRUD routes and writes changes back to disk. Built for **frontend developers** who need a quick, realistic backend for prototypes, demos, and integration tests without standing up a database or bespoke server.
+**zero-mock** is a zero-config Node.js CLI that turns any JSON file into a persistent, production-grade REST API in seconds. It includes an interactive setup wizard, a high-contrast brutalist UI, and smart schema inference with automatic validation.
 
-## Demo
+Built for frontend developers and architects who need a realistic, stable backend for prototypes, demos, and integration tests without the overhead of database orchestration.
 
-![Terminal demo](docs/demo.gif)
+## Key Features
+
+- **Zero-config** — your JSON file is your database and API definition.
+- **Interactive wizard** — run `zero-mock` to start the setup guide.
+- **Smart validation** — automatically infers Zod schemas from your data to validate `POST`, `PUT`, and `PATCH` requests.
+- **Atomic and secure** — cross-platform atomic writes (Windows-safe) with file-locking to prevent data corruption.
+- **Advanced REST** — supports filtering (`_gte`, `_lte`, `_like`), sorting (`_sort`, `_order`), and pagination (`_page`, `_limit`).
+- **Realistic simulation** — simulate network latency and configure custom CORS origins/methods.
+- **Watch mode** — hot-reloads data from disk on manual file changes without a server restart.
+- **Session memory** — remembers your last used configuration for a faster workflow.
+
+---
 
 ## Installation
 
@@ -18,127 +29,118 @@
 npm install -g @xirconsss/zero-mock
 ```
 
-Run the CLI as **`zero-mock`** (see [Usage](#usage)).
+Run the CLI as `zero-mock`.
 
 ### One-off with npx
 
 ```bash
-npx @xirconsss/zero-mock -f ./example/db.json -p 3000
+npx @xirconsss/zero-mock
 ```
 
-If your shell or npm version forwards extra flags to npm instead of the CLI, insert **`--`** before the first CLI flag (e.g. `npx @xirconsss/zero-mock -- -f ./data.json -p 3000 -w`).
+---
 
 ## Usage
 
-| Flag | Description |
-| ---- | ----------- |
-| **`-f` / `--file`** | Required. Path to the JSON file. |
-| **`-p` / `--port`** | HTTP port (default `3000`, must be 1–65535). |
-| **`-d` / `--delay`** | Optional. Delay every request by this many milliseconds. Must be a non-negative integer using digits only (default `0`). |
-| **`-w` / `--watch`** | Optional. Watch the JSON file and reload the in-memory data when it changes. If a save produces invalid JSON, the server prints `[watch] Could not reload "<path>": ...` to stderr and keeps the last good data until the file is valid again. Only one reload runs at a time. When watch starts, you also get `[watch] Watching "<path>" for changes.` on stdout. |
-
-Examples:
-
-```bash
-zero-mock -f ./data.json -p 3000 -d 200
-zero-mock -f ./data.json -w
-```
-
-## Quick start
+### 1. Interactive mode (recommended)
 
-From the repo root (or any directory containing the example file):
+Run the command without arguments to launch the setup wizard:
 
 ```bash
-npx @xirconsss/zero-mock -f ./example/db.json -p 3000
+zero-mock
 ```
 
-Optional:
-
-```bash
-npx @xirconsss/zero-mock -f ./example/db.json -p 3000 -d 200 -w
-```
+### 2. Manual CLI
 
-In another terminal:
+Pass flags to skip the wizard:
 
 ```bash
-curl http://localhost:3000/users
-curl http://localhost:3000/users/1
+zero-mock -f ./data.json -p 8080 -w -d 200
 ```
 
-The server logs the exact URLs for each collection when it starts.
+| Flag | Description |
+| ---- | ----------- |
+| `-f`, `--file` | Path to the source JSON file. |
+| `-p`, `--port` | HTTP port (default `3000`, must be 1024–65535). |
+| `-d`, `--delay` | Delay every request by X milliseconds (default `0`). |
+| `-w`, `--watch` | Enable hot-reloading on manual file changes. |
+| `--cors-origin` | Comma-separated allowed origins (default `*`). |
+| `--reset` | Clear saved wizard configuration and exit. |
 
-## Development
+---
 
-From a clone: `npm install`, then `npm run build` (or `npm run dev` with `ts-node`). Run the built CLI with:
+## Auto-generated API
 
-```bash
-node dist/index.js -f ./example/db.json -p 3000
-```
+The tool generates full CRUD endpoints for every top-level key in your JSON (e.g., `users`, `posts`).
 
-Add `-d` / `-w` the same way as the published CLI.
+| Method | Path | Description |
+| ------ | ---- | ----------- |
+| `GET` | `/{resource}` | List items (supports filtering, sorting, paging). |
+| `POST` | `/{resource}` | Create item (auto-id + schema validation). |
+| `GET` | `/{resource}/{id}` | Return a single item by `id`. |
+| `PUT` | `/{resource}/{id}` | Replace item (schema validation). |
+| `PATCH` | `/{resource}/{id}` | Partial update (schema validation). |
+| `DELETE` | `/{resource}/{id}` | Remove item. |
 
-## Features
+### Advanced List Features
 
-- **Zero-config** — one JSON file defines your API surface; no schemas or generators to run.
-- **Full CRUD REST API** — `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` per collection, with CORS and JSON bodies enabled.
-- **Atomic file persistence** — writes go through a temp file and rename, with serialized saves so concurrent requests do not corrupt the file.
-- **Smart ID generation** — new rows get the next **numeric** id when existing ids are integers or all-digit strings; otherwise new ids use a **UUID**.
-- **Request logging** — each finished request logs as `[METHOD] <path> - <status>` (path is Express `req.path`, no query string).
-- **Optional delay** — `-d` adds a fixed pause before route handling (after JSON body parsing).
-- **List filtering and pagination** — see [List GET](#list-get) on `GET /{resource}`.
-- **Watch mode** — `-w` reloads data from disk on file change without restarting the process (see [Usage](#usage)).
+**Filtering**
 
-## Auto-generated API
+- `GET /posts?category=tech` — exact match
+- `GET /posts?views_gte=100` — greater than or equal
+- `GET /posts?title_like=hello` — case-insensitive search
 
-Each **top-level key** in your JSON (e.g. `users`, `posts`) becomes a **resource** name. Replace `{resource}` with that key and `{id}` with a row’s `id` (string params match numeric ids loosely).
+**Sorting**
 
-| Method   | Path                 | Description |
-| -------- | -------------------- | ----------- |
-| `GET`    | `/{resource}`        | List items (optionally [filtered and paginated](#list-get)). |
-| `POST`   | `/{resource}`        | Create an item; server assigns `id` and returns `201` with the new body. |
-| `GET`    | `/{resource}/{id}`   | Return one item by `id`; `404` if missing. |
-| `PUT`    | `/{resource}/{id}`   | Replace the item; `id` in the URL wins; `404` if missing. |
-| `PATCH`  | `/{resource}/{id}`   | Shallow-merge fields into the item; `404` if missing. |
-| `DELETE` | `/{resource}/{id}`   | Remove the item; `204` on success; `404` if missing. |
+- `GET /posts?_sort=createdAt&_order=desc`
 
-Invalid JSON bodies (non-objects for write routes) receive **`400`** with a JSON error message. Persistence failures surface as **`500`**.
+**Pagination**
 
-### List GET
+- `GET /posts?_page=1&_limit=10`
+- Returns an `X-Total-Count` header and a wrapped `{ data, pagination }` object.
 
-**Filtering:** Every query parameter except `_page` and `_limit` is a filter. Only plain-object rows are kept. For each filter key, the row must have that property, and the value must match the query value with loose equality (`==`). Query values are strings (first value wins if repeated). Rows missing a filter key are dropped.
+---
 
-**Pagination:** If **both** `_page` and `_limit` are present and are positive integers (digit strings only), the list is sliced after filtering. `_page` is 1-based. If either is missing or invalid, the full filtered list is returned (no error).
+## JSON Structure
 
-Examples using [example/db.json](example/db.json):
+The root must be an object, and every resource must be an array.
 
-```bash
-curl 'http://localhost:3000/users?role=admin'
-curl 'http://localhost:3000/users?_page=1&_limit=2'
+```json
+{
+  "users": [
+    { "id": 1, "name": "Alice", "role": "admin" },
+    { "id": 2, "name": "Bob" }
+  ]
+}
 ```
 
-## JSON file shape
+Note: zero-mock automatically infers that `role` is an optional string based on the items above.
 
-The root must be a JSON **object**. Each property must be an **array** (your “tables”). Each item you want to address by URL should include an **`id`** field (number or string).
+---
 
-## Publishing to npm (maintainers)
+## Development
 
-**Release flow (recommended):** Automated via `semantic-release`. Commits following the conventional commit format (e.g., `feat:`, `fix:`) pushed to `main` will automatically trigger a version bump, changelog generation, and NPM publish via the [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml) workflow. Avoid running `npm publish` on your machine.
+1. Clone the repo.
+2. `npm install`
+3. `npm run dev` (runs with `ts-node`)
+4. `npm run build` (compiles to `dist/`)
 
-1. Use an [npmjs.com](https://www.npmjs.com/) account with **2FA** enabled and permission to publish the **`@xirconsss`** scope (user or org on npm).
-2. **GitHub:** repo → **Settings** → **Environments** → **`NPM_TOKEN`** → add secret **`NPM_TOKEN`** (see token steps below). The workflow uses that environment on each run.
-3. Push conventional commits to **`main`**, wait for **Publish to npm** to finish. Check with `npm view @xirconsss/zero-mock version`.
+---
 
-**Token on npm (required for CI):**
+## Publishing (Maintainers)
 
-1. Create a classic **[Automation](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-classic-tokens)** token, **or** a **[granular access token](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens)** with **read and write** on **`@xirconsss/zero-mock`** (and org **`xirconsss`** if npm asks).
-2. For granular tokens: turn **Bypass two-factor authentication (2FA)** **on** so CI does not hit **`EOTP`**. Do **not** use **`NPM_OTP`** secrets (codes expire in ~30 seconds).
-3. Paste the token into the **`NPM_TOKEN`** environment secret on GitHub.
+This project uses `semantic-release` for fully automated versioning and npm publishing.
 
-**Optional — OIDC trusted publishing:** You can later move to [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) and drop the secret; if you see **`E404`** on `PUT` with OIDC, the Trusted Publisher settings on npm (repo, workflow filename, environment name) do not match this workflow—token auth avoids that until it is configured correctly.
+1. Ensure your commits follow the [Conventional Commits](https://www.conventionalcommits.org/) format (e.g., `feat:`, `fix:`, `chore:`).
+2. Push or open a PR against the `main` branch.
+3. GitHub Actions handles testing, version bumping, changelog generation, and publishing to npm.
+
+---
 
 ## License
 
-MIT - see [LICENSE](LICENSE).
+MIT — see [LICENSE](LICENSE).
+
+---
 
 ## Links
 

package/dist/cleanup.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerLock = registerLock;
+exports.releaseLock = releaseLock;
+exports.registerCleanupTask = registerCleanupTask;
+const fs_1 = __importDefault(require("fs"));
+const errors_1 = require("./errors");
+const activeLocks = new Set();
+const cleanupTasks = new Set();
+function registerLock(lockFilePath) {
+    activeLocks.add(lockFilePath);
+}
+function releaseLock(lockFilePath) {
+    activeLocks.delete(lockFilePath);
+    try {
+        if (fs_1.default.existsSync(lockFilePath)) {
+            fs_1.default.unlinkSync(lockFilePath);
+        }
+    }
+    catch (_) {
+        // Ignore cleanup errors
+    }
+}
+function registerCleanupTask(task) {
+    cleanupTasks.add(task);
+}
+function runCleanup() {
+    for (const lockFilePath of activeLocks) {
+        try {
+            if (fs_1.default.existsSync(lockFilePath)) {
+                fs_1.default.unlinkSync(lockFilePath);
+            }
+        }
+        catch (_) {
+            // Ignore cleanup errors
+        }
+    }
+    activeLocks.clear();
+    for (const task of cleanupTasks) {
+        try {
+            task();
+        }
+        catch (_) {
+            // Ignore cleanup task errors
+        }
+    }
+    cleanupTasks.clear();
+}
+// Module load time registry
+process.on('exit', runCleanup);
+process.on('SIGINT', () => { runCleanup(); process.exit(0); });
+process.on('SIGTERM', () => { runCleanup(); process.exit(0); });
+process.on('SIGHUP', () => { runCleanup(); process.exit(0); });
+process.on('uncaughtException', (err) => {
+    console.error(err);
+    runCleanup();
+    (0, errors_1.printFatal)('SERVER_CRASH', err.message);
+});

package/dist/cli-wizard.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PANEL_W = void 0;
+exports.stripAnsi = stripAnsi;
+exports.centerPad = centerPad;
+exports.sectionHeader = sectionHeader;
+exports.renderConfigPanel = renderConfigPanel;
+exports.runWizard = runWizard;
+const prompts_1 = require("@inquirer/prompts");
+const picocolors_1 = __importDefault(require("picocolors"));
+const config_store_1 = require("./config-store");
+exports.PANEL_W = 42;
+function stripAnsi(s) {
+    return s.replace(/\x1B\[[0-9;]*[mGKHF]/g, '');
+}
+function centerPad(text, width = 42) {
+    const stripped = stripAnsi(text);
+    const padding = Math.max(0, Math.floor((width - stripped.length) / 2));
+    return ' '.repeat(padding) + text;
+}
+function sectionHeader(title) {
+    const header = `${picocolors_1.default.blue('◆')} ${picocolors_1.default.bold(picocolors_1.default.white(title))}`;
+    const rule = picocolors_1.default.dim('─'.repeat(exports.PANEL_W));
+    return `${header}\n${rule}`;
+}
+function renderConfigPanel(config, saved) {
+    let out = picocolors_1.default.dim('╭' + '─'.repeat(exports.PANEL_W) + '╮\n');
+    const rows = [
+        { label: 'Target File', value: config.file },
+        { label: 'Default Port', value: config.port },
+        { label: 'Latency', value: `${config.delay}ms` },
+        { label: 'Watch Mode', value: config.watch ? 'Active' : 'Inactive' },
+    ];
+    for (const row of rows) {
+        const labelPadded = ` · ${row.label} `.padEnd(20, ' ');
+        const valRaw = row.value;
+        const spaceCount = Math.max(0, exports.PANEL_W - labelPadded.length - valRaw.length - 3);
+        const spaces = ' '.repeat(spaceCount);
+        out += picocolors_1.default.dim('│') + picocolors_1.default.dim(labelPadded) + picocolors_1.default.white(row.value) + spaces + ' ' + picocolors_1.default.green('✓') + ' ' + picocolors_1.default.dim('│') + '\n';
+    }
+    if (saved) {
+        out += picocolors_1.default.dim('├' + '─'.repeat(exports.PANEL_W) + '┤\n');
+        const footerText = `last used ${(0, config_store_1.formatSavedAt)(saved.savedAt)}`;
+        const footerPadded = ` · ${footerText} `.padEnd(exports.PANEL_W, ' ');
+        out += picocolors_1.default.dim('│') + picocolors_1.default.dim(footerPadded) + picocolors_1.default.dim('│') + '\n';
+    }
+    out += picocolors_1.default.dim('╰' + '─'.repeat(exports.PANEL_W) + '╯');
+    return out;
+}
+const hex = (hexCode, text) => {
+    const r = parseInt(hexCode.slice(1, 3), 16);
+    const g = parseInt(hexCode.slice(3, 5), 16);
+    const b = parseInt(hexCode.slice(5, 7), 16);
+    return `\x1b[38;2;${r};${g};${b}m${text}\x1b[39m`;
+};
+const FALLBACK = {
+    file: './example/db.json',
+    port: '8080',
+    delay: '200',
+    watch: true,
+};
+async function runWizard() {
+    console.clear();
+    const saved = (0, config_store_1.loadSavedConfig)();
+    const defaults = saved ?? FALLBACK;
+    const isReturning = saved !== null;
+    const logoTop = hex('#bfdbfe', '  ▗▄▄▄▄▖▗▄▄▄▖▗▄▄▖  ▗▄▖ ▗▖  ▗▖ ▗▄▖  ▗▄▄▖▗▖ ▗▖');
+    const logoMid1 = hex('#60a5fa', '     ▗▞▘▐▌   ▐▌ ▐▌▐▌ ▐▌▐▛▚▞▜▌▐▌ ▐▌▐▌   ▐▌▗▞▘');
+    const logoMid2 = hex('#2563eb', '   ▗▞▘  ▐▛▀▀▘▐▛▀▚▖▐▌ ▐▌▐▌  ▐▌▐▌ ▐▌▐▌   ▐▛▚▖ ');
+    const logoBottom = hex('#1e3a8a', '  ▐▙▄▄▄▖▐▙▄▄▖▐▌ ▐▌▝▚▄▞▘▐▌  ▐▌▝▚▄▞▘▝▚▄▄▖▐▌ ▐▌');
+    console.log(`\n${logoTop}\n${logoMid1}\n${logoMid2}\n${logoBottom}\n`);
+    console.log(centerPad(picocolors_1.default.bold(picocolors_1.default.white("Zero-Mock By Xircons"))));
+    console.log(centerPad(picocolors_1.default.dim("Zero-config REST API setup in seconds")));
+    if (isReturning && saved) {
+        console.log(centerPad(picocolors_1.default.dim(`last session ${(0, config_store_1.formatSavedAt)(saved.savedAt)}`)));
+    }
+    console.log('\n' + renderConfigPanel(defaults, saved) + '\n');
+    const promptTheme = { prefix: picocolors_1.default.blue('◆') };
+    const choice = await (0, prompts_1.select)({
+        message: 'What would you like to do?',
+        theme: promptTheme,
+        choices: [
+            { name: `${picocolors_1.default.green('▶')}  Continue`, value: 'continue', short: 'Continue' },
+            { name: `${picocolors_1.default.yellow('◈')}  Change configuration (pick manually)`, value: 'change', short: 'Change configuration' },
+            { name: `${picocolors_1.default.dim('✕')}  Cancel (exit wizard)`, value: 'cancel', short: 'Cancel' },
+        ],
+    });
+    if (choice === 'cancel') {
+        console.clear();
+        console.log(picocolors_1.default.dim('Setup cancelled. zero-mock aborted.'));
+        process.exit(0);
+    }
+    if (choice === 'continue') {
+        console.clear();
+        (0, config_store_1.saveConfig)(defaults, saved);
+        return defaults;
+    }
+    // Change configuration
+    console.clear();
+    console.log('\n' + sectionHeader('CUSTOM CONFIGURATION'));
+    if (isReturning) {
+        console.log(picocolors_1.default.dim('Pre-filled from last session — press Enter to keep\n'));
+    }
+    const file = await (0, prompts_1.input)({
+        message: 'Target File Path:',
+        default: defaults.file,
+        theme: promptTheme,
+        validate: (value) => {
+            if (!value.trim())
+                return "File path cannot be empty.";
+            if (!value.endsWith('.json'))
+                return "File must be a JSON file (.json).";
+            return true;
+        }
+    });
+    const port = await (0, prompts_1.input)({
+        message: 'Port Number:',
+        default: defaults.port,
+        theme: promptTheme,
+        validate: (value) => {
+            const p = parseInt(value, 10);
+            if (isNaN(p) || p < 1 || p > 65535)
+                return "Port must be a number between 1 and 65535.";
+            return true;
+        }
+    });
+    const delay = await (0, prompts_1.input)({
+        message: 'Simulated Latency (ms):',
+        default: defaults.delay,
+        theme: promptTheme,
+        validate: (value) => {
+            const d = parseInt(value, 10);
+            if (isNaN(d) || d < 0)
+                return "Latency must be a non-negative integer.";
+            return true;
+        }
+    });
+    const watch = await (0, prompts_1.confirm)({
+        message: 'Enable Watch Mode (auto-reload on save)?',
+        default: defaults.watch,
+        theme: promptTheme,
+    });
+    const newConfig = { file, port, delay, watch };
+    (0, config_store_1.saveConfig)(newConfig, saved);
+    console.log(`\n  ${picocolors_1.default.green('✓')} Configuration updated.`);
+    console.clear();
+    return newConfig;
+}

package/dist/config-store.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSavedConfig = loadSavedConfig;
+exports.saveConfig = saveConfig;
+exports.clearSavedConfig = clearSavedConfig;
+exports.formatSavedAt = formatSavedAt;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const getConfigPath = () => path_1.default.join(os_1.default.homedir(), '.config', 'zero-mock', 'config.json');
+function loadSavedConfig() {
+    try {
+        const configPath = getConfigPath();
+        if (!fs_1.default.existsSync(configPath)) {
+            return null;
+        }
+        const raw = fs_1.default.readFileSync(configPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof parsed.file === 'string' &&
+            typeof parsed.port === 'string' &&
+            typeof parsed.delay === 'string' &&
+            typeof parsed.watch === 'boolean') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveConfig(config, prev) {
+    try {
+        const configPath = getConfigPath();
+        const configDir = path_1.default.dirname(configPath);
+        fs_1.default.mkdirSync(configDir, { recursive: true });
+        const savedConfig = {
+            ...config,
+            savedAt: new Date().toISOString(),
+            useCount: Math.min((prev?.useCount || 0) + 1, 99999),
+        };
+        fs_1.default.writeFileSync(configPath, JSON.stringify(savedConfig, null, 2), 'utf8');
+    }
+    catch {
+        // Non-fatal, do nothing
+    }
+}
+function clearSavedConfig() {
+    try {
+        const configPath = getConfigPath();
+        if (fs_1.default.existsSync(configPath)) {
+            fs_1.default.unlinkSync(configPath);
+            console.log(`${picocolors_1.default.green('✓')} Cleared saved configuration.`);
+        }
+        else {
+            console.log(`${picocolors_1.default.dim('✕')} No saved configuration found.`);
+        }
+    }
+    catch (err) {
+        console.log(`${picocolors_1.default.red('✕')} Failed to clear config: ${err.message}`);
+    }
+    process.exit(0);
+}
+function formatSavedAt(iso) {
+    const date = new Date(iso);
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const mins = Math.floor(diffMs / 60000);
+    if (mins < 2)
+        return "just now";
+    const hours = Math.floor(mins / 60);
+    if (hours < 1)
+        return `${mins}m ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 1)
+        return `${hours}h ago`;
+    if (days < 7)
+        return `${days}d ago`;
+    return date.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+}

package/dist/errors.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printError = printError;
+exports.printFatal = printFatal;
+exports.validateConfig = validateConfig;
+exports.acquireLock = acquireLock;
+const picocolors_1 = __importDefault(require("picocolors"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const crypto_1 = __importDefault(require("crypto"));
+const cleanup_1 = require("./cleanup");
+const ERROR_MESSAGES = {
+    FILE_NOT_FOUND: { msg: 'Target JSON file not found.', hint: 'Check if the file path is correct.' },
+    FILE_NOT_JSON: { msg: 'Target file is not a JSON file.', hint: 'Ensure the file ends with .json.' },
+    FILE_UNREADABLE: { msg: 'Cannot read the target file.', hint: 'Check file permissions.' },
+    JSON_INVALID: { msg: 'Invalid JSON format.', hint: 'Check the file for syntax errors.' },
+    JSON_NOT_OBJECT: { msg: 'JSON root is not an object.', hint: 'The JSON file must have an object at its root.' },
+    JSON_EMPTY: { msg: 'JSON file is empty.', hint: 'The API will start with no resources. Add arrays to the root object.' },
+    PORT_IN_USE: { msg: 'Port is already in use.', hint: 'Choose a different port or kill the process using it.' },
+    PORT_INVALID: { msg: 'Invalid port number.', hint: 'Port must be an integer between 1024 and 65535.' },
+    PORT_PRIVILEGED: { msg: 'Port requires root privileges.', hint: 'Use a port number >= 1024.' },
+    LOCK_STALE: { msg: 'Found a stale lock file.', hint: 'The lock file will be automatically removed.' },
+    LOCK_CONFLICT: { msg: 'Another instance is running.', hint: 'Stop the other zero-mock instance or use a different file.' },
+    LOCK_WRITE_FAILED: { msg: 'Failed to write lock file.', hint: 'Check directory permissions.' },
+    WATCH_FAILED: { msg: 'File watcher failed to start.', hint: 'Hot-reloading will not work. Check OS file watch limits.' },
+    WATCH_RELOAD_FAILED: { msg: 'Failed to reload JSON file.', hint: 'Fix the JSON syntax error. Serving last good snapshot.' },
+    SERVER_CRASH: { msg: 'Server crashed unexpectedly.', hint: 'Check the error details below.' },
+    UNKNOWN: { msg: 'An unknown error occurred.', hint: 'Please report this issue.' },
+};
+function formatErrorBlock(type, code, detail) {
+    const badge = type === 'ERROR'
+        ? picocolors_1.default.red(picocolors_1.default.bold(picocolors_1.default.inverse(' ERROR ')))
+        : picocolors_1.default.yellow(picocolors_1.default.bold(picocolors_1.default.inverse(' WARN  ')));
+    const { msg, hint } = ERROR_MESSAGES[code];
+    let out = `\n  ${badge}  ${picocolors_1.default.bold(picocolors_1.default.white(msg))}\n`;
+    if (detail) {
+        out += `  ${picocolors_1.default.dim('│')}  ${picocolors_1.default.dim(detail)}\n`;
+    }
+    out += `  ${picocolors_1.default.dim('╰─')}  ${picocolors_1.default.blue(hint)}\n`;
+    return out;
+}
+function printError(code, detail) {
+    console.error(formatErrorBlock('WARN', code, detail));
+}
+function printFatal(code, detail) {
+    console.error(formatErrorBlock('ERROR', code, detail));
+    process.exit(1);
+}
+function validateConfig(file, port) {
+    if (path_1.default.extname(file) !== '.json') {
+        printFatal('FILE_NOT_JSON', `Path: ${file}`);
+    }
+    if (!fs_1.default.existsSync(file)) {
+        printFatal('FILE_NOT_FOUND', `Path: ${file}`);
+    }
+    try {
+        fs_1.default.accessSync(file, fs_1.default.constants.R_OK);
+    }
+    catch (e) {
+        printFatal('FILE_UNREADABLE', e.message);
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        printFatal('PORT_INVALID', `Given: ${port}`);
+    }
+    if (port < 1024) {
+        printFatal('PORT_PRIVILEGED', `Given: ${port}`);
+    }
+}
+function acquireLock(file) {
+    const absoluteDbPath = path_1.default.resolve(file);
+    const hash = crypto_1.default.createHash('md5').update(absoluteDbPath).digest('hex');
+    const lockFilePath = path_1.default.join(os_1.default.tmpdir(), `zero-mock-${hash}.lock`);
+    if (fs_1.default.existsSync(lockFilePath)) {
+        try {
+            const lockData = fs_1.default.readFileSync(lockFilePath, 'utf8');
+            const { pid, startedAt } = JSON.parse(lockData);
+            try {
+                process.kill(pid, 0); // test liveness
+                // Alive
+                printFatal('LOCK_CONFLICT', `PID ${pid} since ${startedAt}`);
+            }
+            catch (e) {
+                if (e.code === 'ESRCH') {
+                    // Stale
+                    printError('LOCK_STALE', `PID ${pid} is dead.`);
+                    fs_1.default.unlinkSync(lockFilePath);
+                }
+                else {
+                    // No permission or other error
+                    printFatal('LOCK_CONFLICT', `Unable to check PID ${pid}.`);
+                }
+            }
+        }
+        catch (e) {
+            // Unreadable or invalid lock file format
+            printError('LOCK_STALE', `Invalid lock file format.`);
+            fs_1.default.unlinkSync(lockFilePath);
+        }
+    }
+    try {
+        fs_1.default.writeFileSync(lockFilePath, JSON.stringify({
+            pid: process.pid,
+            startedAt: new Date().toISOString()
+        }), { flag: 'wx' });
+    }
+    catch (e) {
+        if (e.code === 'EEXIST') {
+            printFatal('LOCK_CONFLICT', 'Lock file appeared during race condition.');
+        }
+        else {
+            printFatal('LOCK_WRITE_FAILED', e.message);
+        }
+    }
+    (0, cleanup_1.registerLock)(lockFilePath);
+}

package/dist/index.js

@@ -1,13 +1,50 @@
 #!/usr/bin/env node
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const chokidar_1 = __importDefault(require("chokidar"));
+const chokidar = __importStar(require("chokidar"));
+const picocolors_1 = __importDefault(require("picocolors"));
 const commander_1 = require("commander");
 const jsonStore_1 = require("./store/jsonStore");
 const bootstrap_1 = require("./server/bootstrap");
+const cli_wizard_1 = require("./cli-wizard");
+const errors_1 = require("./errors");
+const config_store_1 = require("./config-store");
 function parseDelayMs(raw) {
     const trimmed = raw.trim();
     if (!/^\d+$/.test(trimmed)) {
@@ -15,67 +52,95 @@ function parseDelayMs(raw) {
     }
     return Number.parseInt(trimmed, 10);
 }
+const program = new commander_1.Command();
+let watcher = null;
 function startFileWatcher(filePath) {
     let reloadTimeout = null;
+    if (watcher) {
+        watcher.close().catch(() => { });
+        watcher = null;
+    }
     const reload = async () => {
         try {
-            await jsonStore_1.JsonStore.load(filePath);
-            console.log(`[watch] Reloaded "${filePath}".`);
+            await jsonStore_1.JsonStore.load(filePath, true);
+            console.log(`\n  ${picocolors_1.default.dim('│')}  ${picocolors_1.default.green('✓')} ${picocolors_1.default.dim('Hot reloaded data from')} ${picocolors_1.default.white(filePath)}`);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.error(`[watch] Could not reload "${filePath}": ${message}`);
+            (0, errors_1.printError)('WATCH_RELOAD_FAILED', err.message);
         }
     };
-    chokidar_1.default
-        .watch(filePath, { persistent: true, ignoreInitial: true })
-        .on("change", () => {
-        if (reloadTimeout)
-            clearTimeout(reloadTimeout);
-        reloadTimeout = setTimeout(() => void reload(), 100);
-    })
-        .on("error", (err) => {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(`[watch] Watcher error: ${msg}`);
-    });
-    console.log(`[watch] Watching "${filePath}" for changes.`);
+    try {
+        watcher = chokidar.watch(filePath, { persistent: true, ignoreInitial: true });
+        watcher
+            .on("change", () => {
+            if (reloadTimeout)
+                clearTimeout(reloadTimeout);
+            reloadTimeout = setTimeout(() => void reload(), 100);
+        })
+            .on("error", (err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            (0, errors_1.printError)('WATCH_FAILED', msg);
+        });
+    }
+    catch (err) {
+        (0, errors_1.printError)('WATCH_FAILED', err.message);
+    }
 }
-const program = new commander_1.Command();
 program
     .name("zero-mock")
     .description("Generate a REST API from a JSON file")
-    .requiredOption("-f, --file <path>", "path to the source JSON file")
-    .option("-p, --port <number>", "HTTP port", "3000")
-    .option("-d, --delay <ms>", "delay each request by this many ms (0 = off)", "0")
-    .option("-w, --watch", "reload JSON from disk when the file changes", false)
+    .option("-f, --file <path>", "path to the source JSON file")
+    .option("-p, --port <number>", "HTTP port")
+    .option("-d, --delay <ms>", "delay each request by this many ms (0 = off)")
+    .option("-w, --watch", "reload JSON from disk when the file changes")
     .option("--cors-origin <origins>", "comma-separated list of allowed origins (e.g., http://localhost:3000)", "*")
     .option("--cors-methods <methods>", "comma-separated list of allowed HTTP methods", "GET,HEAD,PUT,PATCH,POST,DELETE")
     .option("--cors-credentials", "enable CORS credentials (cookies, authorization headers)", false)
+    .option("--reset", "clear saved wizard configuration")
     .action(async (opts) => {
-    const port = Number.parseInt(opts.port, 10);
-    if (Number.isNaN(port) || port < 1 || port > 65535) {
-        console.error("error: --port must be a number between 1 and 65535");
-        process.exit(1);
-        return;
+    if (process.argv.includes('--reset')) {
+        (0, config_store_1.clearSavedConfig)();
+        process.exit(0);
+    }
+    let { file, port: portRaw, delay: delayRaw, watch } = opts;
+    if (!file && !portRaw && !delayRaw && watch === undefined) {
+        const wizardConfig = await (0, cli_wizard_1.runWizard)();
+        file = wizardConfig.file;
+        portRaw = wizardConfig.port;
+        delayRaw = wizardConfig.delay;
+        watch = wizardConfig.watch;
     }
-    const delayMs = parseDelayMs(opts.delay);
+    else {
+        if (!file) {
+            console.error("error: required option '-f, --file <path>' not specified");
+            process.exit(1);
+            return;
+        }
+        portRaw = portRaw ?? "3000";
+        delayRaw = delayRaw ?? "0";
+        watch = watch ?? false;
+    }
+    const port = Number.parseInt(portRaw, 10);
+    const delayMs = parseDelayMs(delayRaw);
     if (delayMs === null) {
         console.error("error: --delay must be a non-negative integer");
         process.exit(1);
         return;
     }
-    const filePath = opts.file;
+    const filePath = file;
+    // Ordered Validation Step 1 & 2
+    (0, errors_1.validateConfig)(filePath, port);
+    (0, errors_1.acquireLock)(filePath);
     try {
         await jsonStore_1.JsonStore.load(filePath);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(message);
-        process.exit(1);
-        return;
+        // JsonStore.load handles its own printFatal internally, 
+        // but we catch to ensure we don't crash without formatting.
+        (0, errors_1.printFatal)('UNKNOWN', err.message);
     }
     try {
-        await (0, bootstrap_1.bootstrap)(port, {
+        await (0, bootstrap_1.bootstrap)(port, filePath, watch, {
             delayMs,
             corsOrigin: opts.corsOrigin,
             corsMethods: opts.corsMethods,
@@ -83,13 +148,18 @@ program
         });
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(`Failed to start server: ${message}`);
-        process.exit(1);
-        return;
+        // Bootstrap will handle EADDRINUSE internally, catching just in case.
+        (0, errors_1.printFatal)('UNKNOWN', err.message);
     }
-    if (opts.watch) {
+    if (watch) {
         startFileWatcher(filePath);
     }
+    const cleanup = () => {
+        if (watcher) {
+            watcher.close().catch(() => { });
+        }
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
 });
 program.parse(process.argv);

package/dist/server/app.js

@@ -7,6 +7,7 @@ exports.createApp = createApp;
 const cors_1 = __importDefault(require("cors"));
 const express_1 = __importDefault(require("express"));
 const dynamicRouter_1 = require("./routes/dynamicRouter");
+const logger_1 = require("./logger");
 const errorHandler = (err, _req, res, _next) => {
     if (res.headersSent) {
         return;
@@ -14,12 +15,6 @@ const errorHandler = (err, _req, res, _next) => {
     const message = err instanceof Error ? err.message : String(err);
     res.status(500).json({ error: "INTERNAL_SERVER_ERROR", message, statusCode: 500 });
 };
-function requestLoggingMiddleware(req, res, next) {
-    res.on("finish", () => {
-        console.log(`[${req.method}] ${req.path} - ${res.statusCode}`);
-    });
-    next();
-}
 function delayMiddleware(delayMs) {
     return (_req, _res, next) => {
         if (delayMs <= 0) {
@@ -37,7 +32,7 @@ function createApp(options) {
         credentials: options.corsCredentials || false,
     }));
     app.use(express_1.default.json());
-    app.use(requestLoggingMiddleware);
+    app.use(logger_1.requestLoggingMiddleware);
     app.use(delayMiddleware(options.delayMs));
     app.use("/", (0, dynamicRouter_1.buildDynamicRouter)());
     app.use(errorHandler);

package/dist/server/bootstrap.js

@@ -3,20 +3,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.bootstrap = bootstrap;
 const app_1 = require("./app");
 const jsonStore_1 = require("../store/jsonStore");
-async function bootstrap(port, appOptions) {
+const logger_1 = require("./logger");
+const errors_1 = require("../errors");
+async function bootstrap(port, file, watch, appOptions) {
     const app = (0, app_1.createApp)(appOptions);
     await new Promise((resolve, reject) => {
         const server = app.listen(port, () => {
             resolve();
         });
-        server.on("error", reject);
+        server.on("error", (e) => {
+            if (e.code === 'EADDRINUSE') {
+                (0, errors_1.printFatal)('PORT_IN_USE', `Port ${port} — ${e.message}`);
+            }
+            else {
+                (0, errors_1.printFatal)('UNKNOWN', e.message);
+            }
+            reject(e);
+        });
     });
-    const base = `http://localhost:${port}`;
-    console.log(`🚀 Server is running at ${base}`);
-    console.log("Read/write API: GET, POST, PUT, PATCH, DELETE are active for each resource below.\n");
-    for (const resource of Object.keys(jsonStore_1.JsonStore.getData())) {
-        console.log(`  ${resource}`);
-        console.log(`    GET    POST              ${base}/${resource}`);
-        console.log(`    GET    PUT   PATCH DELETE  ${base}/${resource}/:id`);
-    }
+    const resources = Object.keys(jsonStore_1.JsonStore.getData());
+    (0, logger_1.printStartupBanner)(file, port, watch, appOptions.delayMs, resources);
 }

package/dist/server/logger.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMethodBadge = getMethodBadge;
+exports.requestLoggingMiddleware = requestLoggingMiddleware;
+exports.getMonochromeBadge = getMonochromeBadge;
+exports.printStartupBanner = printStartupBanner;
+const picocolors_1 = __importDefault(require("picocolors"));
+const cli_wizard_1 = require("../cli-wizard");
+function getMethodBadge(method) {
+    const m = method.toUpperCase();
+    const padded = m.padEnd(6, ' ');
+    const inner = `[${padded}]`;
+    switch (m) {
+        case 'GET': return picocolors_1.default.bold(picocolors_1.default.cyan(inner));
+        case 'POST': return picocolors_1.default.bold(picocolors_1.default.green(inner));
+        case 'PUT': return picocolors_1.default.bold(picocolors_1.default.yellow(inner));
+        case 'PATCH': return picocolors_1.default.bold(picocolors_1.default.magenta(inner));
+        case 'DELETE': return picocolors_1.default.bold(picocolors_1.default.red(inner));
+        default: return picocolors_1.default.bold(picocolors_1.default.white(inner));
+    }
+}
+function requestLoggingMiddleware(req, res, next) {
+    const startMs = Date.now();
+    const start = new Date();
+    res.on("finish", () => {
+        const timeStr = start.toLocaleTimeString('en-US', { hour12: true });
+        const duration = Date.now() - startMs;
+        const badge = getMethodBadge(req.method);
+        let statusStr = String(res.statusCode);
+        if (res.statusCode >= 200 && res.statusCode < 300)
+            statusStr = picocolors_1.default.green(statusStr);
+        else if (res.statusCode >= 300 && res.statusCode < 400)
+            statusStr = picocolors_1.default.cyan(statusStr);
+        else if (res.statusCode >= 400 && res.statusCode < 500)
+            statusStr = picocolors_1.default.yellow(statusStr);
+        else if (res.statusCode >= 500)
+            statusStr = picocolors_1.default.red(statusStr);
+        const pathPadded = req.path.length > 20 ? req.path : req.path.padEnd(20, ' ');
+        console.log(`${picocolors_1.default.dim(`[${timeStr}]`)} ${badge} ${picocolors_1.default.white(pathPadded)} ${statusStr} ${picocolors_1.default.dim(`${duration}ms`)}`);
+    });
+    next();
+}
+function getMonochromeBadge(method) {
+    const m = method.toUpperCase();
+    const padded = m.padEnd(6, ' ');
+    return `[${padded}]`;
+}
+function printStartupBanner(file, port, isWatch, delayMs, resources) {
+    console.log('\n' + (0, cli_wizard_1.sectionHeader)('SERVER READY'));
+    console.log((0, cli_wizard_1.renderConfigPanel)({
+        file,
+        port: String(port),
+        delay: String(delayMs),
+        watch: isWatch
+    }) + '\n');
+    console.log((0, cli_wizard_1.sectionHeader)('AVAILABLE RESOURCES'));
+    const base = `http://localhost:${port}`;
+    const get = getMonochromeBadge('GET');
+    const post = getMonochromeBadge('POST');
+    const put = getMonochromeBadge('PUT');
+    const patch = getMonochromeBadge('PATCH');
+    const del = getMonochromeBadge('DELETE');
+    for (const resource of resources) {
+        console.log(picocolors_1.default.bold(picocolors_1.default.white(`■ /${resource}`)));
+        const methodsLeft1 = `  ${get}  ${post}`;
+        const methodsLeft2 = `  ${get}  ${put}  ${patch}  ${del}`;
+        // Align URLs at column 45
+        const pad1 = ' '.repeat(Math.max(1, 45 - (0, cli_wizard_1.stripAnsi)(methodsLeft1).length));
+        const pad2 = ' '.repeat(Math.max(1, 45 - (0, cli_wizard_1.stripAnsi)(methodsLeft2).length));
+        console.log(`${methodsLeft1}${pad1}${picocolors_1.default.white(`${base}/${resource}`)}`);
+        console.log(`${methodsLeft2}${pad2}${picocolors_1.default.white(`${base}/${resource}/:id`)}\n`);
+    }
+    console.log((0, cli_wizard_1.sectionHeader)('REQUEST LOGS'));
+    console.log(`${picocolors_1.default.green('✓')} ${picocolors_1.default.dim('Ready on')} ${picocolors_1.default.white(`${base}`)}\n`);
+}

package/dist/server/routes/dynamicRouter.js

@@ -109,7 +109,8 @@ function filterCollection(items, query) {
             else if (op === "like") {
                 if (actual === undefined || actual === null)
                     return false;
-                if (!String(actual).toLowerCase().includes(String(want).toLowerCase()))
+                const escaped = want.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                if (!new RegExp(escaped, 'i').test(String(actual)))
                     return false;
             }
         }
@@ -235,10 +236,23 @@ function buildDynamicRouter() {
             const collection = jsonStore_1.JsonStore.getData()[resource];
             const query = req.query;
             let rows = filterCollection(collection, query);
+            const total = rows.length;
+            res.setHeader("X-Total-Count", total);
             const pageInfo = parsePagination(query);
             if (pageInfo !== null) {
                 const start = (pageInfo.page - 1) * pageInfo.limit;
                 rows = rows.slice(start, start + pageInfo.limit);
+                const totalPages = Math.ceil(total / pageInfo.limit);
+                res.json({
+                    data: rows,
+                    pagination: {
+                        total,
+                        page: pageInfo.page,
+                        limit: pageInfo.limit,
+                        totalPages
+                    }
+                });
+                return;
             }
             res.json(rows);
         });

package/dist/store/jsonStore.js

@@ -1,78 +1,63 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JsonStore = void 0;
 const crypto_1 = require("crypto");
 const path_1 = require("path");
+const fs_1 = __importDefault(require("fs"));
 const promises_1 = require("fs/promises");
+const errors_1 = require("../errors");
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function parseJsonStorePayload(raw, filePath) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`Invalid JSON in "${filePath}": ${message}`);
-    }
-    if (!isPlainObject(parsed)) {
-        throw new Error(`JSON root in "${filePath}" must be a non-null object (got ${parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed}).`);
-    }
-    const data = {};
-    for (const [key, value] of Object.entries(parsed)) {
-        if (!Array.isArray(value)) {
-            throw new Error(`Invalid mock database shape in "${filePath}": property "${key}" must be an array.`);
-        }
-        data[key] = value;
-    }
-    return data;
-}
 class JsonStoreImpl {
     data = {};
     backingPath = null;
-    lockPath = null;
     /** Serializes concurrent save() calls so writes are not interleaved. */
     saveChain = Promise.resolve();
-    async load(filePath) {
-        const lockPath = filePath + ".zero-mock.lock";
+    async load(filePath, isReload = false) {
+        let raw;
         try {
-            await (0, promises_1.access)(lockPath);
-            console.warn(`[warn] Lock file found: "${lockPath}". ` +
-                `Another zero-mock process may be running on this file. ` +
-                `If not, delete the lock file and retry.`);
+            raw = await (0, promises_1.readFile)(filePath, "utf8");
         }
-        catch {
-            await (0, promises_1.writeFile)(lockPath, String(process.pid), "utf8");
-            this.lockPath = lockPath;
-            this._registerLockCleanup();
+        catch (err) {
+            if (isReload)
+                throw new Error(`Unreadable: ${err.message}`);
+            (0, errors_1.printFatal)('FILE_UNREADABLE', err.message);
         }
-        let raw;
+        let parsed;
         try {
-            raw = await (0, promises_1.readFile)(filePath, "utf8");
+            parsed = JSON.parse(raw);
         }
         catch (err) {
-            const code = err && typeof err === "object" && "code" in err ? String(err.code) : "";
-            const message = err instanceof Error ? err.message : String(err);
-            throw new Error(code
-                ? `Could not read JSON file "${filePath}" (${code}): ${message}`
-                : `Could not read JSON file "${filePath}": ${message}`);
+            if (isReload)
+                throw new Error(`Parse error: ${err.message}`);
+            (0, errors_1.printFatal)('JSON_INVALID', err.message);
         }
-        this.data = parseJsonStorePayload(raw, filePath);
-        this.backingPath = filePath;
-    }
-    _registerLockCleanup() {
-        const cleanup = () => {
-            if (this.lockPath) {
-                try {
-                    require("fs").unlinkSync(this.lockPath);
-                }
-                catch (_) { }
+        if (!isPlainObject(parsed)) {
+            const msg = `got ${parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed}`;
+            if (isReload)
+                throw new Error(`Root not an object (${msg})`);
+            (0, errors_1.printFatal)('JSON_NOT_OBJECT', msg);
+        }
+        const keys = Object.keys(parsed);
+        if (keys.length === 0) {
+            (0, errors_1.printError)('JSON_EMPTY');
+        }
+        const data = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (!Array.isArray(value)) {
+                const msg = `property "${key}" must be an array.`;
+                if (isReload)
+                    throw new Error(msg);
+                (0, errors_1.printFatal)('JSON_INVALID', msg);
             }
-        };
-        process.once("exit", cleanup);
-        process.once("SIGINT", () => { cleanup(); process.exit(130); });
-        process.once("SIGTERM", () => { cleanup(); process.exit(143); });
+            data[key] = value;
+        }
+        this.data = data;
+        this.backingPath = filePath;
     }
     getData() {
         return this.data;
@@ -88,14 +73,26 @@ class JsonStoreImpl {
         const run = async () => {
             const target = this.backingPath;
             const dir = (0, path_1.dirname)(target);
-            const tmp = (0, path_1.join)(dir, `.zero-mock-${(0, crypto_1.randomBytes)(8).toString("hex")}.tmp`);
+            const tmp = (0, path_1.join)(dir, `.zero-mock-tmp-${(0, crypto_1.randomBytes)(8).toString("hex")}.json`);
             const payload = `${JSON.stringify(this.data, null, 2)}\n`;
             try {
                 await (0, promises_1.writeFile)(tmp, payload, "utf8");
-                await (0, promises_1.rename)(tmp, target);
+                try {
+                    fs_1.default.renameSync(tmp, target);
+                }
+                catch (e) {
+                    if (e.code === 'EXDEV') {
+                        fs_1.default.copyFileSync(tmp, target);
+                        fs_1.default.unlinkSync(tmp);
+                    }
+                    else {
+                        throw e;
+                    }
+                }
             }
             catch (err) {
-                await (0, promises_1.unlink)(tmp).catch(() => { });
+                if (fs_1.default.existsSync(tmp))
+                    fs_1.default.unlinkSync(tmp);
                 const message = err instanceof Error ? err.message : String(err);
                 throw new Error(`Could not write JSON file "${target}": ${message}`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xirconsss/zero-mock",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Zero-config CLI that generates REST APIs from JSON files",
   "license": "MIT",
   "keywords": [
@@ -47,10 +47,13 @@
   },
   "homepage": "https://github.com/xircons/zero-mock#readme",
   "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.5",
     "express": "^4.21.2",
+    "gradient-string": "^3.0.0",
+    "picocolors": "^1.1.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
@@ -64,6 +67,7 @@
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/cors": "^2.8.17",
     "@types/express": "^4.17.21",
+    "@types/gradient-string": "^1.1.6",
     "@types/node": "^22.14.0",
     "@vitest/coverage-v8": "^2.1.9",
     "husky": "^9.1.7",

package/example/db.json

@@ -1,45 +0,0 @@
-{
-  "users": [
-    {
-      "id": 1,
-      "name": "Ada Lovelace",
-      "email": "ada@example.com",
-      "role": "admin"
-    },
-    {
-      "id": 2,
-      "name": "Grace Hopper",
-      "email": "grace@example.com",
-      "role": "editor"
-    },
-    {
-      "id": 3,
-      "name": "Margaret Hamilton",
-      "email": "margaret@example.com",
-      "role": "viewer"
-    }
-  ],
-  "posts": [
-    {
-      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
-      "title": "Shipping a mock API in minutes",
-      "body": "Point zero-mock at a JSON file and iterate on your UI without waiting on backend tickets.",
-      "userId": 1,
-      "published": true
-    },
-    {
-      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
-      "title": "Why atomic writes matter",
-      "body": "Your JSON file stays the source of truth—even when multiple tabs hit the API at once.",
-      "userId": 2,
-      "published": false
-    },
-    {
-      "id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
-      "title": "Frontend-first workflows",
-      "body": "Prototype with realistic CRUD, then swap the mock for a production API when you are ready.",
-      "userId": 1,
-      "published": true
-    }
-  ]
-}