@x12i/static-memorix-explorer-api 1.1.0 → 1.1.1

package/README.md

@@ -13,20 +13,57 @@ See [guides/demo-app.md](./guides/demo-app.md) for the full walkthrough.
 ```bash
 npm install
 npm run build
-npm start                 # listens on :4300 (PORT / HOST / MOCKS_DIR env-overridable)
+npm start                 # listens on :5030 (PORT / HOST / MOCKS_DIR env-overridable)
 # dev (no build): npm run dev
 
 # open the demo UI in your browser
-open http://localhost:4300/demo
+open http://localhost:5030/demo
 ```
 
 Health:
 
 ```bash
-curl localhost:4300/health
-curl "localhost:4300/api/explorer/health?includeInventory=1"
+curl localhost:5030/health
+curl "localhost:5030/api/explorer/health?includeInventory=1"
 ```
 
+## Run from CLI or code
+
+Installed CLI, using the default port `5030`:
+
+```bash
+npx @x12i/static-memorix-explorer-api
+```
+
+Override the port from the shell:
+
+```bash
+PORT=8080 npx @x12i/static-memorix-explorer-api
+```
+
+Start it programmatically (explicit options take precedence over environment
+defaults):
+
+```js
+import { startServer } from "@x12i/static-memorix-explorer-api";
+
+const app = await startServer({ port: 5030, host: "127.0.0.1" });
+// await app.close();
+```
+
+For code-level tests without binding a port:
+
+```js
+import { buildServer } from "@x12i/static-memorix-explorer-api";
+
+const app = await buildServer();
+const response = await app.inject({ method: "GET", url: "/health" });
+await app.close();
+```
+
+See [guides/running-the-service.md](./guides/running-the-service.md) for all
+CLI, environment, lifecycle, and programmatic examples.
+
 ## Architecture
 
 ```
@@ -139,7 +176,7 @@ Full implementation walkthrough: [guides/demo-app.md](./guides/demo-app.md).
 
 | Var | Default | Notes |
 |-----|---------|-------|
-| `PORT` | `4300` | Listen port |
+| `PORT` | `5030` | Listen port |
 | `HOST` | `0.0.0.0` | Listen host |
 | `MOCKS_DIR` | `<project>/mocks` | Fixture root |
 | `DISK_FLUSH_DEBOUNCE_MS` | `300` | Debounce before disk flush |
@@ -204,6 +241,12 @@ and `knowledgeId`.
 
 ## Release history
 
+### v1.1.1
+- Changed the default listen port from `4300` to `5030`.
+- Added safe programmatic APIs: `buildServer()` and `startServer(options)`.
+- Importing the package no longer starts a listener as a side effect.
+- Added CLI, environment override, programmatic startup, and injected-test examples.
+
 ### v1.1.0
 - **Added**: `delete` operation to the write engine
   (`POST /records/write` body `operation:"delete"`).

package/dist/config.js

@@ -8,7 +8,7 @@ export const MOCKS_DIR = process.env.MOCKS_DIR
     : path.resolve(ROOT_DIR, "..", "mocks");
 export const METADATA_DIR = path.join(MOCKS_DIR, "metadata");
 export const DATA_DIR = path.join(MOCKS_DIR, "data");
-export const PORT = Number(process.env.PORT || 4300);
+export const PORT = Number(process.env.PORT || 5030);
 export const HOST = process.env.HOST || "0.0.0.0";
 export const DISK_FLUSH_DEBOUNCE_MS = Number(process.env.DISK_FLUSH_DEBOUNCE_MS || 300);
 // ---------------------------------------------------------------------------

package/dist/server.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 import Fastify from "fastify";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { store } from "./storage/InMemoryStore.js";
 import { registerRoutes } from "./routes/index.js";
 import { PORT, HOST, MOCKS_DIR } from "./config.js";
-async function main() {
-    const app = Fastify({ logger: false });
+/** Build a loaded Fastify instance without opening a network port. */
+export async function buildServer(options = {}) {
+    const app = Fastify({ logger: options.logger ?? false });
     // Global error handler matching predictable error shapes.
     app.setErrorHandler((error, _request, reply) => {
         const normalized = error instanceof Error
@@ -20,22 +23,36 @@ async function main() {
     });
     await store.load();
     await registerRoutes(app);
-    const port = Number(process.env.PORT || PORT);
-    await app.listen({ port, host: HOST });
+    return app;
+}
+/** Build and listen. Options override PORT/HOST environment configuration. */
+export async function startServer(options = {}) {
+    const app = await buildServer(options);
+    const port = options.port ?? PORT;
+    const host = options.host ?? HOST;
+    await app.listen({ port, host });
     // eslint-disable-next-line no-console
-    console.log(`[mock-memorix-explorer-api] listening on ${HOST}:${port}`);
+    console.log(`[mock-memorix-explorer-api] listening on ${host}:${port}`);
     console.log(`[mock-memorix-explorer-api] mocks dir: ${MOCKS_DIR}`);
-    const shutdown = async () => {
-        console.log("\n[mock-memorix-explorer-api] flushing + shutting down");
-        await store.flushAll();
-        await app.close();
-        process.exit(0);
-    };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
+    if (options.installSignalHandlers ?? true) {
+        const shutdown = async () => {
+            console.log("\n[mock-memorix-explorer-api] flushing + shutting down");
+            await store.flushAll();
+            await app.close();
+            process.exit(0);
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+    }
+    return app;
+}
+const isCliEntry = process.argv[1]
+    ? path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+    : false;
+if (isCliEntry) {
+    startServer().catch((err) => {
+        // eslint-disable-next-line no-console
+        console.error(err);
+        process.exit(1);
+    });
 }
-main().catch((err) => {
-    // eslint-disable-next-line no-console
-    console.error(err);
-    process.exit(1);
-});

package/guides/demo-app.md

@@ -17,7 +17,7 @@ calls.
 ```bash
 npm run build
 npm start
