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

package/README.md

@@ -10,6 +10,47 @@ 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.
+
+To create an editable demo in your own directory instead of using the bundled
+read-only seeds:
+
+```bash
+memorix-explorer create-demo
+memorix-explorer --mocks-dir ./memorix-demo
+```
+
+The first command creates `./memorix-demo` with `demo.html`, seed data,
+metadata, write descriptors, and its own README. It refuses to overwrite an
+existing path. The second command serves that folder, and all UI create/edit/
+delete operations persist their routed JSON files inside it.
+
+Choose a different destination or port if needed:
+
+```bash
+memorix-explorer create-demo --dir ./my-project-fixtures
+memorix-explorer --mocks-dir ./my-project-fixtures --port 8080
+```
+
+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 +79,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 +319,23 @@ and `knowledgeId`.
 
 ## Release history
 
+### v1.4.0
+- Added `memorix-explorer create-demo` to create a user-owned, writable demo.
+- Added `--dir` for the generated demo destination and `--mocks-dir` for
+  serving any fixture directory directly from the CLI.
+- Generated demos include UI, metadata, seed data, write descriptors, and a
+  local usage README.
+- Demo creation is atomic, refuses overwrites, and excludes routed state that
+  may have been generated inside a previously used global installation.
+- Installed CLI aliases now use a configuration-first launcher so fixture paths
+  are resolved before the server loads.
+
+### 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/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+export interface CliServerOptions {
+    port?: number;
+    host?: string;
+    mocksDir?: string;
+}
+export declare const CLI_HELP = "Memorix Explorer static server\n\nUsage:\n  memorix-explorer create-demo [--dir <path>]\n  memorix-explorer [options]\n\nCommands:\n  create-demo       Create a writable demo folder (default: ./memorix-demo)\n\nServer options:\n  --port <number>   Port to listen on (default: 5030)\n  --host <address>  Host to bind (default: 0.0.0.0)\n  --mocks-dir <path> JSON fixture directory\n  -h, --help        Show this help\n  -v, --version     Show the installed version\n\nQuick start:\n  memorix-explorer create-demo\n  memorix-explorer --mocks-dir ./memorix-demo\n";
+export declare function getPackageVersion(): string;
+export declare function parseServerArgs(args: string[]): CliServerOptions;
+export declare function parseCreateDemoArgs(args: string[]): {
+    targetDir: string;
+};
+export declare function createDemo(targetDir: string): string;
+export declare function runCli(args: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const CLI_HELP = `Memorix Explorer static server
+
+Usage:
+  memorix-explorer create-demo [--dir <path>]
+  memorix-explorer [options]
+
+Commands:
+  create-demo       Create a writable demo folder (default: ./memorix-demo)
+
+Server options:
+  --port <number>   Port to listen on (default: 5030)
+  --host <address>  Host to bind (default: 0.0.0.0)
+  --mocks-dir <path> JSON fixture directory
+  -h, --help        Show this help
+  -v, --version     Show the installed version
+
+Quick start:
+  memorix-explorer create-demo
+  memorix-explorer --mocks-dir ./memorix-demo
+`;
+function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+export function getPackageVersion() {
+    return JSON.parse(fs.readFileSync(path.join(packageRoot(), "package.json"), "utf8")).version;
+}
+export function parseServerArgs(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--port") {
+            const raw = args[++index];
+            const port = Number(raw);
+            if (!raw || !Number.isInteger(port) || port < 0 || port > 65535) {
+                throw new Error("--port must be an integer from 0 to 65535");
+            }
+            options.port = port;
+        }
+        else if (arg === "--host") {
+            const host = args[++index];
+            if (!host)
+                throw new Error("--host requires a value");
+            options.host = host;
+        }
+        else if (arg === "--mocks-dir") {
+            const mocksDir = args[++index];
+            if (!mocksDir)
+                throw new Error("--mocks-dir requires a path");
+            options.mocksDir = path.resolve(mocksDir);
+        }
+        else {
+            throw new Error(`Unknown CLI argument: ${arg}`);
+        }
+    }
+    return options;
+}
+export function parseCreateDemoArgs(args) {
+    let targetDir = path.resolve("memorix-demo");
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--dir") {
+            const value = args[++index];
+            if (!value)
+                throw new Error("--dir requires a path");
+            targetDir = path.resolve(value);
+        }
+        else {
+            throw new Error(`Unknown create-demo argument: ${arg}`);
+        }
+    }
+    return { targetDir };
+}
+export function createDemo(targetDir) {
+    const resolved = path.resolve(targetDir);
+    if (fs.existsSync(resolved)) {
+        throw new Error(`Refusing to overwrite existing path: ${resolved}`);
+    }
+    const bundledMocks = path.join(packageRoot(), "mocks");
+    if (!fs.existsSync(bundledMocks)) {
+        throw new Error(`Bundled demo fixtures not found: ${bundledMocks}`);
+    }
+    const temporary = `${resolved}.creating-${randomUUID()}`;
+    try {
+        fs.cpSync(bundledMocks, temporary, {
+            recursive: true,
+            errorOnExist: true,
+            force: false,
+            // A globally installed package may already have routed runtime files.
+            // Copy only pristine bundled seeds, never another user's generated state.
+            filter: (source) => !path.basename(source).includes("--"),
+        });
+        fs.writeFileSync(path.join(temporary, "README.md"), `# Memorix Explorer demo\n\n` +
+            `Start this demo from this directory:\n\n` +
+            "```bash\nmemorix-explorer --mocks-dir . --port 5030\n```\n\n" +
+            `Then open http://localhost:5030/demo.\n\n` +
+            `Create, edit, and delete operations update the routed JSON files here.\n`, "utf8");
+        fs.renameSync(temporary, resolved);
+    }
+    catch (error) {
+        fs.rmSync(temporary, { recursive: true, force: true });
+        throw error;
+    }
+    return resolved;
+}
+function quote(value) {
+    return `"${value.replaceAll('"', '\\"')}"`;
+}
+export async function runCli(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(CLI_HELP);
+        return;
+    }
+    if (args.includes("--version") || args.includes("-v")) {
+        console.log(getPackageVersion());
+        return;
+    }
+    if (args[0] === "create-demo") {
+        const { targetDir } = parseCreateDemoArgs(args.slice(1));
+        const created = createDemo(targetDir);
+        console.log(`\nDemo created at:\n  ${created}\n`);
+        console.log("Start the server with:");
+        console.log(`  memorix-explorer --mocks-dir ${quote(created)}\n`);
+        console.log("Then open:");
+        console.log("  http://localhost:5030/demo\n");
+        console.log("Create, edit, and delete operations will update JSON files in that folder.");
+        return;
+    }
+    const options = parseServerArgs(args);
+    if (options.mocksDir)
+        process.env.MOCKS_DIR = options.mocksDir;
+    const { startServer } = await import("./server.js");
+    await startServer({ port: options.port, host: options.host });
+}
+function isCliEntrypoint() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return fs.realpathSync(path.resolve(process.argv[1])) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isCliEntrypoint()) {
+    runCli(process.argv.slice(2)).catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    });
+}

