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

package/README.md

@@ -49,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
@@ -319,6 +329,18 @@ and `knowledgeId`.
 
 ## Release history
 
+### v1.5.1
+- Replaced personal names in the bundled demo users with generic sample names.
+- Added regression coverage to keep personal identifiers out of generated demos.
+
+### 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

package/dist/cli.d.ts

@@ -4,11 +4,14 @@ export interface CliServerOptions {
     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 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

@@ -1,16 +1,20 @@
 #!/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)
@@ -110,6 +114,102 @@ export function createDemo(targetDir) {
 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);
@@ -122,19 +222,41 @@ export async function runCli(args) {
     if (args[0] === "create-demo") {
         const { targetDir } = parseCreateDemoArgs(args.slice(1));
         const created = createDemo(targetDir);
-        console.log(`\nDemo created at:\n  ${created}\n`);
+        const shown = displayPath(created);
+        console.log(`\nDemo created:\n  ${shown}\n`);
         console.log("Start the server with:");
-        console.log(`  memorix-explorer --mocks-dir ${quote(created)}\n`);
+        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");
-    await startServer({ port: options.port, host: options.host });
+    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])

package/guides/demo-app.md

@@ -219,9 +219,9 @@ Data files (under `mocks/data/`) hold the actual records.
 
 ```json
 [
-  { "recordId": "usr-1", "name": "Ami",    "role": "owner" },
-  { "recordId": "usr-2", "name": "Devran", "role": "engineer" },
-  { "recordId": "usr-3", "name": "Ilan",   "role": "growth" }
+  { "recordId": "usr-1", "name": "James",   "role": "owner" },
+  { "recordId": "usr-2", "name": "Emily",   "role": "engineer" },
+  { "recordId": "usr-3", "name": "Michael", "role": "growth" }
 ]
 ```
 

package/guides/running-the-service.md

@@ -71,11 +71,11 @@ memorix-explorer create-demo
 The command creates `./memorix-demo` and prints the exact next step:
 
 ```text
-Demo created at:
-  /your/current/directory/memorix-demo
+Demo created:
+  ./memorix-demo
 
 Start the server with:
-  memorix-explorer --mocks-dir "/your/current/directory/memorix-demo"
+  memorix-explorer --mocks-dir "./memorix-demo"
 
 Then open:
   http://localhost:5030/demo
@@ -92,6 +92,21 @@ 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/mocks/data/users/snapshots.json

@@ -1,5 +1,5 @@
 [
-  { "recordId": "usr-1", "name": "Ami", "role": "owner" },
-  { "recordId": "usr-2", "name": "Devran", "role": "engineer" },
-  { "recordId": "usr-3", "name": "Ilan", "role": "growth" }
+  { "recordId": "usr-1", "name": "James", "role": "owner" },
+  { "recordId": "usr-2", "name": "Emily", "role": "engineer" },
+  { "recordId": "usr-3", "name": "Michael", "role": "growth" }
 ]

package/package.json

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