@x12i/static-memorix-explorer-api 1.3.1 → 1.3.2

package/README.md

@@ -10,6 +10,27 @@ See [guides/demo-app.md](./guides/demo-app.md) for the full walkthrough.
 
 ## Quick start
 
+Install once, then run one command:
+
+```bash
+npm install --global @x12i/static-memorix-explorer-api
+memorix-explorer
+```
+
+Then open **http://localhost:5030/demo**. The command prints the Demo, API,
+Health, and JSON paths when it starts. No database or additional configuration
+is required.
+
+Useful options:
+
+```bash
+memorix-explorer --port 8080
+memorix-explorer --help
+memorix-explorer --version
+```
+
+### Run from this repository
+
 ```bash
 npm install
 npm run build
@@ -38,7 +59,7 @@ npx @x12i/static-memorix-explorer-api
 Or, after a global install:
 
 ```bash
-static-memorix-explorer-api --port 5030 --host 127.0.0.1
+memorix-explorer
 ```
 
 Override the port from the shell:
@@ -278,6 +299,12 @@ and `knowledgeId`.
 
 ## Release history
 
+### v1.3.2
+- Added the short `memorix-explorer` CLI command.
+- Added `--help`/`-h` and `--version`/`-v` commands.
+- Startup now prints clickable Demo, API, Health, and JSON locations.
+- Reworked Quick Start documentation around install-once, run-one-command use.
+
 ### v1.3.1
 - Rejected unsafe routing IDs, object types, and metadata keys before path use.
 - Changed malformed and empty JSON handling from silent fallback to explicit

package/dist/server.d.ts

@@ -5,6 +5,8 @@ export interface StartServerOptions {
     logger?: boolean;
     installSignalHandlers?: boolean;
 }
+export declare const CLI_HELP = "Memorix Explorer static server\n\nUsage:\n  memorix-explorer [options]\n\nOptions:\n  --port <number>  Port to listen on (default: 5030)\n  --host <address> Host to bind (default: 0.0.0.0)\n  -h, --help       Show this help\n  -v, --version    Show the installed version\n\nEnvironment:\n  MOCKS_DIR         Writable JSON fixture directory\n  MEMORIX_ORG_ID    Organization routing ID\n  MEMORIX_AGENT_ID  Agent/Catalox routing ID\n\nExample:\n  memorix-explorer --port 5030\n";
+export declare function getPackageVersion(): string;
 export declare function parseCliArgs(args: string[]): StartServerOptions;
 export declare function isCliEntrypoint(argvPath: string | undefined, moduleUrl: string): boolean;
 /** Build a loaded Fastify instance without opening a network port. */

package/dist/server.js

@@ -6,6 +6,29 @@ 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";
+export const CLI_HELP = `Memorix Explorer static server
+
+Usage:
+  memorix-explorer [options]
+
+Options:
+  --port <number>  Port to listen on (default: 5030)
+  --host <address> Host to bind (default: 0.0.0.0)
+  -h, --help       Show this help
+  -v, --version    Show the installed version
+
+Environment:
+  MOCKS_DIR         Writable JSON fixture directory
+  MEMORIX_ORG_ID    Organization routing ID
+  MEMORIX_AGENT_ID  Agent/Catalox routing ID
+
+Example:
+  memorix-explorer --port 5030
+`;
+export function getPackageVersion() {
+    const packageFile = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
+    return JSON.parse(fs.readFileSync(packageFile, "utf8")).version;
+}
 export function parseCliArgs(args) {
     const options = {};
     for (let index = 0; index < args.length; index++) {
@@ -70,9 +93,13 @@ export async function startServer(options = {}) {
     await app.listen({ port, host });
     const address = app.server.address();
     const boundPort = typeof address === "object" && address ? address.port : port;
+    const displayHost = host === "0.0.0.0" ? "localhost" : host;
     // eslint-disable-next-line no-console
-    console.log(`[mock-memorix-explorer-api] listening on ${host}:${boundPort}`);
-    console.log(`[mock-memorix-explorer-api] mocks dir: ${MOCKS_DIR}`);
+    console.log(`\nMemorix Explorer is ready`);
+    console.log(`  Demo:   http://${displayHost}:${boundPort}/demo`);
+    console.log(`  API:    http://${displayHost}:${boundPort}/api/explorer`);
+    console.log(`  Health: http://${displayHost}:${boundPort}/health`);
+    console.log(`  JSON:   ${MOCKS_DIR}\n`);
     if (options.installSignalHandlers ?? true) {
         const shutdown = async () => {
             console.log("\n[mock-memorix-explorer-api] flushing + shutting down");
@@ -87,9 +114,17 @@ export async function startServer(options = {}) {
 }
 const isCliEntry = isCliEntrypoint(process.argv[1], import.meta.url);
 if (isCliEntry) {
-    Promise.resolve().then(() => startServer(parseCliArgs(process.argv.slice(2)))).catch((err) => {
-        // eslint-disable-next-line no-console
-        console.error(err);
-        process.exit(1);
-    });
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(CLI_HELP);
+    }
+    else if (args.includes("--version") || args.includes("-v")) {
+        console.log(getPackageVersion());
+    }
+    else
+        Promise.resolve().then(() => startServer(parseCliArgs(args))).catch((err) => {
+            // eslint-disable-next-line no-console
+            console.error(err);
+            process.exit(1);
+        });
 }

package/guides/running-the-service.md

@@ -12,9 +12,9 @@ from in-memory state backed by JSON files on disk.
 npm install -g @x12i/static-memorix-explorer-api
 ```
 
-This makes the `mock-memorix-explorer-api` command available globally.
-The preferred command name is `static-memorix-explorer-api`; the older
-`mock-memorix-explorer-api` name remains as a compatibility alias.
+This makes the short `memorix-explorer` command available globally.
+`static-memorix-explorer-api` and `mock-memorix-explorer-api` remain available
+as compatibility aliases.
 
 ### From source (git clone)
 
@@ -45,11 +45,19 @@ iteration, but not suitable for distribution.
 ### As a global CLI
 
 ```bash
-static-memorix-explorer-api
+memorix-explorer
 ```
 
 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.
+mocks directory defaults to the bundled fixtures, and the CLI prints the URLs
+to open:
+
+```text
+Memorix Explorer is ready
+  Demo:   http://localhost:5030/demo
+  API:    http://localhost:5030/api/explorer
+  Health: http://localhost:5030/health
+```
 
 ### With `npx` (no global install)
 
@@ -61,8 +69,15 @@ Choose a port with a CLI option or environment variable. CLI options take
 precedence:
 
 ```bash
-static-memorix-explorer-api --port 5030 --host 127.0.0.1
-PORT=5030 HOST=127.0.0.1 static-memorix-explorer-api
+memorix-explorer --port 5030 --host 127.0.0.1
+PORT=5030 HOST=127.0.0.1 memorix-explorer
+```
+
+Built-in help and version output do not start the server:
+
+```bash
+memorix-explorer --help
+memorix-explorer --version
 ```
 
 ### From application code
@@ -111,7 +126,7 @@ containerized deployments, point it at a persistent application-owned volume
 rather than relying on the package's bundled seed directory:
 
 ```bash
-MOCKS_DIR=/var/lib/my-app/memorix-mocks static-memorix-explorer-api --port 5030
+MOCKS_DIR=/var/lib/my-app/memorix-mocks memorix-explorer --port 5030
 ```
 
 Configuration is resolved when the package is imported. In programmatic usage,
@@ -162,7 +177,7 @@ default.
 Set to `true` or `1` to enable:
 
 ```bash
-MEMORIX_EXPLORER_ENABLE_METADATA_WRITES=true mock-memorix-explorer-api
+MEMORIX_EXPLORER_ENABLE_METADATA_WRITES=true memorix-explorer
 ```
 
 ### Disk flush
@@ -180,7 +195,7 @@ MOCKS_DIR=/path/to/my/fixtures \
 MEMORIX_ORG_ID=neo \
 MEMORIX_AGENT_ID=neo-agent \
 MEMORIX_EXPLORER_ENABLE_METADATA_WRITES=true \
-mock-memorix-explorer-api
+memorix-explorer
 ```
 
 ## Health checks

package/guides/using-the-api.md

@@ -261,5 +261,5 @@ when the corresponding feature flag is not enabled. Set the environment
 variable to `true` or `1` to allow writes:
 
 ```bash
-MEMORIX_EXPLORER_ENABLE_METADATA_WRITES=true mock-memorix-explorer-api
+MEMORIX_EXPLORER_ENABLE_METADATA_WRITES=true memorix-explorer
 ```

package/package.json

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