package/dist/engine/lists.d.ts

@@ -11,7 +11,7 @@ export declare function executeListDescriptor(desc: ListDescriptor, params?: Exp
 export declare function suggestListExtensions(entityName: string): {
     entityName: string;
     suggestions: {
-        contentType: "events" | "memory" | "analysis" | "decisions";
+        contentType: "analysis" | "decisions" | "events" | "memory";
         collection: string;
         suggestion: string;
     }[];

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,52 @@ 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
+```
+
+### Create a writable demo
+
+The bundled fixtures may live inside a global npm installation. Create a
+user-owned copy before experimenting with create/edit/delete:
+
+```bash
+memorix-explorer create-demo
+```
+
+The command creates `./memorix-demo` and prints the exact next step:
+
+```text
+Demo created at:
+  /your/current/directory/memorix-demo
+
+Start the server with:
+  memorix-explorer --mocks-dir "/your/current/directory/memorix-demo"
+
+Then open:
+  http://localhost:5030/demo
+```
+
+The generated directory contains `demo.html`, `data/`, `metadata/`, and a
+README. It is safe to edit and suitable for source control. The command refuses
+to overwrite an existing file or directory.
+
+Use a custom folder or port:
+
+```bash
+memorix-explorer create-demo --dir ./fixtures
+memorix-explorer --mocks-dir ./fixtures --port 8080
+```
 
 ### With `npx` (no global install)
 
@@ -61,8 +102,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 +159,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 +210,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 +228,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.4.0",
   "description": "Static mock server providing full API parity for the Memorix Explorer API.",
   "type": "module",
   "main": "dist/server.js",
@@ -15,13 +15,14 @@
     }
   },
   "bin": {
-    "static-memorix-explorer-api": "dist/server.js",
-    "mock-memorix-explorer-api": "dist/server.js"
+    "memorix-explorer": "dist/cli.js",
+    "static-memorix-explorer-api": "dist/cli.js",
+    "mock-memorix-explorer-api": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "start": "node dist/server.js",
-    "dev": "node --experimental-strip-types server.ts",
+    "start": "node dist/cli.js",
+    "dev": "node --experimental-strip-types cli.ts",
     "test": "npm run build && node --test tests/*.test.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build",