@crazygiscool/cap 1.0.0

package/README.md

@@ -0,0 +1,161 @@
+# CAP — Central Archive Protocol
+
+Configuration-driven **TypeScript** library for lore documentation. Wraps **MongoDB** with **Zod** validation to standardize irregular, deeply nested lore data across fictional universes.
+
+## Install
+
+```sh
+npm install cap
+# peer deps (must install yourself)
+npm install mongodb@^6 zod@^3
+```
+
+## Quick Start
+
+```typescript
+import { loadSettings, generateDynamicSchema, CAPRepository, ICAPBaseDocument } from "cap";
+import { MongoClient, Db } from "mongodb";
+
+// 1. Load universe config
+const config = loadSettings("./settings.json");
+
+// 2. Build dynamic validation schema
+const schema = generateDynamicSchema(config.entryFormat.customFields ?? []);
+
+// 3. Connect to MongoDB
+const client = new MongoClient("mongodb://localhost:27017");
+const db = client.db(config.databaseName);
+
+// 4. Define an entry type
+interface CharacterEntry extends ICAPBaseDocument {
+  sparkId: string;
+  firepower: number;
+  isOnline: boolean;
+}
+
+// 5. Extend the repository
+class CharacterRepo extends CAPRepository<CharacterEntry> {
+  constructor(db: Db) {
+    super(db, "characters");
+  }
+}
+
+// 6. Use it
+const repo = new CharacterRepo(db);
+
+const optimus = await repo.create({
+  name: "Optimus Prime",
+  description: "Leader of the Autobots",
+  continuityId: "g1",
+  factions: ["Autobots"],
+  sparkId: "SP-2187",
+  firepower: 9000,
+  isOnline: true,
+});
+
+console.log(optimus.id); // auto-generated UUID
+
+const found = await repo.findById(optimus.id);
+const updated = await repo.update(optimus.id, { firepower: 9500 });
+await repo.delete(optimus.id);
+
+// Validate incoming data at runtime
+const parsed = schema.parse({
+  name: "Bumblebee",
+  description: "Autobot scout",
+  continuityId: "animated",
+  factions: ["Autobots"],
+  sparkId: "SP-0001",
+  firepower: 500,
+  isOnline: true,
+});
+```
+
+## API
+
+### `CAPRepository<T>`
+
+Abstract class you extend. `T` must implement `ICAPBaseDocument`.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `create(data)` | `T & { id: string }` | Insert doc with auto-generated UUID + `createdAt` / `updatedAt` |
+| `findById(id)` | `T \| null` | Lookup by string id |
+| `findByName(name)` | `T \| null` | Case-insensitive regex match on `name` |
+| `listAll()` | `T[]` | All documents in the collection |
+| `update(id, data)` | `T \| null` | Partial update, auto-bumps `updatedAt`. Returns updated doc or null |
+| `delete(id)` | `boolean` | Delete by id. Returns `true` if a document was removed |
+
+### `generateDynamicSchema(customFields)`
+
+Creates a Zod schema from a `settings.json` `customFields` array and merges it with `CAPBaseSchema`.
+
+```typescript
+const schema = generateDynamicSchema([
+  { key: "sparkId", type: "string", label: "Spark Signature" },
+  { key: "firepower", type: "number", label: "Firepower Rating" },
+]);
+// Result: CAPBaseSchema extended with sparkId (z.string()) + firepower (z.number())
+```
+
+Supported field types: `"string"` | `"number"` | `"boolean"` | `"date"`
+
+### `loadSettings(path)`
+
+Reads a JSON file from disk, validates it against `CAPSettingsSchema`, and returns a typed `SettingsConfig`.
+
+```typescript
+const config = loadSettings("./settings.json");
+// config.databaseName       → string
+// config.entryFormat        → { requiredFields?, customFields? }
+```
+
+## Configuration
+
+Create a `settings.json` at your app root:
+
+```json
+{
+  "databaseName": "Nova Cronum",
+  "entryFormat": {
+    "requiredFields": ["name", "description", "continuityId", "factions"],
+    "customFields": [
+      { "key": "sparkId", "type": "string", "label": "Spark Signature" },
+      { "key": "primaryFunction", "type": "string", "label": "Designated Function" },
+      { "key": "firepower", "type": "number", "label": "Firepower Rating" }
+    ]
+  }
+}
+```
+
+## Build & Test
+
+```sh
+npm run build          # tsc → dist/
+npm test               # vitest run --coverage
+npm run test:watch     # vitest (watch mode)
+```
+
+## Exports
+
+| Export | Kind |
+|--------|------|
+| `ICAPBaseDocument` | interface |
+| `ILoreVariant<T>` | interface |
+| `CAPBaseSchema` | Zod schema |
+| `CAPRepository<T>` | abstract class |
+| `generateDynamicSchema` | function |
+| `loadSettings` | function |
+| `CAPSettingsSchema` | Zod schema |
+| `CustomFieldConfig` | interface |
+| `EntryFormatConfig` | interface |
+| `SettingsConfig` | interface |
+| `FieldType` | type (`"string" | "number" | "boolean" | "date"`) |
+
+## Module System
+
+ESM (`"type": "module"`) with NodeNext module resolution. Import sibling files with `.js` extension.
+
+```typescript
+import { CAPRepository } from "cap";
+```

