@bilal-fazlani/mock-server 0.2.1

package/.next/standalone/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@bilal-fazlani/mock-server",
+  "version": "0.2.1",
+  "description": "A generic, catalog-driven HTTP API mock server — run via npx or Docker, no request-handling code required.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bilal-fazlani/mock-server.git"
+  },
+  "homepage": "https://github.com/bilal-fazlani/mock-server#readme",
+  "keywords": [
+    "mock",
+    "mock-server",
+    "api",
+    "testing",
+    "http"
+  ],
+  "bin": {
+    "mock-server": "bin/mock-server.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    ".next/standalone",
+    "bin"
+  ],
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "test": "vitest run",
+    "validate:catalog": "tsx scripts/validate-catalog.ts",
+    "prepack": "npm run build && cp -r .next/static .next/standalone/.next/static && cp -r public .next/standalone/public && node scripts/prepack-standalone.mjs"
+  },
+  "dependencies": {
+    "@tailwindcss/postcss": "^4.3.2",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "esbuild": "^0.25.12",
+    "lucide-react": "^1.23.0",
+    "mongodb": "^7.4.0",
+    "mongodb-memory-server": "^11.2.0",
+    "next": "16.2.10",
+    "next-themes": "^0.4.6",
+    "postcss": "^8.5.19",
+    "radix-ui": "^1.6.2",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.2",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.10",
+    "tsx": "^4.22.5",
+    "typescript": "^5",
+    "vitest": "^4.1.9"
+  }
+}

package/.next/standalone/public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

package/.next/standalone/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/.next/standalone/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/.next/standalone/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/.next/standalone/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/.next/standalone/release-please-config.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "package-name": "@bilal-fazlani/mock-server",
+      "include-v-in-tag": true,
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "changelog-sections": [
+        { "type": "feat", "section": "Features" },
+        { "type": "fix", "section": "Bug Fixes" },
+        { "type": "perf", "section": "Performance Improvements" },
+        { "type": "revert", "section": "Reverts" },
+        { "type": "docs", "section": "Documentation", "hidden": true },
+        { "type": "refactor", "section": "Code Refactoring", "hidden": true },
+        { "type": "test", "section": "Tests", "hidden": true },
+        { "type": "build", "section": "Build System", "hidden": true },
+        { "type": "ci", "section": "Continuous Integration", "hidden": true },
+        { "type": "chore", "section": "Chores", "hidden": true }
+      ]
+    }
+  }
+}

package/.next/standalone/server.js

