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

package/README.md

@@ -21,6 +21,26 @@ 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
@@ -299,6 +319,17 @@ 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.

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/guides/running-the-service.md

@@ -59,6 +59,39 @@ Memorix Explorer is ready
   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)
 
 ```bash

package/package.json

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