-# open http://localhost:4300/demo
+# open http://localhost:5030/demo
 ```
 
 Every mutation you make in the UI is persisted back to `mocks/data/**/*.json`
@@ -454,23 +454,23 @@ A 30-second smoke test, runnable from the repo root:
 npm run build && npm start &
 
 # 2. Read
-curl -s "localhost:4300/api/explorer/records/collection?entityName=users&limit=10"
+curl -s "localhost:5030/api/explorer/records/collection?entityName=users&limit=10"
 
 # 3. Create
-curl -s -X POST localhost:4300/api/explorer/records/write \
+curl -s -X POST localhost:5030/api/explorer/records/write \
   -H "Content-Type: application/json" \
   -d '{"writeDescriptorId":"product-task-write","operation":"add","input":{"recordId":"t-smoke-1","title":"Smoke","area":"product","status":"todo","priority":"normal"}}'
 
 # 4. Update (partial)
-curl -s -X POST localhost:4300/api/explorer/records/write \
+curl -s -X POST localhost:5030/api/explorer/records/write \
   -H "Content-Type: application/json" \
   -d '{"writeDescriptorId":"product-task-write","operation":"upsert","input":{"recordId":"t-smoke-1","status":"doing"}}'
 
 # 5. Delete
-curl -s -X DELETE "localhost:4300/api/explorer/records/item?entityName=product&recordId=t-smoke-1&writeDescriptorId=product-task-write"
+curl -s -X DELETE "localhost:5030/api/explorer/records/item?entityName=product&recordId=t-smoke-1&writeDescriptorId=product-task-write"
 
 # 6. Open the UI
-open http://localhost:4300/demo
+open http://localhost:5030/demo
 ```
 
 ---

package/guides/running-the-service.md

@@ -9,7 +9,7 @@ from in-memory state backed by JSON files on disk.
 ### From npm (global)
 
 ```bash
-npm install -g x12i/static-memorix-explorer-api
+npm install -g @x12i/static-memorix-explorer-api
 ```
 
 This makes the `mock-memorix-explorer-api` command available globally.
@@ -49,6 +49,41 @@ mock-memorix-explorer-api
 After `npm install -g`, the CLI starts the server with default settings. The
 mocks directory defaults to a `mocks/` folder relative to the installed package.
 
+### With `npx` (no global install)
+
+```bash
+npx @x12i/static-memorix-explorer-api
+```
+
+### From application code
+
+Importing the package does not open a port. Call `startServer()` explicitly:
+
+```js
+import { startServer } from "@x12i/static-memorix-explorer-api";
+
+const app = await startServer({
+  port: 5030,
+  host: "127.0.0.1",
+  installSignalHandlers: false,
+});
+
+// Later, for example during test teardown:
+await app.close();
+```
+
+For tests that do not need a real TCP listener, build the Fastify app and use
+its injection API:
+
+```js
+import { buildServer } from "@x12i/static-memorix-explorer-api";
+
+const app = await buildServer();
+const response = await app.inject({ method: "GET", url: "/health" });
+console.log(response.json()); // { ok: true }
+await app.close();
+```
+
 ## Configuration
 
 All configuration is via environment variables. Defaults work out of the box.
@@ -57,7 +92,7 @@ All configuration is via environment variables. Defaults work out of the box.
 
 | Variable  | Default     | Description                    |
 | --------- | ----------- | ------------------------------ |
-| `PORT`    | `4300`      | HTTP listen port               |
+| `PORT`    | `5030`      | HTTP listen port               |
 | `HOST`    | `0.0.0.0`   | HTTP listen host               |
 | `MOCKS_DIR` | `<project>/mocks` | Root directory for JSON fixtures |
 
@@ -117,10 +152,10 @@ mock-memorix-explorer-api
 Once running, verify the server is up:
 
 ```bash
-curl localhost:4300/health
+curl localhost:5030/health
 # {"ok":true}
 
-curl "localhost:4300/api/explorer/health?includeInventory=1"
+curl "localhost:5030/api/explorer/health?includeInventory=1"
 # {"ok":true,"mongoUriConfigured":true,"discoverySample":["assets","findings","memory"],...}
 ```
 

package/guides/using-the-api.md

@@ -3,7 +3,7 @@
 The mock server exposes the full Memorix Explorer API under `/api/explorer/`.
 All responses are JSON. Errors follow the shape `{ ok: false, error: "..." }`.
 
-Base URL defaults to `http://localhost:4300`.
+Base URL defaults to `http://localhost:5030`.
 
 ## Endpoints
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/static-memorix-explorer-api",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Static mock server providing full API parity for the Memorix Explorer API.",
   "type": "module",
   "main": "dist/server.js",