@x12i/static-memorix-explorer-api 1.3.2 → 1.5.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
@@ -29,6 +49,16 @@ memorix-explorer --help
 memorix-explorer --version
 ```
 
+Stop a server started by the CLI:
+
+```bash
+memorix-explorer stop                 # port 5030
+memorix-explorer stop --port 8080
+```
+
+If a requested port is occupied, the CLI explains these stop and alternate-port
+options instead of returning only `EADDRINUSE`.
+
 ### Run from this repository
 
 ```bash
@@ -299,6 +329,25 @@ and `knowledgeId`.
 
 ## Release history
 
+### v1.5.0
+- Added `memorix-explorer stop [--port <number>]` with safe managed-process
+  tracking and stale-PID cleanup.
+- Added actionable port-conflict output with stop and alternate-port commands.
+- Changed `create-demo` instructions to relative, user-owned paths such as
+  `./memorix-demo`; package or maintainer filesystem paths are never exposed.
+- Added lifecycle and occupied-port integration coverage.
+
+### 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,17 @@
+#!/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 stop [--port <number>]\n  memorix-explorer [options]\n\nCommands:\n  create-demo       Create a writable demo folder (default: ./memorix-demo)\n  stop              Stop a managed server (default port: 5030)\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 pidFileForPort(port: number): string;
+export declare function registerManagedServer(port: number): void;
+export declare function stopManagedServer(port: number): Promise<boolean>;
+export declare function runCli(args: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+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 stop [--port <number>]
+  memorix-explorer [options]
+
+Commands:
+  create-demo       Create a writable demo folder (default: ./memorix-demo)
+  stop              Stop a managed server (default port: 5030)
+
+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('"', '\\"')}"`;
+}
+function displayPath(value) {
+    const relative = path.relative(process.cwd(), value);
+    if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+        return `./${relative}`;
+    }
+    return value;
+}
+function parsePortOption(args) {
+    if (args.length === 0)
+        return 5030;
+    if (args.length !== 2 || args[0] !== "--port") {
+        throw new Error("Usage: memorix-explorer stop [--port <number>]");
+    }
+    const port = Number(args[1]);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error("--port must be an integer from 1 to 65535");
+    }
+    return port;
+}
+function runtimeDirectory() {
+    const user = typeof process.getuid === "function" ? String(process.getuid()) : os.userInfo().username;
+    return path.join(os.tmpdir(), `memorix-explorer-${user}`);
+}
+export function pidFileForPort(port) {
+    return path.join(runtimeDirectory(), `${port}.pid.json`);
+}
+function processCommand(pid) {
+    if (process.platform === "win32")
+        return "memorix-explorer";
+    try {
+        return execFileSync("ps", ["-p", String(pid), "-o", "command="], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function isRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function registerManagedServer(port) {
+    const file = pidFileForPort(port);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ pid: process.pid, port, startedAt: new Date().toISOString() }) + "\n");
+    process.once("exit", () => {
+        try {
+            const current = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (current.pid === process.pid)
+                fs.unlinkSync(file);
+        }
+        catch {
+            // Missing or replaced PID files need no cleanup.
+        }
+    });
+}
+export async function stopManagedServer(port) {
+    const file = pidFileForPort(port);
+    if (!fs.existsSync(file))
+        return false;
+    let pid;
+    try {
+        pid = Number(JSON.parse(fs.readFileSync(file, "utf8")).pid);
+    }
+    catch {
+        fs.unlinkSync(file);
+        return false;
+    }
+    if (!Number.isInteger(pid) || pid <= 0 || !isRunning(pid)) {
+        fs.unlinkSync(file);
+        return false;
+    }
+    const command = processCommand(pid);
+    if (process.platform !== "win32" && !command) {
+        throw new Error(`Cannot verify Memorix Explorer PID ${pid}; refusing to stop it`);
+    }
+    if (command && !/memorix-explorer|static-memorix-explorer-api|mock-memorix-explorer-api|dist\/cli\.js/.test(command)) {
+        throw new Error(`Refusing to stop PID ${pid}; it is not a Memorix Explorer process`);
+    }
+    process.kill(pid, "SIGTERM");
+    for (let attempt = 0; attempt < 50 && isRunning(pid); attempt++) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (isRunning(pid))
+        throw new Error(`Timed out while stopping Memorix Explorer PID ${pid}`);
+    if (fs.existsSync(file))
+        fs.unlinkSync(file);
+    return true;
+}
+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);
+        const shown = displayPath(created);
+        console.log(`\nDemo created:\n  ${shown}\n`);
+        console.log("Start the server with:");
+        console.log(`  memorix-explorer --mocks-dir ${quote(shown)}\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;
+    }
+    if (args[0] === "stop") {
+        const port = parsePortOption(args.slice(1));
+        const stopped = await stopManagedServer(port);
+        console.log(stopped
+            ? `Memorix Explorer on port ${port} stopped.`
+            : `No managed Memorix Explorer server found on port ${port}.`);
+        return;
+    }
+    const options = parseServerArgs(args);
+    if (options.mocksDir)
+        process.env.MOCKS_DIR = options.mocksDir;
+    const { startServer } = await import("./server.js");
+    const port = options.port ?? 5030;
+    try {
+        const app = await startServer({ port, host: options.host });
+        const address = app.server.address();
+        const boundPort = typeof address === "object" && address ? address.port : port;
+        registerManagedServer(boundPort);
+    }
+    catch (error) {
+        if (error.code === "EADDRINUSE") {
+            throw new Error(`Port ${port} is already in use. Run "memorix-explorer stop --port ${port}" ` +
+                `or choose another port with "--port ${port + 1}".`);
+        }
+        throw error;
+    }
+}
+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,54 @@ 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:
+  ./memorix-demo
+
+Start the server with:
+  memorix-explorer --mocks-dir "./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
+```
+
+### Stop the server
+
+Press Ctrl+C in the terminal where the server is running, or stop a managed
+instance from another terminal:
+
+```bash
+memorix-explorer stop
+memorix-explorer stop --port 8080
+```
+
+The CLI tracks only server processes it started and refuses to terminate a PID
+that does not identify as Memorix Explorer. Stale tracking files are removed
+automatically. If startup finds an occupied port, the error prints the matching
+stop command and suggests the next port.
+
 ### 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.5.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",