@@ -0,0 +1,38 @@
+const path = require('path')
+
+const dir = path.join(__dirname)
+
+process.env.NODE_ENV = 'production'
+process.chdir(__dirname)
+
+const currentPort = parseInt(process.env.PORT, 10) || 3000
+const hostname = process.env.HOSTNAME || '0.0.0.0'
+
+let keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)
+const nextConfig = {"env":{},"webpack":null,"typescript":{"ignoreBuildErrors":false},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.ts","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"maximumResponseBody":50000000,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":false,"customCacheHandler":false},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{"serverFunctions":true,"browserToTerminal":"warn"},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/home/runner/work/mock-server/mock-server","cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"appNewScrollHandler":false,"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"cachedNavigations":false,"partialFallbacks":false,"dynamicOnHover":false,"varyParams":false,"prefetchInlining":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":3,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"strictRouteTypes":false,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":true,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"transitionIndicator":false,"gestureTransition":false,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":"warn","lockDistDir":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"turbopackFileSystemCacheForDev":true,"turbopackFileSystemCacheForBuild":false,"turbopackInferModuleSideEffects":true,"turbopackPluginRuntimeStrategy":"childProcesses","optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.ts","serverExternalPackages":["mongodb-memory-server","esbuild"],"outputFileTracingIncludes":{"**":["./node_modules/mongodb-memory-server/**"]},"turbopack":{"root":"/home/runner/work/mock-server/mock-server"},"distDirRoot":".next"}
+
+process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig)
+
+require('next')
+const { startServer } = require('next/dist/server/lib/start-server')
+
+if (
+  Number.isNaN(keepAliveTimeout) ||
+  !Number.isFinite(keepAliveTimeout) ||
+  keepAliveTimeout < 0
+) {
+  keepAliveTimeout = undefined
+}
+
+startServer({
+  dir,
+  isDev: false,
+  config: nextConfig,
+  hostname,
+  port: currentPort,
+  allowRetry: false,
+  keepAliveTimeout,
+}).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/.next/standalone/tests/testdata/fixtures/test-system/capture_assessment/default.json

@@ -0,0 +1 @@
+{ "status": 200, "body": { "ok": true } }

package/.next/standalone/tests/testdata/fixtures/test-system/customer_status/default.json

@@ -0,0 +1 @@
+{ "status": 200, "body": { "customerId": "{{path:customerId}}" } }

package/.next/standalone/tests/testdata/fixtures/test-system/dynamic_ep/default.json

@@ -0,0 +1,4 @@
+{
+  "status": 200,
+  "body": { "customerId": "{{$.customerId}}", "ok": true }
+}

package/.next/standalone/tests/testdata/fixtures/test-system/dynamic_ep/failure.json

@@ -0,0 +1 @@
+{ "status": 422, "body": { "ok": false } }

package/.next/standalone/tests/testdata/fixtures/test-system/hello_world/default.json

@@ -0,0 +1,4 @@
+{
+  "status": 200,
+  "body": { "customerId": "{{$.customerId}}", "date": "{{now:YYYYMMDD}}", "ok": true }
+}

package/.next/standalone/tests/testdata/fixtures/test-system/hello_world/failure.json

@@ -0,0 +1 @@
+{ "status": 500, "body": { "ok": false } }

package/.next/standalone/tests/testdata/fixtures/test-system/lookup/default.json

@@ -0,0 +1 @@
+{ "status": 200, "body": { "cid": "{{query:cid}}" } }

package/.next/standalone/tests/testdata/fixtures/test-system/mapped_callback/default.json

@@ -0,0 +1 @@
+{ "status": 200, "body": { "ok": true } }

package/.next/standalone/tests/testdata/fixtures/test-system/oauth_token/default.json

@@ -0,0 +1,7 @@
+{
+  "status": 200,
+  "body": {
+    "access_token": "mock-token",
+    "token_type": "Bearer"
+  }
+}

package/.next/standalone/tests/testdata/fixtures/test-system/oauth_token/expired.json

@@ -0,0 +1,6 @@
+{
+  "status": 401,
+  "body": {
+    "error": "expired_token"
+  }
+}

package/.next/standalone/tests/testdata/fixtures/test-system/schema_checked/bad_response.json

@@ -0,0 +1,4 @@
+{
+  "status": 200,
+  "body": { "customerId": "{{$.customerId}}", "ok": "{{$.customerId}}" }
+}

package/.next/standalone/tests/testdata/fixtures/test-system/schema_checked/default.json

@@ -0,0 +1,4 @@
+{
+  "status": 200,
+  "body": { "customerId": "{{$.customerId}}", "ok": true }
+}

package/.next/standalone/tests/testdata/fixtures/test-system/template_fail/default.json

@@ -0,0 +1 @@
+{ "status": 200, "body": { "x": "{{$.fieldThatWillNeverExist}}" } }

package/.next/standalone/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bilal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# Mock Server
+
+A data-driven HTTP mock server. You describe upstream endpoints as JSON files in a
+`catalog/` tree — no request-handling code — and the server routes incoming requests
+to canned responses. Which response a given caller gets is chosen per **profile**
+(a business ID such as `customer-123`) and per **scenario** (a named outcome like
+`default`, `frozen`, or `failure`), all editable from a built-in web UI. Any endpoint
+can also proxy through to a real upstream (`real` passthrough).
+
+Built with [Next.js](https://nextjs.org) and MongoDB.
+
+## Features
+
+- **Catalog-as-data** — add endpoints by creating directories and JSON files; the
+  engine loads them at startup.
+- **Profiles & scenarios** — pick, per caller, which scenario each endpoint returns;
+  picks can be ordered sequences served call-by-call.
+- **Profile-ID selectors** — resolve the caller from the request body, path, query,
+  or a Bearer token/JWT claim.
+- **Placeholders** — echo request values and timestamps into responses.
+- **Schema validation** — optional per-endpoint request/response JSON Schema checks.
+- **`real` passthrough** — proxy any endpoint to its configured live upstream.
+- **Request logs** — every request captured with a full decision trace, browsable in
+  the UI.
+
+## Quickstart
+
+Requirements: **Node.js 22+**. MongoDB is optional — if `MONGODB_CONNECTION_STRING`
+isn't set, an in-memory MongoDB starts automatically (data is ephemeral).
+
+```bash
+# via npx
+npx @bilal-fazlani/mock-server ./catalog
+
+# or via Docker
+docker run --rm -p 3000:3000 ghcr.io/bilal-fazlani/mock-server:latest
+```
+
+Mock endpoints answer at the **root** — an endpoint whose catalog `path` is
+`/hello/world` responds at `http://localhost:3000/hello/world`; the management UI
+is at `http://localhost:3000/ui`. The repo ships an example system
+(`catalog/hello-system/`) to call and edit:
+
+```bash
+curl -s -X POST http://localhost:3000/hello/world \
+  -H 'content-type: application/json' \
+  -d '{"customerId":"customer-123"}'
+```
+
+Full install (npx options, Docker, from-source), CI usage, the runtime-control
+API, and every environment variable are documented in the
+**[guide](docs/site/)** — see [Documentation](#documentation) to run it locally.
+
+## Scripts
+
+```bash
+npm run dev               # start the dev server
+npm run build             # production build
+npm start                 # run the production build
+npm test                  # run the test suite (Vitest)
+npm run lint              # lint
+npm run validate:catalog  # validate the catalog the way startup does
+```
+
+## Documentation
+
+The full guide lives under [`docs/site/`](docs/site/) (built with
+[Zensical](https://zensical.org)) and is the canonical source for install, Docker,
+CI, configuration, and every framework feature. It's organized into **Building
+mocks** (authoring the catalog) and **Driving mocks** (controlling a running
+server from the UI or the runtime-control API). Run it locally:
+
+```bash
+cd docs/site
+python3 -m venv .venv && .venv/bin/pip install zensical
+.venv/bin/zensical serve
+```
+
+Start with `docs/site/docs/index.md` for the mental model, or
+`docs/site/docs/get-started/install.md` to install and run.

package/bin/args.js

@@ -0,0 +1,42 @@
+'use strict'
+
+const HELP = `mock-server — run a mock API server from a catalog directory
+
+Usage:
+  mock-server [catalogPath] [options]
+
+Arguments:
+  catalogPath            Path to the catalog directory (default: ./catalog).
+                         Overrides the CATALOG_PATH environment variable.
+
+Options:
+  -p, --port <number>    Port to listen on (default: 3000, or $PORT).
+  -h, --help             Show this help and exit.
+  -v, --version          Print the version and exit.
+
+Environment:
+  CATALOG_PATH                 Catalog directory (relative or absolute).
+  MONGODB_CONNECTION_STRING    External MongoDB. If unset, an in-memory
+                               MongoDB is started automatically (ephemeral).
+`
+
+function parseArgs(argv) {
+  const opts = { catalogPath: undefined, port: undefined, help: false, version: false }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--help' || arg === '-h') {
+      opts.help = true
+    } else if (arg === '--version' || arg === '-v') {
+      opts.version = true
+    } else if (arg === '--port' || arg === '-p') {
+      opts.port = argv[++i]
+    } else if (arg.startsWith('--port=')) {
+      opts.port = arg.slice('--port='.length)
+    } else if (!arg.startsWith('-') && opts.catalogPath === undefined) {
+      opts.catalogPath = arg
+    }
+  }
+  return opts
+}
+
+module.exports = { parseArgs, HELP }

package/bin/mock-server.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+'use strict'
+
+const path = require('node:path')
+const fs = require('node:fs')
+const os = require('node:os')
+const { spawn } = require('node:child_process')
+const { parseArgs, HELP } = require('./args')
+
+const pkgRoot = path.join(__dirname, '..')
+const pkg = require(path.join(pkgRoot, 'package.json'))
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2))
+
+  if (opts.help) {
+    process.stdout.write(HELP)
+    return
+  }
+  if (opts.version) {
+    process.stdout.write(`${pkg.version}\n`)
+    return
+  }
+
+  // The launcher's cwd differs from the server's (we spawn inside the
+  // standalone dir), so always hand the server an ABSOLUTE catalog path,
+  // resolved against the user's real cwd. Precedence: positional arg > env.
+  const userCwd = process.cwd()
+  const rawCatalog = opts.catalogPath ?? process.env.CATALOG_PATH ?? 'catalog'
+
+  const env = { ...process.env }
+  env.CATALOG_PATH = path.resolve(userCwd, rawCatalog)
+  if (opts.port !== undefined) env.PORT = String(opts.port)
+
+  const standaloneDir = path.join(pkgRoot, '.next', 'standalone')
+  const serverJs = path.join(standaloneDir, 'server.js')
+  if (!fs.existsSync(serverJs)) {
+    process.stderr.write(
+      'mock-server: build output not found at .next/standalone/server.js. ' +
+        'This usually means the package was not built before publishing.\n',
+    )
+    process.exit(1)
+  }
+
+  const child = spawn(process.execPath, [serverJs], {
+    cwd: standaloneDir,
+    stdio: 'inherit',
+    env,
+  })
+
+  const forward = (signal) => {
+    if (!child.killed) child.kill(signal)
+  }
+  process.on('SIGINT', () => forward('SIGINT'))
+  process.on('SIGTERM', () => forward('SIGTERM'))
+
+  child.on('exit', (code, signal) => {
+    if (signal) process.exit(128 + (os.constants.signals[signal] ?? 0))
+    else process.exit(code ?? 0)
+  })
+}
+
+main()

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@bilal-fazlani/mock-server",
+  "version": "0.2.1",
+  "description": "A generic, catalog-driven HTTP API mock server — run via npx or Docker, no request-handling code required.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bilal-fazlani/mock-server.git"
+  },
+  "homepage": "https://github.com/bilal-fazlani/mock-server#readme",
+  "keywords": [
+    "mock",
+    "mock-server",
+    "api",
+    "testing",
+    "http"
+  ],
+  "bin": {
+    "mock-server": "bin/mock-server.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    ".next/standalone",
+    "bin"
+  ],
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "test": "vitest run",
+    "validate:catalog": "tsx scripts/validate-catalog.ts",
+    "prepack": "npm run build && cp -r .next/static .next/standalone/.next/static && cp -r public .next/standalone/public && node scripts/prepack-standalone.mjs"
+  },
+  "dependencies": {
+    "@tailwindcss/postcss": "^4.3.2",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "esbuild": "^0.25.12",
+    "lucide-react": "^1.23.0",
+    "mongodb": "^7.4.0",
+    "mongodb-memory-server": "^11.2.0",
+    "next": "16.2.10",
+    "next-themes": "^0.4.6",
+    "postcss": "^8.5.19",
+    "radix-ui": "^1.6.2",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.2",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.10",
+    "tsx": "^4.22.5",
+    "typescript": "^5",
+    "vitest": "^4.1.9"
+  }
+}