@x12i/static-memorix 2.0.0

package/dist/cli.js

@@ -0,0 +1,278 @@
+#!/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:
+  static-memorix create-demo [--dir <path>]
+  static-memorix stop [--port <number>]
+  static-memorix [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:
+  static-memorix create-demo
+  static-memorix --mocks-dir ./memorix-demo
+
+("memorix-explorer" remains available as a short alias for this command.)
+`;
+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|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/config.d.ts

@@ -0,0 +1,39 @@
+export declare const ROOT_DIR: string;
+export declare const MOCKS_DIR: string;
+export declare const METADATA_DIR: string;
+export declare const DATA_DIR: string;
+export declare const PORT: number;
+export declare const HOST: string;
+export declare const DISK_FLUSH_DEBOUNCE_MS: number;
+export declare function validateRouteId(value: string, variableName?: string): string;
+export declare const MEMORIX_ORG_ID: string;
+export declare const MEMORIX_AGENT_ID: string;
+export declare const MEMORIX_DEPLOYMENT_PROFILE: string;
+/**
+ * Construct the router string the frontend expects.
+ * e.g. "neo-memorix-entities + neo-memorix-events" for MEMORIX_ORG_ID=neo
+ */
+export declare function buildMemorixDbString(): string;
+/**
+ * Construct the agent-scoped Catalox DB name.
+ * e.g. "ebooks-memorix-catalox"
+ */
+export declare function buildCataloxDbString(): string;
+/**
+ * Files emulate routed databases by using the resolved database name as a
+ * prefix. The `--` separator is reserved for routing and must not be used in
+ * an unprefixed fixture basename.
+ */
+export declare function buildDataFilePrefix(contentType: string): string;
+export declare function buildMetadataFilePrefix(): string;
+export declare function prefixedJsonFilename(prefix: string, basename: string): string;
+export declare const FLAGS: {
+    METADATA_WRITES: boolean;
+    PIPELINE_WRITES: boolean;
+    REGISTRY_WRITES: boolean;
+};
+export declare function metadataWritesEnabled(): boolean;
+export declare function pipelineWritesEnabled(): boolean;
+export declare function registryWritesEnabled(): boolean;
+export declare function metadataPath(...segments: string[]): string;
+export declare function dataPath(...segments: string[]): string;

package/dist/config.js

@@ -0,0 +1,109 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export const ROOT_DIR = path.resolve(__dirname);
+export const MOCKS_DIR = process.env.MOCKS_DIR
+    ? path.resolve(process.env.MOCKS_DIR)
+    : path.resolve(ROOT_DIR, "..", "mocks");
+export const METADATA_DIR = path.join(MOCKS_DIR, "metadata");
+export const DATA_DIR = path.join(MOCKS_DIR, "data");
+export const PORT = Number(process.env.PORT || 5030);
+export const HOST = process.env.HOST || "0.0.0.0";
+export const DISK_FLUSH_DEBOUNCE_MS = Number(process.env.DISK_FLUSH_DEBOUNCE_MS || 300);
+// ---------------------------------------------------------------------------
+// DB Router Simulation (@x12i/memorix-db-router)
+// The mock does not connect to MongoDB, but it must convince the frontend that
+// it is talking to the routed tenant databases.
+// ---------------------------------------------------------------------------
+function resolveOrgId() {
+    if ((process.env.MEMORIX_DEPLOYMENT_PROFILE || "").toLowerCase() === "ebook") {
+        return "ebooks";
+    }
+    return validateRouteId(process.env.MEMORIX_ORG_ID || "memorix", "MEMORIX_ORG_ID");
+}
+function resolveAgentId() {
+    if ((process.env.MEMORIX_DEPLOYMENT_PROFILE || "").toLowerCase() === "ebook") {
+        return "ebooks";
+    }
+    return validateRouteId(process.env.MEMORIX_AGENT_ID || "default-agent", "MEMORIX_AGENT_ID");
+}
+export function validateRouteId(value, variableName = "route ID") {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) ||
+        value.includes("--") ||
+        value === "." ||
+        value === "..") {
+        throw Object.assign(new Error(`${variableName} must contain only letters, numbers, dot, underscore, or hyphen; ` +
+            `it must not contain path separators or the reserved "--" delimiter`), { statusCode: 400 });
+    }
+    return value;
+}
+export const MEMORIX_ORG_ID = resolveOrgId();
+export const MEMORIX_AGENT_ID = resolveAgentId();
+export const MEMORIX_DEPLOYMENT_PROFILE = process.env.MEMORIX_DEPLOYMENT_PROFILE || "default";
+/**
+ * Construct the router string the frontend expects.
+ * e.g. "neo-memorix-entities + neo-memorix-events" for MEMORIX_ORG_ID=neo
+ */
+export function buildMemorixDbString() {
+    const org = MEMORIX_ORG_ID;
+    return `${org}-memorix-entities + ${org}-memorix-events`;
+}
+/**
+ * Construct the agent-scoped Catalox DB name.
+ * e.g. "ebooks-memorix-catalox"
+ */
+export function buildCataloxDbString() {
+    return `${MEMORIX_AGENT_ID}-memorix-catalox`;
+}
+/**
+ * Files emulate routed databases by using the resolved database name as a
+ * prefix. The `--` separator is reserved for routing and must not be used in
+ * an unprefixed fixture basename.
+ */
+export function buildDataFilePrefix(contentType) {
+    if (contentType === "events")
+        return `${MEMORIX_ORG_ID}-memorix-events`;
+    if (contentType === "memory")
+        return buildCataloxDbString();
+    return `${MEMORIX_ORG_ID}-memorix-entities`;
+}
+export function buildMetadataFilePrefix() {
+    return buildCataloxDbString();
+}
+export function prefixedJsonFilename(prefix, basename) {
+    validateRouteId(prefix, "file routing prefix");
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(basename) || basename.includes("--")) {
+        throw Object.assign(new Error(`Unsafe JSON fixture basename: ${basename}`), {
+            statusCode: 400,
+        });
+    }
+    return `${prefix}--${basename}.json`;
+}
+// ---------------------------------------------------------------------------
+// Feature Flag Enforcement
+// ---------------------------------------------------------------------------
+function flagEnabled(name) {
+    const v = process.env[name];
+    return v === "1" || v === "true";
+}
+export const FLAGS = {
+    METADATA_WRITES: flagEnabled("MEMORIX_EXPLORER_ENABLE_METADATA_WRITES"),
+    PIPELINE_WRITES: flagEnabled("MEMORIX_EXPLORER_ENABLE_PIPELINE_WRITES"),
+    REGISTRY_WRITES: flagEnabled("MEMORIX_EXPLORER_ENABLE_REGISTRY_WRITES"),
+};
+export function metadataWritesEnabled() {
+    return FLAGS.METADATA_WRITES;
+}
+export function pipelineWritesEnabled() {
+    return FLAGS.PIPELINE_WRITES;
+}
+export function registryWritesEnabled() {
+    return FLAGS.REGISTRY_WRITES;
+}
+export function metadataPath(...segments) {
+    return path.join(METADATA_DIR, ...segments);
+}
+export function dataPath(...segments) {
+    return path.join(DATA_DIR, ...segments);
+}

package/dist/engine/aliases.d.ts

@@ -0,0 +1,32 @@
+import type { IncludeFlag } from "../types.js";
+/**
+ * Storage Alias Translation Map
+ * Client API key -> storage property / fallback.
+ */
+export interface AliasEntry {
+    clientKey: string;
+    storageProp: string;
+    fallbacks: string[];
+}
+export declare const STORAGE_ALIASES: Record<string, AliasEntry>;
+/**
+ * Resolve a normalized associated bucket from a raw document.
+ * Strips raw `associated*` fields and reconstructs the `associated` bucket
+ * using the alias map. Custom associated properties follow the pattern
+ * associated{Custom}.
+ */
+export declare function buildAssociatedBucket(rawDoc: Record<string, unknown>): {
+    associated: Record<string, unknown>;
+    strippedDoc: Record<string, unknown>;
+    properties: Array<{
+        propertyName: string;
+        source: string;
+        count: number;
+    }>;
+};
+export declare function aliasStorageToClient(storageKey: string): string;
+export declare function aliasClientToStorage(clientKey: string): {
+    primary: string;
+    fallbacks: string[];
+};
+export declare function resolveInclude(include?: string | string[]): Set<IncludeFlag> | null;

package/dist/engine/aliases.js

@@ -0,0 +1,74 @@
+export const STORAGE_ALIASES = {
+    data: {
+        clientKey: "data",
+        storageProp: "doc.associatedData",
+        fallbacks: ["associatedData"],
+    },
+    discovery: {
+        clientKey: "discovery",
+        storageProp: "doc.associatedInferred or doc.associatedDiscovery",
+        fallbacks: ["associatedInferred", "associatedDiscovery"],
+    },
+    analysis: {
+        clientKey: "analysis",
+        storageProp: "doc.associatedAnalysis",
+        fallbacks: ["associatedAnalysis"],
+    },
+};
+/**
+ * Resolve a normalized associated bucket from a raw document.
+ * Strips raw `associated*` fields and reconstructs the `associated` bucket
+ * using the alias map. Custom associated properties follow the pattern
+ * associated{Custom}.
+ */
+export function buildAssociatedBucket(rawDoc) {
+    const associated = {};
+    const properties = [];
+    const strippedDoc = {};
+    for (const [k, v] of Object.entries(rawDoc)) {
+        if (k.startsWith("associated")) {
+            // Map known aliases: associatedData -> data, associatedInferred -> discovery, etc.
+            const clientKey = aliasStorageToClient(k);
+            associated[clientKey] = v;
+            properties.push({
+                propertyName: clientKey,
+                source: k,
+                count: Array.isArray(v) ? v.length : v != null ? 1 : 0,
+            });
+        }
+        else {
+            strippedDoc[k] = v;
+        }
+    }
+    return { associated, strippedDoc, properties };
+}
+export function aliasStorageToClient(storageKey) {
+    switch (storageKey) {
+        case "associatedData":
+            return "data";
+        case "associatedInferred":
+        case "associatedDiscovery":
+            return "discovery";
+        case "associatedAnalysis":
+            return "analysis";
+        default:
+            // associated{Custom} -> {custom}
+            return storageKey.replace(/^associated/, "").replace(/^./, (c) => c.toLowerCase());
+    }
+}
+export function aliasClientToStorage(clientKey) {
+    const entry = STORAGE_ALIASES[clientKey];
+    if (entry) {
+        return { primary: entry.fallbacks[0], fallbacks: entry.fallbacks };
+    }
+    // custom -> associated{Custom}
+    const cap = clientKey.replace(/^./, (c) => c.toUpperCase());
+    const storage = `associated${cap}`;
+    return { primary: storage, fallbacks: [storage] };
+}
+export function resolveInclude(include) {
+    if (!include)
+        return null;
+    const list = Array.isArray(include) ? include : include.split(",");
+    return new Set(list.map((s) => s.trim()).filter(Boolean));
+}

package/dist/engine/associations.d.ts

@@ -0,0 +1,26 @@
+export interface AssociationPlan {
+    objectType: string;
+    expectedPlanFingerprint: string;
+    proposedMutations: Array<{
+        recordId: string;
+        targetArray: string;
+        op: string;
+        count: number;
+    }>;
+}
+export declare function planAssociations(objectType?: string): AssociationPlan[];
+export interface ApplyResult {
+    objectType: string;
+    applied: boolean;
+    expectedPlanFingerprint: string;
+    actualFingerprint: string;
+    mismatch: boolean;
+    count: number;
+}
+export declare function applyAssociations(expectedPlanFingerprint: string, objectType?: string): ApplyResult[];
+export declare function verifyAssociations(expectedPlanFingerprint: string, objectType?: string): {
+    objectType: string;
+    expectedPlanFingerprint: string;
+    actualFingerprint: string;
+    verified: boolean;
+}[];

package/dist/engine/associations.js

@@ -0,0 +1,60 @@
+import { store } from "../storage/InMemoryStore.js";
+import { CONTENT_TYPES } from "../types.js";
+import { computeAssociationFingerprint } from "../engine/snapshots.js";
+import { listDataObjectTypes } from "../engine/inventory.js";
+export function planAssociations(objectType) {
+    const types = objectType ? [objectType] : listDataObjectTypes();
+    const plans = [];
+    for (const ot of types) {
+        const fingerprint = computeAssociationFingerprint(ot);
+        const mutations = [];
+        for (const ct of CONTENT_TYPES) {
+            const records = store.getCollection(ot, ct);
+            mutations.push({
+                recordId: `${ot}/${ct}`,
+                targetArray: `${ot}/${ct}`,
+                op: "noop",
+                count: records.length,
+            });
+        }
+        plans.push({
+            objectType: ot,
+            expectedPlanFingerprint: fingerprint,
+            proposedMutations: mutations,
+        });
+    }
+    return plans;
+}
+export function applyAssociations(expectedPlanFingerprint, objectType) {
+    const types = objectType ? [objectType] : listDataObjectTypes();
+    const results = [];
+    for (const ot of types) {
+        const actual = computeAssociationFingerprint(ot);
+        const mismatch = actual !== expectedPlanFingerprint;
+        results.push({
+            objectType: ot,
+            applied: !mismatch,
+            expectedPlanFingerprint,
+            actualFingerprint: actual,
+            mismatch,
+            count: store.getCollection(ot, "snapshots").length,
+        });
+    }
+    // Trigger flush
+    for (const ot of types) {
+        store.flushCollectionNow(`${ot}/snapshots`);
+    }
+    return results;
+}
+export function verifyAssociations(expectedPlanFingerprint, objectType) {
+    const types = objectType ? [objectType] : listDataObjectTypes();
+    return types.map((ot) => {
+        const actual = computeAssociationFingerprint(ot);
+        return {
+            objectType: ot,
+            expectedPlanFingerprint,
+            actualFingerprint: actual,
+            verified: actual === expectedPlanFingerprint,
+        };
+    });
+}

package/dist/engine/identity.d.ts

@@ -0,0 +1,22 @@
+import type { ContentType, IdentityKey } from "../types.js";
+/**
+ * Resolve the primary identity field for a given object type / content type.
+ * `memory` collections are keyed by `memoryId`; everything else falls back to
+ * the per-document heuristic used elsewhere.
+ */
+export declare function resolveIdField(ct: ContentType, sample?: any): IdentityKey;
+/**
+ * Mock of the production `MemorixRecordArraySchema`. Validates that each record
+ * in a collection array carries the collection's canonical identity key.
+ * Additional identity-shaped fields are allowed because they can represent
+ * relationships (for example a memory has `memoryId` and may reference an
+ * `entityId` or `eventId`).
+ */
+export declare function validateRecordArray(objectType: string, ct: ContentType, records: any[]): {
+    ok: boolean;
+    errors: string[];
+};
+/**
+ * Find a record by any of the supported identity keys.
+ */
+export declare function findByIdentity(records: any[], identity: Partial<Record<IdentityKey, string>>): any | undefined;