@x12i/static-memorix 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,431 @@
+# @x12i/static-memorix
+
+Static mock server that provides **full API parity** for the Memorix Explorer
+Fastify API. No MongoDB, Catalox, or Redis required — state lives in
+`./mocks/**/*.json` and is flushed to disk (debounced) on mutation.
+
+Ships with a **complete reference demo app** (FlowState — a small task
+manager) at `GET /demo` that exercises every read/write path in the API.
+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
+static-memorix
+```
+
+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
+static-memorix create-demo
+static-memorix --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
+static-memorix create-demo --dir ./my-project-fixtures
+static-memorix --mocks-dir ./my-project-fixtures --port 8080
+```
+
+Useful options:
+
+```bash
+static-memorix --port 8080
+static-memorix --help
+static-memorix --version
+```
+
+Stop a server started by the CLI:
+
+```bash
+static-memorix stop                 # port 5030
+static-memorix stop --port 8080
+```
+
+If a requested port is occupied, the CLI explains these stop and alternate-port
+options instead of returning only `EADDRINUSE`.
+
+> `memorix-explorer` remains available as a short alias for the `static-memorix`
+> command — both point at the same binary.
+
+### Run from this repository
+
+```bash
+npm install
+npm run build
+npm start                 # listens on :5030 (PORT / HOST / MOCKS_DIR env-overridable)
+# dev (no build): npm run dev
+
+# open the demo UI in your browser
+open http://localhost:5030/demo
+```
+
+Health:
+
+```bash
+curl localhost:5030/health
+curl "localhost:5030/api/explorer/health?includeInventory=1"
+```
+
+## Run from CLI or code
+
+Installed CLI, using the default port `5030`:
+
+```bash
+npx @x12i/static-memorix
+```
+
+Or, after a global install:
+
+```bash
+static-memorix
+```
+
+Override the port from the shell:
+
+```bash
+PORT=8080 npx @x12i/static-memorix
+```
+
+Start it programmatically (explicit options take precedence over environment
+defaults):
+
+```js
+import { startServer } from "@x12i/static-memorix";
+
+const app = await startServer({ port: 5030, host: "127.0.0.1" });
+// await app.close();
+```
+
+For code-level tests without binding a port:
+
+```js
+import { buildServer } from "@x12i/static-memorix";
+
+const app = await buildServer();
+const response = await app.inject({ method: "GET", url: "/health" });
+await app.close();
+```
+
+See [guides/running-the-service.md](./guides/running-the-service.md) for all
+CLI, environment, lifecycle, and programmatic examples.
+
+## Architecture
+
+```
+Fastify Router (/api/explorer/* + /health + Authix/M2M shim + /demo)
+        │
+Query & Interceptor Engine (mingo + narrative virtual filters)
+    ┌────────────┬──────────────────┬──────────────┐
+Inventory/Lenses  Snapshots/Aliases   Records Writer
+    └────────────┴──────────────────┴──────────────┘
+               InMemoryStore (state matrix)
+                         │ debounced disk flush
+          ./mocks/metadata  &  ./mocks/data
+```
+
+## Routes
+
+| Group | Endpoints |
+|------|-----------|
+| Health | `GET /health`, `GET /api/explorer/health?includeInventory=1` |
+| Inventory | `/inventory/collections`, `/summary`, `/issues`, `/graph` (query `sourceLens=db-first\|catalox-first`) |
+| Snapshots | `/snapshots/:objectType/:recordId[.../associated[/:propertyName]]`, `/snapshots/:objectType/associated-properties`, `/associations/plan\|apply\|verify` |
+| Records | `/records/collection`, `/full`, `/item`, `/content`, `/raw-collection`, `/raw-item`, `/workspace`, `POST /records/write`, `DELETE /records/item` |
+| Lists | `/lists`, `/lists/:listId`, `/lists/:listId/records`, `/lists/suggest`, mutations `POST/PATCH/PUT/DELETE` |
+| Narratives | `/narratives`, `/:entity`, `/:entity/raw`, `/:entity/:key`, `/:entity/:key/records`, mutations `POST/PATCH/DELETE` |
+| Object Types | `/object-types`, `/:name`, `/:name/root-property-catalog`, `POST .../compute` |
+| Write | `POST /records/write` (validate / dryRun / add / upsert / patch / replace / **delete**) |
+| Agents | `GET /agents` |
+| Auth shim | `POST /api/explorer/auth/token` |
+| Demo | `GET /demo` — serves `mocks/demo.html` |
+
+## Query conventions
+
+- `filter=prop:op:val` — op ∈ `eq,ne,gt,gte,lt,lte,in,nin,exists,regex`
+  (`in`/`nin` use `|` separators). Repeatable / `;`-separated.
+- Virtual narrative filter: `filter=narrativeId:eq:has-vulns` rewrites the
+  query to evaluate `doc.narratives['has-vulns']`.
+- `sort=severity:desc&sort=entityId:asc` (mingo sort).
+- `searchText=` / `q=` full-text substring match.
+- `limit` (max 500), `offset`/`skip`, `includeTotal=1`.
+- `target=memory` to query the memory tier (fourth data tier alongside entities/events/knowledge).
+
+## Identity keys
+
+The mock server accepts the following identity keys across fetch/write engines:
+- `recordId` — entities
+- `entityId` — entities
+- `eventId` — events
+- `knowledgeId` — knowledge
+- `memoryId` — memory
+
+Endpoints like `/records/full` and `/records/content` require exactly one identity key
+per request. Memory collections are keyed by `memoryId`; the unprefixed
+`./mocks/data/memory/memory.json` is the seed and routed writes use the active
+Catalox-prefixed filename.
+
+## Snapshot alias translation
+
+Client `associated.data|discovery|analysis|{custom}` maps to storage
+`associatedData | associatedInferred/associatedDiscovery | associatedAnalysis |
+associated{Custom}`. Raw `associated*` fields are stripped from the returned
+document and recomposed into a normalized `associated` bucket.
+
+## Write engine
+
+`POST /api/explorer/records/write` accepts an `operation` and routes the
+payload through the write descriptor's JSON schema.
+
+### Operations
+
+| Operation | Behavior |
+|-----------|----------|
+| `add`     | Append. Auto-generates an identity if missing. |
+| `upsert`  | Update existing by identity key, or append. |
+| `patch`   | Update existing by identity key. No-op if missing. |
+| `replace` | Replace the entire collection (use with caution). |
+| `delete`  | Remove every record matching the supplied identity keys. Returns the removed records. |
+
+### Required-field semantics
+
+The `schema.required` array is enforced **fully** for `add` and `replace`.
+For `upsert`, `patch`, and `delete`, only the identity field (`recordId`,
+or `memoryId` on the memory tier) is required. This allows partial updates
+like `{recordId, status}` without resupplying every required field — the
+pattern the demo UI uses for every inline edit.
+
+### REST-style delete
+
+For ergonomics, you can also delete a single record with:
+
+```
+DELETE /api/explorer/records/item?entityName=product&recordId=t1&writeDescriptorId=product-task-write
+```
+
+Returns `{ ok: true, count: <n>, removed: [<record>…] }` and flushes immediately.
+
+## Demo app
+
+The `mocks/demo.html` reference UI (served at `GET /demo`) is a complete task
+manager that uses the Explorer API for every read and mutation. It demonstrates:
+
+- Multi-collection reads (3 parallel `records/collection` calls + a `users` collection)
+- Filter / search / sort via query params
+- **Create** via modal → `POST /records/write op=add`
+- **Edit** via inline pills/dropdowns → `POST /records/write op=upsert` (partial updates)
+- **Delete** via button → `DELETE /records/item`
+- Cross-collection **move** (delete on old area + add on new area)
+- Optimistic UI with rollback on failure
+
+Full implementation walkthrough: [guides/demo-app.md](./guides/demo-app.md).
+
+## Environment
+
+| Var | Default | Notes |
+|-----|---------|-------|
+| `PORT` | `5030` | Listen port |
+| `HOST` | `0.0.0.0` | Listen host |
+| `MOCKS_DIR` | bundled `<package>/mocks` | Fixture root |
+| `DISK_FLUSH_DEBOUNCE_MS` | `300` | Debounce before disk flush |
+| `MEMORIX_ORG_ID` | `memorix` | Organization prefix for DB routing |
+| `MEMORIX_AGENT_ID` | `default-agent` | Agent prefix for catalox DB routing |
+| `MEMORIX_DEPLOYMENT_PROFILE` | `default` | Deployment profile; `ebook` forces org/agent to `ebooks` |
+| `MEMORIX_EXPLORER_ENABLE_METADATA_WRITES` | `false` | Allow list & narrative mutations |
+| `MEMORIX_EXPLORER_ENABLE_PIPELINE_WRITES` | `false` | Allow pipeline writes |
+| `MEMORIX_EXPLORER_ENABLE_REGISTRY_WRITES` | `false` | Allow registry writes |
+
+For mutation-capable installed deployments, set `MOCKS_DIR` to a writable,
+persistent directory. Routing configuration is process-scoped and resolved on
+first import; use one process per organization/agent context and one writer per
+prefix.
+
+## DB Router Simulation
+
+The mock server does not connect to MongoDB, but it **tricks the frontend** into
+thinking it is talking to the routed tenant databases.
+
+- The `GET /api/explorer/health` response includes a dynamic `memorixDb`
+  field constructed as `<orgId>-memorix-entities + <orgId>-memorix-events`.
+- The agent-scoped catalox DB is reflected in the `cataloxDb` field as
+  `<agentId>-memorix-catalox`.
+
+These strings are derived from `MEMORIX_ORG_ID`, `MEMORIX_AGENT_ID`, and the
+`MEMORIX_DEPLOYMENT_PROFILE` (which, when set to `ebook`, forces both IDs to
+`ebooks`).
+
+### File-backed routing
+
+Those routed database names also select JSON files. The separator is `--`:
+
+```text
+mocks/data/product/neo-memorix-entities--snapshots.json
+mocks/data/product/neo-memorix-events--events.json
+mocks/data/memory/neo-agent-memorix-catalox--memory.json
+mocks/metadata/lists/neo-agent-memorix-catalox--my-plate.json
+```
+
+For `MEMORIX_ORG_ID=neo` and `MEMORIX_AGENT_ID=neo-agent`, entity-like
+collections use the first prefix, events use the second, and memory plus
+metadata use the Catalox prefix. If a routed file does not exist, the server
+loads its unprefixed counterpart as seed data, but all mutations are written
+to the routed filename. This provides database-style isolation without a
+database and preserves existing fixtures.
+
+The health response exposes the resolved values under `fileRouting`.
+See [guides/managing-json-files.md](./guides/managing-json-files.md) for the
+complete precedence and migration rules.
+
+## Feature Flag Enforcement
+
+The mock server enforces the following feature-flag gates with error responses:
+- List/narrative mutations (`POST/PATCH/PUT/DELETE /lists`, `/narratives`) require
+  `MEMORIX_EXPLORER_ENABLE_METADATA_WRITES=true`.
+- Pipeline writes (if implemented) require
+  `MEMORIX_EXPLORER_ENABLE_PIPELINE_WRITES=true`.
+- Registry writes (if implemented) require
+  `MEMORIX_EXPLORER_ENABLE_REGISTRY_WRITES=true`.
+
+Record writes (`POST /records/write`, `DELETE /records/item`) are **not**
+feature-flagged — they're always on, gated only by the write descriptor contract.
+
+When a flag is disabled or unset, the mock returns `{ ok: false, error: "..." }`
+matching the production Fastify error shape (typically 403/404).
+
+## The "memory" Target
+
+The API has expanded its domain model to include a fourth tier of data: `memory`.
+The mock's querying and writing engines now support `target=memory` and
+`memoryId` as a valid primary key alongside `recordId`, `entityId`, `eventId`,
+and `knowledgeId`.
+
+- Folder structure: `./mocks/data/memory/memory.json` (seeded with example memories).
+- Runtime memory writes persist to the active
+  `<agent>-memorix-catalox--memory.json` route.
+- Inventory engine accepts `target=memory` and includes memory collections in
+  the simulated `inventorySummary`.
+- Records engine accepts `target=memory` and supports `memoryId` for fetching.
+- Write engine validates and persists `memoryId` on memory-tier records.
+- Startup validation (`MemorixRecordArraySchema` mock) allows `memoryId` without
+  throwing schema errors.
+
+## Documentation
+
+- [guides/running-the-service.md](./guides/running-the-service.md) — installation, configuration, env vars
+- [guides/using-the-api.md](./guides/using-the-api.md) — endpoint reference, query language, write operations
+- [guides/managing-json-files.md](./guides/managing-json-files.md) — fixture structure, schemas, how the store works
+- [guides/demo-app.md](./guides/demo-app.md) — FlowState reference UI walkthrough
+
+## Release history
+
+### v2.0.0
+- **Renamed** the package from `@x12i/static-memorix-explorer-api` to
+  `@x12i/static-memorix`. Install and import under the new name going
+  forward; see [Install → Renamed package](./site/install.html#uninstall).
+- Added the `static-memorix` CLI command, matching the new package name.
+  `memorix-explorer` remains available as a short alias; the old
+  `static-memorix-explorer-api` and `mock-memorix-explorer-api` aliases were
+  retired as part of the rename.
+- Updated repository, homepage, and issue-tracker URLs to
+  `github.com/x12i/static-memorix`.
+- No functional, API, or behavior changes — this is a naming-only release.
+
+### 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
+  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
+  startup failure, preventing accidental data loss.
+- Made JSON persistence atomic through same-directory temporary-file renames.
+- Made list deletion restart-safe with routed tombstones.
+- Fixed installed npm CLI execution through symlink-aware entry detection.
+- Added packed-install, restart, traversal, corruption, and atomic-write checks.
+- Documented writable `MOCKS_DIR`, process isolation, and single-writer limits.
+
+### v1.3.0
+- Added database-routing parity through deterministic JSON filename prefixes.
+- Added separate entity, event, and Catalox/metadata prefix resolution.
+- Added migration-safe fallback from missing routed files to unprefixed seeds;
+  writes always persist to the selected routed file.
+- Added resolved `fileRouting` prefixes to the health response.
+- Updated metadata discovery to ignore other routed tenants.
+- Added routed persistence and prefix regression coverage.
+
+### v1.2.0
+- Added native `--port` and `--host` CLI options.
+- Added the canonical `static-memorix-explorer-api` executable while retaining
+  `mock-memorix-explorer-api` as a compatibility alias.
+- Published TypeScript declarations for `buildServer()`, `startServer()`,
+  configuration exports, and server options.
+- Corrected the supported Node.js runtime to Node 20 or newer for Fastify 5.
+- Expanded CLI, programmatic, test, precedence, and lifecycle documentation.
+
+### v1.1.1
+- Changed the default listen port from `4300` to `5030`.
+- Added safe programmatic APIs: `buildServer()` and `startServer(options)`.
+- Importing the package no longer starts a listener as a side effect.
+- Added CLI, environment override, programmatic startup, and injected-test examples.
+
+### v1.1.0
+- **Added**: `delete` operation to the write engine
+  (`POST /records/write` body `operation:"delete"`).
+- **Added**: REST-style `DELETE /api/explorer/records/item` endpoint.
+- **Added**: Operation-aware schema validation — `upsert`/`patch`/`delete`
+  only require the identity field, not every `required` field.
+- **Added**: Complete demo application (`mocks/demo.html`) wired entirely
+  through the Explorer API — Create/Edit/Delete/Move with optimistic UI.
+- **Added**: `users` object type + collection.
+- **Added**: Per-area task write descriptors
+  (`product/marketing/admin-task-write`).
+- **Added**: Per-area narratives and enriched task snapshots
+  (`notes`, `chat`, `assigneeId`).
+- **Removed**: obsolete `/api/state` flow and `mocks/db.json`
+  (replaced by Explorer API writes).
+- **Docs**: full demo walkthrough (`guides/demo-app.md`) and refreshed
+  endpoint tables.
+
+### v1.0.0
+- Initial implementation of mock Memorix Explorer API.
+- Health, inventory, snapshots, records, lists, narratives, object types,
+  write engine (add/upsert/patch/replace), agents, auth shim.

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  static-memorix create-demo [--dir <path>]\n  static-memorix stop [--port <number>]\n  static-memorix [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  static-memorix create-demo\n  static-memorix --mocks-dir ./memorix-demo\n\n(\"memorix-explorer\" remains available as a short alias for this command.)\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>;