@kelceyp/caw-server 1.0.245 → 1.0.249

package/README.md

@@ -1,198 +1,22 @@
-# CAW Server
+# @kelceyp/caw-server
 
-The CAW server provides REST API, MCP server, WebSocket bridge, and core content management features.
+You probably want **[`@kelceyp/caw`](https://www.npmjs.com/package/@kelceyp/caw)**, which installs, launches and manages this server for you.
 
-## Overview
+`@kelceyp/caw-server` is the backing server component of [CAW](https://www.npmjs.com/package/@kelceyp/caw): a REST API, an MCP server, the web UI static assets, and a SQLite-backed content store, packaged as one Node.js application.
 
-The server is the central component of CAW, providing:
+## Standalone install
 
-- **REST API** - HTTP endpoints for web client and CLI
-- **MCP Server** - HTTP MCP server for Claude Code integration
-- **WebSocket Bridge** - Real-time communication with browser extension tabs
-- **Core** - Business logic layer (services, stores, entities)
-- **Static File Hosting** - Serves the web client
-
-## Architecture
-
-```
-┌─────────────────────────────────────────┐
-│         API Layer (REST/MCP)            │  HTTP routes, MCP tools
-│  (api/, mcp/)                           │  Auth via Bearer tokens
-└─────────────────────────────────────────┘
-                  ↓
-┌─────────────────────────────────────────┐
-│            Server.js                    │  Express app setup
-│  (main.js)                              │  Port management
-└─────────────────────────────────────────┘
-                  ↓
-┌─────────────────────────────────────────┐
-│             Core Facade                 │  Token resolution
-│  (core/Core.js)                         │  Service caching
-│                                         │  Flat API
-└─────────────────────────────────────────┘
-                  ↓
-┌─────────────────────────────────────────┐
-│            Services Layer               │  Orchestration
-│  (core/services/)                       │  Business workflows
-│                                         │  Multi-store coordination
-└─────────────────────────────────────────┘
-                  ↓
-┌─────────────────────────────────────────┐
-│             Stores Layer                │  Data access
-│  (core/stores/)                         │  Identity Map caching
-│                                         │  CRUD operations
-└─────────────────────────────────────────┘
-                  ↓
-┌─────────────────────────────────────────┐
-│            Database Layer               │  SQLite
-│  (db/)                                  │  Kysely query builder
-└─────────────────────────────────────────┘
-```
-
-## Directory Structure
-
-```
-server/
-├── src/
-│   ├── main.js              # Entry point, server initialization
-│   ├── Server.js            # Express app factory
-│   ├── api/                 # REST API routes
-│   │   ├── ProjectRoutes.js
-│   │   ├── FolderRoutes.js
-│   │   ├── DocumentRoutes.js
-│   │   ├── TemplateRoutes.js
-│   │   ├── FieldRoutes.js
-│   │   ├── ExportRoutes.js
-│   │   └── EventRoutes.js
-│   ├── core/                # Business logic layer
-│   │   ├── Core.js          # Facade - token resolution, service caching
-│   │   ├── entities/        # Domain objects (read-only)
-│   │   ├── services/        # Orchestration layer
-│   │   └── stores/          # Data access + caching
-│   ├── db/                  # Database layer
-│   │   ├── Connection.js    # Database connection factory
-│   │   ├── schema.js        # Table definitions
-│   │   └── seed.js          # Initial data seeding
-│   ├── mcp/                 # MCP server implementation
-│   ├── wss/                 # WebSocket server
-│   ├── static/              # Static files for web client
-│   └── common/              # Shared utilities
-└── test/                    # Test suites
-    ├── unit/                # In-memory unit tests
-    ├── integration/         # Real database integration tests
-    └── component/           # Black-box HTTP tests via subprocess
-```
-
-## Port Configuration
-
-The server uses the `CAW_PORT` environment variable:
-
-```bash
-CAW_PORT=2229 caw-server   # Default: 2229
-```
-
-## Building
-
-```bash
-# Build server only
-bun run build
-
-# Build client + server
-bun run build:all
-```
-
-Output: `dist/main.js` (ES6 module for Node.js)
-
-## Running
-
-```bash
-# Development (uses source files)
-bun run dev
-
-# Production (uses built files)
-node dist/main.js
-```
-
-## Testing
-
-```bash
-# Run all tests
-bun test
-
-# Run specific test suite
-bun test test/unit/
-bun test test/integration/
-bun test test/component/
-```
-
-Test types:
-- **Unit** - In-memory tests (entities, utilities)
-- **Integration** - Real database tests (stores, services)
-- **Component** - Black-box HTTP tests (API routes, MCP tools)
-
-## Tech Stack
-
-- **Pure JavaScript** - ES6 modules, factory functions only
-- **Express** - HTTP server framework
-- **Kysely** - SQL query builder (type-safe)
-- **better-sqlite3** - SQLite driver
-- **ws** - WebSocket server
-- **MCP SDK** - Model Context Protocol implementation
-- **Bun** - Build tool (development and bundling)
-
-## Distribution
-
-Published to npm as `@kelceyp/caw-server`:
+Most users should install the launcher instead — it handles lifecycle (start / stop / status / logs / upgrade), config, and integrations. If you have a specific reason to run the server directly:
 
 ```bash
-# Global install
 npm install -g @kelceyp/caw-server
-
-# Run
 caw-server
 ```
 
-## Key Features
-
-### Token-Based Authentication
-
-All API and MCP requests use Bearer tokens:
-
-```bash
-Authorization: Bearer <project-token>
-```
-
-Core facade resolves tokens to project context and caches services per project.
-
-### Multi-Store System
-
-Projects use a hierarchical store structure:
-- **DemuxStore** - Routes operations to child stores
-- **LocalStore A** - Project-specific content
-- **LocalStore B** - Shared content across projects
-
-### Identity Map Caching
-
-Stores cache entities to ensure single object instance per ID:
-- Cache checked before database queries
-- Mutations update cache after DB commit (via onSuccess callbacks)
-- Referential equality guaranteed
-
-### Field System
+## Links
 
-Entity fields provide metadata storage:
-- In-memory only (not persisted)
-- Store-level defaults
-- Single-valued and multi-valued fields
-- Accessed via FieldService
+- [Report an Issue or request a Feature](https://github.com/kelceyp/caw-feedback/issues)
 
-## Development
+## License
 
-See individual component READMEs:
-- `/core/README.md` - Core architecture
-- `/core/entities/README.md` - Domain entities
-- `/core/services/README.md` - Service layer
-- `/core/stores/README.md` - Data access layer
-- `/api/README.md` - REST API routes
-- `/db/README.md` - Database layer
-- `/test/README.md` - Testing guide
+Proprietary. All rights reserved.

package/dist/cli.js

@@ -10142,14 +10142,17 @@ var create73 = ({ httpClient }) => {
 };
 var cancel_resume_default = Object.freeze({ create: create73 });
 
-// src/commands/export/list.js
+// src/commands/bundle/list.js
 var create74 = ({ httpClient }) => {
-  return createCommand("list").summary("List available export files").param((p) => p.name("sid").type("string").flag("sid", "s").required()).run(async (ctx) => {
-    const { sid } = ctx.params;
+  return createCommand("list").summary("List available bundles").param((p) => p.name("sid").type("string").flag("sid", "s").required()).param((p) => p.name("store").type("string").flag("store")).run(async (ctx) => {
+    const { sid, store } = ctx.params;
+    const args = {};
+    if (store !== undefined)
+      args.store = store;
     const result = await httpClient.post(`/cli/mcp-client/${sid}/dispatch`, {
       cwd: process.cwd(),
-      tool: "list_exports",
-      args: {}
+      tool: "list_bundles",
+      args
     });
     ctx.stdio.stdout.write(JSON.stringify(result, null, 2) + `
 `);
@@ -10157,16 +10160,32 @@ var create74 = ({ httpClient }) => {
 };
 var list_default5 = Object.freeze({ create: create74 });
 
-// src/commands/export/preview.js
+// src/commands/bundle/preview.js
+var splitIds = (value) => value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
 var create75 = ({ httpClient }) => {
-  return createCommand("preview").summary("Preview export").param((p) => p.name("sid").type("string").flag("sid", "s").required()).param((p) => p.name("store").type("string").flag("store")).run(async (ctx) => {
-    const { sid, store } = ctx.params;
-    const args = {};
+  return createCommand("preview").summary("Preview a bundle export (dependency walk)").param((p) => p.name("sid").type("string").flag("sid", "s").required()).param((p) => p.name("store").type("string").flag("store")).param((p) => p.name("pickedDocIds").type("string").flag("pickedDocIds")).param((p) => p.name("pickedTemplateIds").type("string").flag("pickedTemplateIds")).param((p) => p.name("pickedTrackIds").type("string").flag("pickedTrackIds")).param((p) => p.name("pickedFolderIds").type("string").flag("pickedFolderIds")).run(async (ctx) => {
+    const {
+      sid,
+      store,
+      pickedDocIds,
+      pickedTemplateIds,
+      pickedTrackIds,
+      pickedFolderIds
+    } = ctx.params;
+    const args = { commit: false };
+    if (pickedDocIds !== undefined)
+      args.pickedDocIds = splitIds(pickedDocIds);
+    if (pickedTemplateIds !== undefined)
+      args.pickedTemplateIds = splitIds(pickedTemplateIds);
+    if (pickedTrackIds !== undefined)
+      args.pickedTrackIds = splitIds(pickedTrackIds);
+    if (pickedFolderIds !== undefined)
+      args.pickedFolderIds = splitIds(pickedFolderIds);
     if (store !== undefined)
       args.store = store;
     const result = await httpClient.post(`/cli/mcp-client/${sid}/dispatch`, {
       cwd: process.cwd(),
-      tool: "export_preview",
+      tool: "export_bundle",
       args
     });
     ctx.stdio.stdout.write(JSON.stringify(result, null, 2) + `
@@ -10175,18 +10194,33 @@ var create75 = ({ httpClient }) => {
 };
 var preview_default = Object.freeze({ create: create75 });
 
-// src/commands/export/export.js
+// src/commands/bundle/export.js
+var splitIds2 = (value) => value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
 var create76 = ({ httpClient }) => {
-  return createCommand("export").summary("Export documents and templates").param((p) => p.name("sid").type("string").flag("sid", "s").required()).param((p) => p.name("confirm").type("boolean").flag("confirm")).param((p) => p.name("store").type("string").flag("store")).run(async (ctx) => {
-    const { sid, confirm, store } = ctx.params;
-    const args = {};
-    if (confirm !== undefined)
-      args.confirm = confirm;
+  return createCommand("export").summary("Export a bundle (commit)").param((p) => p.name("sid").type("string").flag("sid", "s").required()).param((p) => p.name("name").type("string").flag("name").required()).param((p) => p.name("store").type("string").flag("store")).param((p) => p.name("pickedDocIds").type("string").flag("pickedDocIds")).param((p) => p.name("pickedTemplateIds").type("string").flag("pickedTemplateIds")).param((p) => p.name("pickedTrackIds").type("string").flag("pickedTrackIds")).param((p) => p.name("pickedFolderIds").type("string").flag("pickedFolderIds")).run(async (ctx) => {
+    const {
+      sid,
+      name,
+      store,
+      pickedDocIds,
+      pickedTemplateIds,
+      pickedTrackIds,
+      pickedFolderIds
+    } = ctx.params;
+    const args = { commit: true, name };
+    if (pickedDocIds !== undefined)
+      args.pickedDocIds = splitIds2(pickedDocIds);
+    if (pickedTemplateIds !== undefined)
+      args.pickedTemplateIds = splitIds2(pickedTemplateIds);
+    if (pickedTrackIds !== undefined)
+      args.pickedTrackIds = splitIds2(pickedTrackIds);
+    if (pickedFolderIds !== undefined)
+      args.pickedFolderIds = splitIds2(pickedFolderIds);
     if (store !== undefined)
       args.store = store;
     const result = await httpClient.post(`/cli/mcp-client/${sid}/dispatch`, {
       cwd: process.cwd(),
-      tool: "export_documents",
+      tool: "export_bundle",
       args
     });
     ctx.stdio.stdout.write(JSON.stringify(result, null, 2) + `
@@ -10195,16 +10229,16 @@ var create76 = ({ httpClient }) => {
 };
 var export_default = Object.freeze({ create: create76 });
 
-// src/commands/export/import.js
+// src/commands/bundle/import.js
 var create77 = ({ httpClient }) => {
-  return createCommand("import").summary("Import documents and templates").param((p) => p.name("sid").type("string").flag("sid", "s").required()).param((p) => p.name("filename").type("string").flag("filename").required()).param((p) => p.name("store").type("string").flag("store")).run(async (ctx) => {
+  return createCommand("import").summary("Import a bundle (non-destructive)").param((p) => p.name("sid").type("string").flag("sid", "s").required()).param((p) => p.name("filename").type("string").flag("filename").required()).param((p) => p.name("store").type("string").flag("store")).run(async (ctx) => {
     const { sid, filename, store } = ctx.params;
     const args = { filename };
     if (store !== undefined)
       args.store = store;
     const result = await httpClient.post(`/cli/mcp-client/${sid}/dispatch`, {
       cwd: process.cwd(),
-      tool: "import_documents",
+      tool: "import_bundle",
       args
     });
     ctx.stdio.stdout.write(JSON.stringify(result, null, 2) + `
@@ -10213,8 +10247,26 @@ var create77 = ({ httpClient }) => {
 };
 var import_default = Object.freeze({ create: create77 });
 
-// src/commands/asset/read.js
+// src/commands/bundle/delete.js
 var create78 = ({ httpClient }) => {
+  return createCommand("delete").summary("Delete a bundle").param((p) => p.name("sid").type("string").flag("sid", "s").required()).param((p) => p.name("filename").type("string").flag("filename").required()).param((p) => p.name("store").type("string").flag("store")).run(async (ctx) => {
+    const { sid, filename, store } = ctx.params;
+    const args = { filename };
+    if (store !== undefined)
+      args.store = store;
+    const result = await httpClient.post(`/cli/mcp-client/${sid}/dispatch`, {
+      cwd: process.cwd(),
+      tool: "delete_bundle",
+      args
+    });
+    ctx.stdio.stdout.write(JSON.stringify(result, null, 2) + `
+`);
+  }).onError({ exitCode: 1 }).build();
+};
+var delete_default6 = Object.freeze({ create: create78 });
+
+// src/commands/asset/read.js
+var create79 = ({ httpClient }) => {
   return createCommand("read").summary("Read an asset").param((p) => p.name("sid").type("string").flag("sid", "s").required()).param((p) => p.name("id").type("string").flag("id").required()).run(async (ctx) => {
     const { sid, id } = ctx.params;
     const result = await httpClient.post(`/cli/mcp-client/${sid}/dispatch`, {
@@ -10226,10 +10278,10 @@ var create78 = ({ httpClient }) => {
 `);
   }).onError({ exitCode: 1 }).build();
 };
-var read_default2 = Object.freeze({ create: create78 });
+var read_default2 = Object.freeze({ create: create79 });
 
 // src/commands/backfill/content-refs.js
-var create79 = ({ httpClient }) => {
+var create80 = ({ httpClient }) => {
   return createCommand("content-refs").summary("Backfill content reference fields on existing versions").param((p) => p.name("sid").type("string").flag("sid", "s").required()).param((p) => p.name("store").type("string").flag("store")).param((p) => p.name("confirm").type("boolean").flag("confirm")).param((p) => p.name("skipPopulated").type("boolean").flag("skip-populated")).param((p) => p.name("batchSize").type("number").flag("batch-size")).run(async (ctx) => {
     const { sid, store, confirm, skipPopulated, batchSize } = ctx.params;
     const args = {};
@@ -10250,10 +10302,10 @@ var create79 = ({ httpClient }) => {
 `);
   }).onError({ exitCode: 1 }).build();
 };
-var content_refs_default = Object.freeze({ create: create79 });
+var content_refs_default = Object.freeze({ create: create80 });
 
 // src/commands/embeddings/reindex.js
-var create80 = ({ httpClient }) => {
+var create81 = ({ httpClient }) => {
   return createCommand("reindex").summary("Trigger a full embedding reindex").param((p) => p.name("sid").type("string").flag("sid", "s").required()).run(async (ctx) => {
     const { sid } = ctx.params;
     const result = await httpClient.post(`/cli/mcp-client/${sid}/dispatch`, {
@@ -10265,13 +10317,13 @@ var create80 = ({ httpClient }) => {
 `);
   }).onError({ exitCode: 1 }).build();
 };
-var reindex_default = Object.freeze({ create: create80 });
+var reindex_default = Object.freeze({ create: create81 });
 
 // src/cli-main.js
 var CAW_URL = process.env.CAW_URL || "http://localhost:2229";
 try {
   const httpClient = http_client_default.create({ baseUrl: CAW_URL });
-  const app = create().name("caw").version("0.0.1").command(connect_default.create({ httpClient })).command(disconnect_default.create({ httpClient })).group(createCommandGroup("doc").summary("Document operations").command(read_default.create({ httpClient })).command(create_default.create({ httpClient })).command(save_default.create({ httpClient })).command(publish_default.create({ httpClient })).command(read_by_path_default.create({ httpClient })).command(update_path_default.create({ httpClient })).command(versions_default.create({ httpClient })).command(read_version_default.create({ httpClient })).command(discard_default.create({ httpClient })).command(delete_default.create({ httpClient })).command(read_lines_default.create({ httpClient })).command(read_head_default.create({ httpClient })).command(read_tail_default.create({ httpClient })).command(read_from_line_default.create({ httpClient })).command(read_to_line_default.create({ httpClient })).command(read_between_markers_default.create({ httpClient })).command(read_section_default.create({ httpClient })).command(headings_default.create({ httpClient })).command(checklist_default.create({ httpClient })).command(stats_default.create({ httpClient })).command(frontmatter_default.create({ httpClient })).command(edit_default.create({ httpClient })).command(batch_edit_default.create({ httpClient })).command(check_item_default.create({ httpClient })).command(toggle_item_default.create({ httpClient })).command(batch_check_items_default.create({ httpClient })).command(set_edit_state_default.create({ httpClient })).command(clear_edit_state_default.create({ httpClient })).command(get_edit_state_default.create({ httpClient })).command(check_includes_default.create({ httpClient })).command(update_includes_default.create({ httpClient })).build()).group(createCommandGroup("folder").summary("Folder operations").command(list_default.create({ httpClient })).command(create_default2.create({ httpClient })).command(get_default.create({ httpClient })).command(get_by_path_default.create({ httpClient })).command(rename_default.create({ httpClient })).command(move_default.create({ httpClient })).command(delete_default2.create({ httpClient })).build()).group(createCommandGroup("field").summary("Field operations").command(get_default2.create({ httpClient })).command(get_field_default.create({ httpClient })).command(set_default.create({ httpClient })).command(delete_default3.create({ httpClient })).command(create_def_default.create({ httpClient })).command(list_defs_default.create({ httpClient })).command(get_type_fields_default.create({ httpClient })).command(delete_def_default.create({ httpClient })).build()).group(createCommandGroup("story").summary("Story operations").command(create_default3.create({ httpClient })).command(list_default2.create({ httpClient })).command(get_default3.create({ httpClient })).command(update_state_default.create({ httpClient })).command(change_track_default.create({ httpClient })).command(delete_default4.create({ httpClient })).command(inc_jobs_default.create({ httpClient })).command(dec_jobs_default.create({ httpClient })).build()).group(createCommandGroup("track").summary("Track operations").command(list_default3.create({ httpClient })).command(create_default4.create({ httpClient })).command(update_default.create({ httpClient })).command(delete_default5.create({ httpClient })).build()).group(createCommandGroup("template").summary("Template operations").command(create_default5.create({ httpClient })).command(render_default.create({ httpClient })).command(params_default.create({ httpClient })).command(list_by_type_default.create({ httpClient })).build()).group(createCommandGroup("job").summary("Job operations").command(list_default4.create({ httpClient })).command(get_default4.create({ httpClient })).command(create_default6.create({ httpClient })).command(continue_default.create({ httpClient })).command(output_default.create({ httpClient })).command(prompt_default.create({ httpClient })).command(cancel_resume_default.create({ httpClient })).build()).group(createCommandGroup("export").summary("Export operations").command(list_default5.create({ httpClient })).command(preview_default.create({ httpClient })).command(export_default.create({ httpClient })).command(import_default.create({ httpClient })).build()).group(createCommandGroup("asset").summary("Asset operations").command(read_default2.create({ httpClient })).build()).group(createCommandGroup("backfill").summary("Backfill operations").command(content_refs_default.create({ httpClient })).build()).group(createCommandGroup("embeddings").summary("Embedding operations").command(reindex_default.create({ httpClient })).build());
+  const app = create().name("caw").version("0.0.1").command(connect_default.create({ httpClient })).command(disconnect_default.create({ httpClient })).group(createCommandGroup("doc").summary("Document operations").command(read_default.create({ httpClient })).command(create_default.create({ httpClient })).command(save_default.create({ httpClient })).command(publish_default.create({ httpClient })).command(read_by_path_default.create({ httpClient })).command(update_path_default.create({ httpClient })).command(versions_default.create({ httpClient })).command(read_version_default.create({ httpClient })).command(discard_default.create({ httpClient })).command(delete_default.create({ httpClient })).command(read_lines_default.create({ httpClient })).command(read_head_default.create({ httpClient })).command(read_tail_default.create({ httpClient })).command(read_from_line_default.create({ httpClient })).command(read_to_line_default.create({ httpClient })).command(read_between_markers_default.create({ httpClient })).command(read_section_default.create({ httpClient })).command(headings_default.create({ httpClient })).command(checklist_default.create({ httpClient })).command(stats_default.create({ httpClient })).command(frontmatter_default.create({ httpClient })).command(edit_default.create({ httpClient })).command(batch_edit_default.create({ httpClient })).command(check_item_default.create({ httpClient })).command(toggle_item_default.create({ httpClient })).command(batch_check_items_default.create({ httpClient })).command(set_edit_state_default.create({ httpClient })).command(clear_edit_state_default.create({ httpClient })).command(get_edit_state_default.create({ httpClient })).command(check_includes_default.create({ httpClient })).command(update_includes_default.create({ httpClient })).build()).group(createCommandGroup("folder").summary("Folder operations").command(list_default.create({ httpClient })).command(create_default2.create({ httpClient })).command(get_default.create({ httpClient })).command(get_by_path_default.create({ httpClient })).command(rename_default.create({ httpClient })).command(move_default.create({ httpClient })).command(delete_default2.create({ httpClient })).build()).group(createCommandGroup("field").summary("Field operations").command(get_default2.create({ httpClient })).command(get_field_default.create({ httpClient })).command(set_default.create({ httpClient })).command(delete_default3.create({ httpClient })).command(create_def_default.create({ httpClient })).command(list_defs_default.create({ httpClient })).command(get_type_fields_default.create({ httpClient })).command(delete_def_default.create({ httpClient })).build()).group(createCommandGroup("story").summary("Story operations").command(create_default3.create({ httpClient })).command(list_default2.create({ httpClient })).command(get_default3.create({ httpClient })).command(update_state_default.create({ httpClient })).command(change_track_default.create({ httpClient })).command(delete_default4.create({ httpClient })).command(inc_jobs_default.create({ httpClient })).command(dec_jobs_default.create({ httpClient })).build()).group(createCommandGroup("track").summary("Track operations").command(list_default3.create({ httpClient })).command(create_default4.create({ httpClient })).command(update_default.create({ httpClient })).command(delete_default5.create({ httpClient })).build()).group(createCommandGroup("template").summary("Template operations").command(create_default5.create({ httpClient })).command(render_default.create({ httpClient })).command(params_default.create({ httpClient })).command(list_by_type_default.create({ httpClient })).build()).group(createCommandGroup("job").summary("Job operations").command(list_default4.create({ httpClient })).command(get_default4.create({ httpClient })).command(create_default6.create({ httpClient })).command(continue_default.create({ httpClient })).command(output_default.create({ httpClient })).command(prompt_default.create({ httpClient })).command(cancel_resume_default.create({ httpClient })).build()).group(createCommandGroup("bundle").summary("Bundle operations").command(list_default5.create({ httpClient })).command(preview_default.create({ httpClient })).command(export_default.create({ httpClient })).command(import_default.create({ httpClient })).command(delete_default6.create({ httpClient })).build()).group(createCommandGroup("asset").summary("Asset operations").command(read_default2.create({ httpClient })).build()).group(createCommandGroup("backfill").summary("Backfill operations").command(content_refs_default.create({ httpClient })).build()).group(createCommandGroup("embeddings").summary("Embedding operations").command(reindex_default.create({ httpClient })).build());
   await app.run(process.argv.slice(2));
 } catch (error) {
   console.error(`Error: ${error.message}`);