package/dist/index.js

@@ -0,0 +1,84 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+// Runtime validation baseline
+export const CAPBaseSchema = z.object({
+    name: z.string().min(1),
+    description: z.string(),
+    continuityId: z.string(),
+    factions: z.array(z.string()),
+});
+// Standardized MongoDB Data Layer
+export class CAPRepository {
+    collection;
+    constructor(db, collectionName) {
+        this.collection = db.collection(collectionName);
+    }
+    async create(data) {
+        const doc = {
+            ...data,
+            id: randomUUID(),
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+        await this.collection.insertOne(doc);
+        return doc;
+    }
+    async findById(id) {
+        return this.collection.findOne({ id });
+    }
+    async findByName(name) {
+        return this.collection.findOne({
+            name: { $regex: name, $options: "i" },
+        });
+    }
+    async listAll() {
+        return this.collection.find({}).toArray();
+    }
+    async update(id, data) {
+        return this.collection.findOneAndUpdate({ id }, { $set: { ...data, updatedAt: new Date() } }, { returnDocument: "after" });
+    }
+    async delete(id) {
+        const result = await this.collection.deleteOne({ id });
+        return result.deletedCount > 0;
+    }
+}
+const CustomFieldSchema = z.object({
+    key: z.string().min(1),
+    type: z.enum(["string", "number", "boolean", "date"]),
+    label: z.string().min(1),
+});
+export const CAPSettingsSchema = z.object({
+    databaseName: z.string().min(1),
+    entryFormat: z.object({
+        requiredFields: z.array(z.string()).optional(),
+        customFields: z.array(CustomFieldSchema).optional(),
+    }),
+});
+function zodTypeForFieldType(fieldType) {
+    switch (fieldType) {
+        case "string":
+            return z.string();
+        case "number":
+            return z.number();
+        case "boolean":
+            return z.boolean();
+        case "date":
+            return z.string().datetime();
+        default:
+            throw new Error(`Unknown field type: ${fieldType}`);
+    }
+}
+export function generateDynamicSchema(customFields) {
+    const shape = {};
+    for (const field of customFields) {
+        shape[field.key] = zodTypeForFieldType(field.type);
+    }
+    return CAPBaseSchema.extend(shape);
+}
+export function loadSettings(path) {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    return CAPSettingsSchema.parse(parsed);
+}
+//# sourceMappingURL=index.js.map

package/docs/PLAN.md

@@ -0,0 +1,96 @@
+# CAP Development Plan
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────┐
+│  CAP (this repo)                             │
+│  ─────────────                               │
+│  cap package                                 │
+│  - CAPRepository<T>                          │
+│  - CAPBaseSchema                             │
+│  - generateDynamicSchema(customFields)       │
+│  - loadSettings(path)                        │
+└──────────────────────┬──────────────────────┘
+                       │ npm install file:../cap
+                       ▼
+┌─────────────────────────────────────────────┐
+│  Nova Cronum (separate repo)                 │
+│  SvelteKit full-stack app                    │
+│  - settings.json (backend config, validation)│
+│  - CRUD routes with dynamic Zod validation   │
+│  - consumes `cap` library                    │
+└─────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────┐
+│  Frontend Template (separate GH template)    │
+│  SvelteKit skeleton                          │
+│  - theme.config.json (separate frontend cfg) │
+│  - CSS custom properties (build-time baked)  │
+│  - Nav from pages config                     │
+│  - Favicon injection                         │
+│  - Layout + slot for universe pages          │
+└─────────────────────────────────────────────┘
+```
+
+**Key decisions:**
+- No monorepo — `cap` stays a standalone npm package at root
+- Backend and frontend use separate config files
+- Frontend template is a "Use this template" GitHub repo
+- Template loads config at build time (static, baked into CSS)
+
+---
+
+## Task 1: Testing Infrastructure
+
+| # | File | Detail |
+|---|------|--------|
+| 1.1 | `package.json` | Add `vitest` + `@vitest/coverage-v8` to devDependencies. Add `"test": "vitest run --coverage"` and `"test:watch": "vitest"`. |
+| 1.2 | `vitest.config.ts` | `defineConfig({ test: { globals: true, environment: 'node', include: ['src/**/*.test.ts'] } })` |
+| 1.3 | `src/__tests__/smoke.test.ts` | Import `CAPBaseSchema` and `CAPRepository` — verify they exist and schema validates a valid object. |
+| 1.4 | — | `npm install && npm run test` — verify green. |
+
+## Task 2: Dynamic Zod Schema Generator
+
+| # | File | Detail |
+|---|------|--------|
+| 2.1 | `src/index.ts` | Add types: `CustomFieldConfig`, `EntryFormatConfig`, `SettingsConfig`, `FieldType`. |
+| 2.2 | `src/index.ts` | **`generateDynamicSchema(customFields: CustomFieldConfig[])`:** maps each field type to a Zod primitive (`string → z.string()`, `number → z.number()`, `boolean → z.boolean()`, `date → z.string().datetime()`), builds a `z.object({ [key]: zodType })`, merges with `CAPBaseSchema`. Returns composite schema. |
+| 2.3 | `src/index.ts` | **`loadSettings(path: string)`:** reads JSON with `fs.readFileSync`, parses, validates against a static `SettingsSchema` (Zod schema for the config file shape), returns typed `SettingsConfig`. |
+| 2.4 | — | `npm run build` — verify compilation. |
+
+## Task 3: Tests
+
+| # | File | Detail |
+|---|------|--------|
+| 3.1 | `src/__tests__/dynamic-schema.test.ts` | Test `generateDynamicSchema`: empty list returns base schema; each type maps correctly; mixed fields; unknown type throws; valid data passes; invalid fails. |
+| 3.2 | `src/__tests__/settings-loader.test.ts` | Test `loadSettings` with temp files: valid config parses; missing file throws; invalid JSON throws; missing required field throws. |
+| 3.3 | — | `npm run test` — full suite green. |
+
+## Task 4: Documentation
+
+| # | File | Detail |
+|---|------|--------|
+| 4.1 | `AGENTS.md` | Add test commands, new exports, dynamic schema notes. |
+| 4.2 | — | `npm run build && npm run test` — final verification. |
+
+---
+
+## Separate Repos (out of scope for this repo)
+
+### Nova Cronum
+- Standalone SvelteKit repo
+- `npm install file:../cap` to link cap package
+- `settings.json` with universe-specific entry format and custom fields
+- API routes using `CAPRepository` + `generateDynamicSchema`
+- Serves as the integration test for cap
+
+### Frontend Template
+- GitHub template repository ("Use this template")
+- SvelteKit skeleton project
+- `theme.config.json` with theme, favicon, pages config
+- Imports config at build time (Vite JSON import)
+- Binds CSS custom properties from theme
+- Renders navigation from pages config
+- Injects favicon from config path
+- Universe apps fork and add their routes on top

package/docs/QUICKSTART.md

@@ -0,0 +1,123 @@
+# Quick Start — Building a Universe App with CAP
+
+This guide walks through creating a **Nova Cronum**-style lore application from scratch.
+
+## 1. Create the project
+
+```sh
+mkdir nova-cronum && cd nova-cronum
+npm init -y
+npm install ../cap      # or: npm install file:../cap
+npm install mongodb@^6 zod@^3
+```
+
+Set `"type": "module"` in `package.json`.
+
+## 2. Create settings.json
+
+```json
+{
+  "databaseName": "Nova Cronum",
+  "entryFormat": {
+    "customFields": [
+      { "key": "sparkId", "type": "string", "label": "Spark Signature" },
+      { "key": "primaryFunction", "type": "string", "label": "Designated Function" },
+      { "key": "firepower", "type": "number", "label": "Firepower Rating" },
+      { "key": "isOnline", "type": "boolean", "label": "Active Status" },
+      { "key": "activated", "type": "date", "label": "Activation Date" }
+    ]
+  }
+}
+```
+
+## 3. Connect and seed
+
+```typescript
+// src/db.ts
+import { loadSettings, CAPRepository, ICAPBaseDocument } from "cap";
+import { MongoClient, Db } from "mongodb";
+
+export interface CharacterEntry extends ICAPBaseDocument {
+  sparkId: string;
+  primaryFunction: string;
+  firepower: number;
+  isOnline: boolean;
+  activated: string; // ISO datetime string
+}
+
+export class CharacterRepo extends CAPRepository<CharacterEntry> {
+  constructor(db: Db) {
+    super(db, "characters");
+  }
+}
+
+const config = loadSettings("./settings.json");
+const client = new MongoClient("mongodb://localhost:27017");
+const db = client.db(config.databaseName);
+export const repo = new CharacterRepo(db);
+```
+
+```typescript
+// src/seed.ts
+import { repo } from "./db.js";
+
+const optimus = await repo.create({
+  name: "Optimus Prime",
+  description: "Leader of the Autobots",
+  continuityId: "g1",
+  factions: ["Autobots"],
+  sparkId: "SP-2187",
+  primaryFunction: "Matrix of Leadership Bearer",
+  firepower: 9000,
+  isOnline: true,
+  activated: "1984-09-17T00:00:00.000Z",
+});
+
+console.log("Created:", optimus.id);
+```
+
+## 4. Validate incoming data dynamically
+
+```typescript
+// src/validate.ts
+import { loadSettings, generateDynamicSchema } from "cap";
+
+const config = loadSettings("./settings.json");
+const schema = generateDynamicSchema(config.entryFormat.customFields ?? []);
+
+// Use schema.parse() in API routes to reject bad data
+const result = schema.safeParse(req.body);
+if (!result.success) {
+  return res.status(400).json(result.error);
+}
+```
+
+## 5. Full CRUD pattern
+
+```typescript
+// src/routes.ts
+import { repo } from "./db.js";
+
+// READ
+const all = await repo.listAll();
+const one = await repo.findById("some-uuid");
+const search = await repo.findByName("optimus");
+
+// CREATE (returns entry with generated id + timestamps)
+const created = await repo.create({ ... });
+
+// UPDATE (partial update, bumps updatedAt)
+const updated = await repo.update(created.id, { firepower: 9500 });
+
+// DELETE
+const deleted = await repo.delete(created.id); // boolean
+```
+
+## 6. With SvelteKit (for frontend + API later)
+
+```sh
+npx sv create . --template minimal --types ts
+npm install ../cap
+```
+
+Then add API routes under `src/routes/api/entries/+server.ts` using the same `repo` pattern above.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crazygiscool/cap",
+  "version": "1.0.0",
+  "description": "The Central Archive Protocol core library for lore documentation",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Crazygiscool/CAP.git"
+  },
+  "keywords": [
+    "documentation",
+    "mongodb",
+    "typescript",
+    "lore"
+  ],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/Crazygiscool/CAP/issues"
+  },
+  "homepage": "https://github.com/Crazygiscool/CAP#readme",
+  "peerDependencies": {
+    "mongodb": "^6.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "@vitest/coverage-v8": "^2.1.9",
+    "mongodb": "^6.5.0",
+    "typescript": "^5.4.5",
+    "vitest": "^2.1.9",
+    "zod": "^3.22.4"
+  }
+}

package/src/__tests__/dynamic-schema.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect } from "vitest";
+import {
+  CAPBaseSchema,
+  generateDynamicSchema,
+  type CustomFieldConfig,
+} from "../index.js";
+
+const baseFields = {
+  name: "Optimus Prime",
+  description: "Leader of the Autobots",
+  continuityId: "g1",
+  factions: ["Autobots"],
+};
+
+describe("generateDynamicSchema", () => {
+  it("returns base schema when customFields is empty", () => {
+    const schema = generateDynamicSchema([]);
+    const result = schema.safeParse(baseFields);
+    expect(result.success).toBe(true);
+  });
+
+  it("adds a string field", () => {
+    const fields: CustomFieldConfig[] = [
+      { key: "sparkId", type: "string", label: "Spark Signature" },
+    ];
+    const schema = generateDynamicSchema(fields);
+    const result = schema.safeParse({
+      ...baseFields,
+      sparkId: "SP-2187",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects a number for a string field", () => {
+    const fields: CustomFieldConfig[] = [
+      { key: "sparkId", type: "string", label: "Spark Signature" },
+    ];
+    const schema = generateDynamicSchema(fields);
+    const result = schema.safeParse({
+      ...baseFields,
+      sparkId: 42,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("adds a number field", () => {
+    const fields: CustomFieldConfig[] = [
+      { key: "firepower", type: "number", label: "Firepower Rating" },
+    ];
+    const schema = generateDynamicSchema(fields);
+    const ok = schema.safeParse({
+      ...baseFields,
+      firepower: 9000,
+    });
+    expect(ok.success).toBe(true);
+
+    const fail = schema.safeParse({
+      ...baseFields,
+      firepower: "over 9000",
+    });
+    expect(fail.success).toBe(false);
+  });
+
+  it("adds a boolean field", () => {
+    const fields: CustomFieldConfig[] = [
+      { key: "isOnline", type: "boolean", label: "Online Status" },
+    ];
+    const schema = generateDynamicSchema(fields);
+    const ok = schema.safeParse({
+      ...baseFields,
+      isOnline: true,
+    });
+    expect(ok.success).toBe(true);
+
+    const fail = schema.safeParse({
+      ...baseFields,
+      isOnline: "yes",
+    });
+    expect(fail.success).toBe(false);
+  });
+
+  it("adds a date field (ISO datetime string)", () => {
+    const fields: CustomFieldConfig[] = [
+      { key: "activated", type: "date", label: "Activation Date" },
+    ];
+    const schema = generateDynamicSchema(fields);
+    const ok = schema.safeParse({
+      ...baseFields,
+      activated: "2024-01-15T08:00:00.000Z",
+    });
+    expect(ok.success).toBe(true);
+
+    const fail = schema.safeParse({
+      ...baseFields,
+      activated: "not-a-date",
+    });
+    expect(fail.success).toBe(false);
+  });
+
+  it("handles multiple custom fields of different types", () => {
+    const fields: CustomFieldConfig[] = [
+      { key: "sparkId", type: "string", label: "Spark Signature" },
+      { key: "firepower", type: "number", label: "Firepower Rating" },
+      { key: "isOnline", type: "boolean", label: "Online Status" },
+    ];
+    const schema = generateDynamicSchema(fields);
+    const result = schema.safeParse({
+      ...baseFields,
+      sparkId: "SP-2187",
+      firepower: 9000,
+      isOnline: true,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects missing custom fields", () => {
+    const fields: CustomFieldConfig[] = [
+      { key: "sparkId", type: "string", label: "Spark Signature" },
+    ];
+    const schema = generateDynamicSchema(fields);
+    const result = schema.safeParse(baseFields);
+    expect(result.success).toBe(false);
+  });
+
+  it("still enforces base schema requirements", () => {
+    const schema = generateDynamicSchema([]);
+    const result = schema.safeParse({ name: "Megatron" });
+    expect(result.success).toBe(false);
+  });
+});

package/src/__tests__/repository.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { CAPRepository, type ICAPBaseDocument } from "../index.js";
+
+interface TestEntry extends ICAPBaseDocument {
+  sparkId: string;
+}
+
+class TestRepository extends CAPRepository<TestEntry> {
+  constructor(db: any) {
+    super(db, "test_entries");
+  }
+}
+
+function mockDb() {
+  const mockCollection = {
+    insertOne: vi.fn(),
+    findOne: vi.fn(),
+    find: vi.fn(() => ({
+      toArray: vi.fn(),
+    })),
+    findOneAndUpdate: vi.fn(),
+    deleteOne: vi.fn(),
+  };
+
+  const db = {
+    collection: vi.fn(() => mockCollection),
+  } as any;
+
+  return { db, collection: mockCollection };
+}
+
+describe("CAPRepository", () => {
+  let repo: TestRepository;
+  let collection: ReturnType<typeof mockDb>["collection"];
+
+  beforeEach(() => {
+    const { db, collection: c } = mockDb();
+    repo = new TestRepository(db);
+    collection = c;
+  });
+
+  describe("create", () => {
+    it("inserts a document with generated id and timestamps", async () => {
+      collection.insertOne.mockResolvedValue({ acknowledged: true });
+
+      const result = await repo.create({
+        name: "Optimus Prime",
+        description: "Leader of the Autobots",
+        continuityId: "g1",
+        factions: ["Autobots"],
+        sparkId: "SP-2187",
+      });
+
+      expect(result.id).toBeDefined();
+      expect(typeof result.id).toBe("string");
+      expect(result.createdAt).toBeInstanceOf(Date);
+      expect(result.updatedAt).toBeInstanceOf(Date);
+      expect(result.name).toBe("Optimus Prime");
+      expect(result.sparkId).toBe("SP-2187");
+
+      expect(collection.insertOne).toHaveBeenCalledOnce();
+      const inserted = collection.insertOne.mock.calls[0][0];
+      expect(inserted.id).toBe(result.id);
+      expect(inserted.createdAt).toBeInstanceOf(Date);
+      expect(inserted.updatedAt).toBeInstanceOf(Date);
+    });
+  });
+
+  describe("findById", () => {
+    it("returns a document by id", async () => {
+      const doc = {
+        _id: "abc",
+        id: "uuid-123",
+        name: "Bumblebee",
+        description: "Scout",
+        continuityId: "g1",
+        factions: ["Autobots"],
+        sparkId: "SP-0001",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      collection.findOne.mockResolvedValue(doc);
+
+      const result = await repo.findById("uuid-123");
+      expect(result).toEqual(doc);
+      expect(collection.findOne).toHaveBeenCalledWith({ id: "uuid-123" });
+    });
+
+    it("returns null when not found", async () => {
+      collection.findOne.mockResolvedValue(null);
+
+      const result = await repo.findById("nonexistent");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("findByName", () => {
+    it("returns a document by name (case-insensitive)", async () => {
+      const doc = {
+        _id: "abc",
+        id: "uuid-1",
+        name: "Megatron",
+        description: "Decepticon leader",
+        continuityId: "g1",
+        factions: ["Decepticons"],
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      collection.findOne.mockResolvedValue(doc);
+
+      const result = await repo.findByName("megatron");
+      expect(result).toEqual(doc);
+    });
+
+    it("returns null when not found", async () => {
+      collection.findOne.mockResolvedValue(null);
+
+      const result = await repo.findByName("Starscream");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("listAll", () => {
+    it("returns all documents", async () => {
+      const docs = [
+        { id: "1", name: "A", description: "", continuityId: "g1", factions: [], createdAt: new Date(), updatedAt: new Date() },
+        { id: "2", name: "B", description: "", continuityId: "g1", factions: [], createdAt: new Date(), updatedAt: new Date() },
+      ];
+      collection.find.mockReturnValue({ toArray: vi.fn().mockResolvedValue(docs) });
+
+      const result = await repo.listAll();
+      expect(result).toEqual(docs);
+      expect(result).toHaveLength(2);
+    });
+  });
+
+  describe("update", () => {
+    it("updates fields and bumps updatedAt", async () => {
+      const original = {
+        id: "uuid-1",
+        name: "Optimus Prime",
+        description: "Old description",
+        continuityId: "g1",
+        factions: ["Autobots"],
+        createdAt: new Date("2020-01-01"),
+        updatedAt: new Date("2020-01-01"),
+      };
+
+      const updated = {
+        ...original,
+        description: "New description",
+        updatedAt: new Date(),
+      };
+
+      collection.findOneAndUpdate.mockResolvedValue(updated);
+
+      const result = await repo.update("uuid-1", {
+        description: "New description",
+      });
+
+      expect(result).toEqual(updated);
+      expect(collection.findOneAndUpdate).toHaveBeenCalled();
+
+      const [, updateDoc] = collection.findOneAndUpdate.mock.calls[0];
+      expect(updateDoc.$set.description).toBe("New description");
+      expect(updateDoc.$set.updatedAt).toBeInstanceOf(Date);
+    });
+
+    it("returns null when document does not exist", async () => {
+      collection.findOneAndUpdate.mockResolvedValue(null);
+
+      const result = await repo.update("nonexistent", {
+        description: "Nope",
+      });
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("delete", () => {
+    it("returns true when a document is deleted", async () => {
+      collection.deleteOne.mockResolvedValue({ deletedCount: 1 });
+
+      const result = await repo.delete("uuid-1");
+      expect(result).toBe(true);
+      expect(collection.deleteOne).toHaveBeenCalledWith({ id: "uuid-1" });
+    });
+
+    it("returns false when no document matched", async () => {
+      collection.deleteOne.mockResolvedValue({ deletedCount: 0 });
+
+      const result = await repo.delete("nonexistent");
+      expect(result).toBe(false);
+    });
+  });
+});

package/src/__tests__/settings-loader.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, writeFileSync, unlinkSync, rmdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadSettings } from "../index.js";
+
+function withTempFile(
+  name: string,
+  content: string,
+  fn: (path: string) => void,
+) {
+  const dir = mkdtempSync(join(tmpdir(), "cap-test-"));
+  const filePath = join(dir, name);
+  writeFileSync(filePath, content, "utf-8");
+  try {
+    fn(filePath);
+  } finally {
+    try {
+      unlinkSync(filePath);
+    } catch {}
+    try {
+      rmdirSync(dir);
+    } catch {}
+  }
+}
+
+const validSettings = JSON.stringify({
+  databaseName: "Nova Cronum",
+  entryFormat: {
+    requiredFields: ["name", "description", "continuityId", "factions"],
+    customFields: [
+      { key: "sparkId", type: "string", label: "Spark Signature" },
+      { key: "firepower", type: "number", label: "Firepower Rating" },
+    ],
+  },
+});
+
+describe("loadSettings", () => {
+  it("parses a valid settings file", () => {
+    withTempFile("settings.json", validSettings, (path) => {
+      const config = loadSettings(path);
+      expect(config.databaseName).toBe("Nova Cronum");
+      expect(config.entryFormat.customFields).toHaveLength(2);
+      expect(config.entryFormat.customFields![0].key).toBe("sparkId");
+    });
+  });
+
+  it("accepts settings without customFields", () => {
+    const minimal = JSON.stringify({
+      databaseName: "Test Universe",
+      entryFormat: {},
+    });
+    withTempFile("settings.json", minimal, (path) => {
+      const config = loadSettings(path);
+      expect(config.databaseName).toBe("Test Universe");
+      expect(config.entryFormat.customFields).toBeUndefined();
+    });
+  });
+
+  it("throws on missing file", () => {
+    expect(() => loadSettings("/nonexistent/path.json")).toThrow();
+  });
+
+  it("throws on invalid JSON", () => {
+    withTempFile("settings.json", "{bad json}", (path) => {
+      expect(() => loadSettings(path)).toThrow();
+    });
+  });
+
+  it("throws on invalid field type", () => {
+    const bad = JSON.stringify({
+      databaseName: "Test",
+      entryFormat: {
+        customFields: [{ key: "x", type: "binary", label: "X" }],
+      },
+    });
+    withTempFile("settings.json", bad, (path) => {
+      expect(() => loadSettings(path)).toThrow();
+    });
+  });
+
+  it("throws when databaseName is missing", () => {
+    const bad = JSON.stringify({
+      entryFormat: {},
+    });
+    withTempFile("settings.json", bad, (path) => {
+      expect(() => loadSettings(path)).toThrow();
+    });
+  });
+});

package/src/__tests__/smoke.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { CAPBaseSchema, CAPRepository } from "../index.js";
+
+describe("CAPBaseSchema", () => {
+  it("validates a correct lore entry", () => {
+    const result = CAPBaseSchema.safeParse({
+      name: "Optimus Prime",
+      description: "Leader of the Autobots",
+      continuityId: "g1",
+      factions: ["Autobots"],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects an entry missing required fields", () => {
+    const result = CAPBaseSchema.safeParse({
+      name: "Megatron",
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("CAPRepository", () => {
+  it("is an abstract class that cannot be instantiated directly", () => {
+    expect(CAPRepository).toBeDefined();
+  });
+});

package/src/index.ts

@@ -0,0 +1,149 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { Collection, Db } from "mongodb";
+
+// Universal Document Rules
+export interface ICAPBaseDocument {
+  id: string;
+  name: string;
+  description: string;
+  continuityId: string;
+  factions: string[];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// Flexible variant template (Alt-modes, Multiverse variants, Eras)
+export interface ILoreVariant<T> {
+  variantName: string;
+  appearanceMediaId: string;
+  specifications: T;
+}
+
+// Runtime validation baseline
+export const CAPBaseSchema = z.object({
+  name: z.string().min(1),
+  description: z.string(),
+  continuityId: z.string(),
+  factions: z.array(z.string()),
+});
+
+// Standardized MongoDB Data Layer
+export abstract class CAPRepository<T extends ICAPBaseDocument> {
+  protected collection: Collection<T>;
+
+  constructor(db: Db, collectionName: string) {
+    this.collection = db.collection<T>(collectionName);
+  }
+
+  async create(
+    data: Omit<T, "id" | "createdAt" | "updatedAt">,
+  ): Promise<T & { id: string }> {
+    const doc = {
+      ...data,
+      id: randomUUID(),
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    } as any;
+    await this.collection.insertOne(doc);
+    return doc as T & { id: string };
+  }
+
+  async findById(id: string): Promise<T | null> {
+    return this.collection.findOne({ id } as any) as Promise<T | null>;
+  }
+
+  async findByName(name: string): Promise<T | null> {
+    return this.collection.findOne({
+      name: { $regex: name, $options: "i" },
+    } as any) as Promise<T | null>;
+  }
+
+  async listAll(): Promise<T[]> {
+    return this.collection.find({}).toArray() as Promise<T[]>;
+  }
+
+  async update(
+    id: string,
+    data: Partial<Omit<T, "id" | "createdAt" | "updatedAt">>,
+  ): Promise<T | null> {
+    return this.collection.findOneAndUpdate(
+      { id } as any,
+      { $set: { ...data, updatedAt: new Date() } } as any,
+      { returnDocument: "after" },
+    ) as Promise<T | null>;
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const result = await this.collection.deleteOne({ id } as any);
+    return result.deletedCount > 0;
+  }
+}
+
+// --- Dynamic Schema Generator ---
+
+export type FieldType = "string" | "number" | "boolean" | "date";
+
+export interface CustomFieldConfig {
+  key: string;
+  type: FieldType;
+  label: string;
+}
+
+export interface EntryFormatConfig {
+  requiredFields?: string[];
+  customFields?: CustomFieldConfig[];
+}
+
+export interface SettingsConfig {
+  databaseName: string;
+  entryFormat: EntryFormatConfig;
+}
+
+const CustomFieldSchema = z.object({
+  key: z.string().min(1),
+  type: z.enum(["string", "number", "boolean", "date"]),
+  label: z.string().min(1),
+});
+
+export const CAPSettingsSchema = z.object({
+  databaseName: z.string().min(1),
+  entryFormat: z.object({
+    requiredFields: z.array(z.string()).optional(),
+    customFields: z.array(CustomFieldSchema).optional(),
+  }),
+});
+
+function zodTypeForFieldType(fieldType: FieldType): z.ZodType {
+  switch (fieldType) {
+    case "string":
+      return z.string();
+    case "number":
+      return z.number();
+    case "boolean":
+      return z.boolean();
+    case "date":
+      return z.string().datetime();
+    default:
+      throw new Error(`Unknown field type: ${fieldType}`);
+  }
+}
+
+export function generateDynamicSchema(
+  customFields: CustomFieldConfig[],
+): z.ZodObject<z.ZodRawShape> {
+  const shape: Record<string, z.ZodType> = {};
+
+  for (const field of customFields) {
+    shape[field.key] = zodTypeForFieldType(field.type);
+  }
+
+  return CAPBaseSchema.extend(shape);
+}
+
+export function loadSettings(path: string): SettingsConfig {
+  const raw = readFileSync(path, "utf-8");
+  const parsed = JSON.parse(raw);
+  return CAPSettingsSchema.parse(parsed) as SettingsConfig;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+  },
+  "include": ["src/**/*"],
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});