several fixes

Author: rozek

README.md

@@ -2,6 +2,8 @@
 
 A CRDT-based, offline-capable, real-time-syncable **tree-of-data** library for Browser and Node.js.
 
+## work-in-progress - please ignore for the moment
+
 Data Items are organised in a hierarchy (with optional links between them), can carry arbitrary typed values (text, binary, large blobs), and synchronise across devices and users without conflicts — even when peers are offline for extended periods. The library is split into small, composable packages so you can use only what you need.
 
 The CRDT engine is **pluggable**: choose from three ready-made backends or write your own: [Y.js](https://yjs.dev/), [Loro CRDT](https://loro.dev/) or [JSON JOY](https://jsonjoy.com/).
@@ -64,7 +66,7 @@ All three backend packages expose an **identical public API**. Import from which
 | `@rozek/sds-sidecar-loro` | `sds-sidecar-loro` | Loro |
 | `@rozek/sds-sidecar-yjs` | `sds-sidecar-yjs` | Y.js |
 
-Each wrapper is a thin ~40-line entry point that wires the corresponding `@rozek/sds-core-*` backend into the generic library. Install only the package matching your chosen CRDT backend.
+Each wrapper is a thin \~40-line entry point that wires the corresponding `@rozek/sds-core-*` backend into the generic library. Install only the package matching your chosen CRDT backend.
 
 ---
 

packages/sds-command-jj/src/tests/cli.test.ts

@@ -47,7 +47,7 @@ describe('CLI default behaviour (CL)', () => {
   it('CL-06: "help entry" shows entry subcommand help (not top-level help)', async () => {
     const Result = await runCLI(['help', 'entry'])
     expect(Result.ExitCode).toBe(0)
-    expect(Result.Stdout).toMatch(/sds entry/)        // entry-specific usage line
+    expect(Result.Stdout).toMatch(/sds\S* entry/)     // entry-specific usage line
     expect(Result.Stdout).toMatch(/create/)           // at least one entry subcommand listed
     expect(Result.Stderr).not.toMatch(/error/)
   })

packages/sds-command/dist/sds-command.d.ts

@@ -1,8 +1,4 @@
-/*******************************************************************************
-*                                                                              *
-*                             SDS Command CLI                                  *
-*                                                                              *
-*******************************************************************************/
+import { SDS_StoreFactory } from './StoreAccess.js';
 export type { SDS_StoreFactory } from './StoreAccess.js';
 /**** runCommand — called by backend-specific wrapper packages ****/
 export declare function runCommand(StoreFactory: SDS_StoreFactory, CommandName?: string, Version?: string): Promise<void>;

packages/sds-command/dist/sds-command.d.ts.map

@@ -354,7 +354,7 @@ function C(e, n, t, o = []) {
   for (const [r, s] of Object.entries(t))
     e[r] = s;
   for (const r of o)
-    e[r] = void 0;
+    delete e[r];
 }
 function Z(e) {
   const n = [];
@@ -1258,24 +1258,27 @@ async function V(e, n) {
   }
 }
 async function ze() {
-  const { CleanArgv: e, InfoEntries: n } = N(process.argv.slice(2)), t = Object.entries(n).flatMap(([r, s]) => [
-    `--info.${r}`,
-    JSON.stringify(s)
-  ]), o = O(t);
-  G(o);
+  const { CleanArgv: e, InfoEntries: n, InfoDeleteKeys: t } = N(process.argv.slice(2)), o = [
+    ...Object.entries(n).flatMap(([s, i]) => [
+      `--info.${s}`,
+      JSON.stringify(i)
+    ]),
+    ...t.map((s) => `--info-delete.${s}`)
+  ], r = O(o);
+  G(r);
   try {
-    await o.parseAsync(["node", E, ...e]);
-  } catch (r) {
-    const s = r;
-    if ((s.code === "commander.help" || s.code === "commander.helpDisplayed" || s.code === "commander.version") && process.exit(c.OK), (s.code === "commander.unknownCommand" || s.code === "commander.unknownOption" || s.code === "commander.missingArgument" || s.code === "commander.missingMandatoryOptionValue") && (process.stderr.write(`${E}: ${s.message}
+    await r.parseAsync(["node", E, ...e]);
+  } catch (s) {
+    const i = s;
+    if ((i.code === "commander.help" || i.code === "commander.helpDisplayed" || i.code === "commander.version") && process.exit(c.OK), (i.code === "commander.unknownCommand" || i.code === "commander.unknownOption" || i.code === "commander.missingArgument" || i.code === "commander.missingMandatoryOptionValue") && (process.stderr.write(`${E}: ${i.message}
 
-`), process.stderr.write(o.helpInformation()), process.exit(c.UsageError)), r instanceof R && (process.stderr.write(`${E}: ${r.message}
-`), process.exit(r.ExitCode)), r instanceof l) {
-      const a = w({});
-      P(a, r.message, r.ExitCode), process.exit(r.ExitCode);
+`), process.stderr.write(r.helpInformation()), process.exit(c.UsageError)), s instanceof R && (process.stderr.write(`${E}: ${s.message}
+`), process.exit(s.ExitCode)), s instanceof l) {
+      const d = w({});
+      P(d, s.message, s.ExitCode), process.exit(s.ExitCode);
     }
-    const i = w({});
-    P(i, r.message ?? String(r)), process.exit(c.GeneralError);
+    const a = w({});
+    P(a, s.message ?? String(s)), process.exit(c.GeneralError);
   }
 }
 async function ot(e, n = "sds", t = "0.0.0") {

packages/sds-command/dist/sds-command.js

@@ -144,6 +144,6 @@ export function applyInfoToEntry (
 
   // --info-delete.key: remove individual keys (already validated in extractInfoEntries)
   for (const Key of InfoDeleteKeys) {
-    InfoProxy[Key] = undefined
+    delete InfoProxy[Key]
   }
 }

packages/sds-command/src/InfoParser.ts

@@ -12,7 +12,7 @@ import { Command } from 'commander'
 import { resolveConfig, SDS_ConfigError } from './Config.js'
 import { printError }        from './Output.js'
 import { ExitCodes }         from './ExitCodes.js'
-import { SDS_CommandError, setStoreFactory } from './StoreAccess.js'
+import { SDS_CommandError, setStoreFactory, type SDS_StoreFactory } from './StoreAccess.js'
 import { extractInfoEntries } from './InfoParser.js'
 import { startREPL }         from './REPL.js'
 import { runScript }         from './ScriptRunner.js'
@@ -216,13 +216,16 @@ async function executeTokens (
 /**** main — CLI entry point ****/
 
 async function main ():Promise<void> {
-  // strip --info.<key> options before commander sees them; keep them for
-  // later injection into sub-command handlers via buildProgram(ExtraArgv)
-  const { CleanArgv, InfoEntries } = extractInfoEntries(process.argv.slice(2))
+  // strip --info.<key> and --info-delete.<key> options before commander sees them;
+  // keep them for later injection into sub-command handlers via buildProgram(ExtraArgv)
+  const { CleanArgv, InfoEntries, InfoDeleteKeys } = extractInfoEntries(process.argv.slice(2))
 
-  const ExtraArgv = Object.entries(InfoEntries).flatMap(([Key, Value]) => [
-    `--info.${Key}`, JSON.stringify(Value),
-  ])
+  const ExtraArgv = [
+    ...Object.entries(InfoEntries).flatMap(([Key, Value]) => [
+      `--info.${Key}`, JSON.stringify(Value),
+    ]),
+    ...InfoDeleteKeys.map((Key) => `--info-delete.${Key}`),
+  ]
 
   const Program = buildProgram(ExtraArgv)
   applyExitOverride(Program)

packages/sds-command/src/sds-command.ts

@@ -69,12 +69,12 @@ describe('resolveConfig / DBPathFor', () => {
   })
 
   it('CF-07: DBPathFor combines PersistenceDir and store ID into a .db path', () => {
-    const Config = resolveConfig({ dataDir:'/tmp/sds' })
+    const Config = resolveConfig({ persistenceDir:'/tmp/sds' })
     expect(DBPathFor(Config, 'valid-id_123')).toBe('/tmp/sds/valid-id_123.db')
   })
 
   it('CF-08: DBPathFor replaces chars outside [a-zA-Z0-9_-] in the store ID with _', () => {
-    const Config = resolveConfig({ dataDir:'/tmp/sds' })
+    const Config = resolveConfig({ persistenceDir:'/tmp/sds' })
     expect(DBPathFor(Config, 'my/store')).toBe('/tmp/sds/my_store.db')
     expect(DBPathFor(Config, 'test store')).toBe('/tmp/sds/test_store.db')
   })

packages/sds-command/src/tests/Config.test.ts

@@ -0,0 +1,196 @@
+# @rozek/sds-mcp-server-jj
+
+MCP (Model Context Protocol) server for the **shareable-data-store** (SDS) family — backed by the [json-joy](https://github.com/streamich/json-joy) CRDT engine. Exposes all SDS store and entry operations as MCP tools so that AI agents can manage CRDT stores, entries, items, links, tokens, and batch workflows through the standard MCP tool-calling interface.
+
+This package is the **runnable binary**. The tool definitions, handlers, and shared infrastructure live in [`@rozek/sds-mcp-server`](../sds-mcp-server/README.md); this package wires in the json-joy store factory and exposes the result as the `sds-mcp-server-jj` executable.
+
+---
+
+## Prerequisites
+
+| requirement | details |
+| --- | --- |
+| **Node.js 22.5+** | required to run the server. Download from [nodejs.org](https://nodejs.org). |
+| **MCP client** | any host that speaks the Model Context Protocol (Claude Desktop, custom agent, etc.) |
+| **SDS server** | only required for network operations (`sds_store_sync`, `sds_store_ping`, `sds_token_issue`). All local read/write tools work entirely offline against the SQLite file. |
+| **JWT tokens** | server operations need a client token (scope `read` or `write`) or an admin token (scope `admin`). Tokens are issued by the server's `POST /api/token` endpoint via `sds_token_issue`. |
+
+SQLite support is built directly into Node.js since version 22.5 via the `node:sqlite` module — no separate database driver, no native C++ addon, and no build toolchain is needed. The server binary therefore runs with **Node.js as its only dependency**.
+
+> **Note on stability:** `node:sqlite` is classified as *Stability 1 — Experimental* in the Node.js 22 and 24 documentation. In practice the API has been stable since its introduction. The server suppresses the associated runtime warning automatically.
+
+---
+
+## Installation
+
+```bash
+npm add @rozek/sds-mcp-server-jj
+```
+
+After installation the `sds-mcp-server-jj` command is available in the project's `node_modules/.bin/` directory.
+
+---
+
+## Running without Installation
+
+The package includes a `bin` entry, so it can be started directly via `npx` — no prior installation required:
+
+```bash
+npx @rozek/sds-mcp-server-jj
+```
+
+This is the recommended way to configure MCP hosts that manage servers themselves. Register the server in your MCP host configuration using `npx` as the command:
+
+**Claude Desktop (`claude_desktop_config.json`):**
+
+```json
+{
+  "mcpServers": {
+    "sds": {
+      "command": "npx",
+      "args": [ "-y", "@rozek/sds-mcp-server-jj" ]
+    }
+  }
+}
+```
+
+The `-y` flag skips the confirmation prompt when `npx` downloads the package. Remove it if you prefer to confirm each download.
+
+> **Note on Node.js version:** `npx` uses whatever `node` is on your `PATH`. Make sure it is version 22.5 or later before adding the server to a host configuration.
+
+---
+
+## Configuration (installed package)
+
+If you have installed `@rozek/sds-mcp-server-jj` locally or globally, register the built binary directly in your MCP host configuration:
+
+**Claude Desktop (`claude_desktop_config.json`):**
+
+```json
+{
+  "mcpServers": {
+    "sds": {
+      "command": "node",
+      "args": [ "/path/to/node_modules/@rozek/sds-mcp-server-jj/dist/sds-mcp-server-jj.js" ]
+    }
+  }
+}
+```
+
+The server communicates over **stdio** — no port, no HTTP server, no daemon is required.
+
+### Server-level defaults
+
+You can pre-configure default values for `StoreId`, `PersistenceDir`, `ServerURL`, `Token`, and `AdminToken` so that individual tool calls do not need to repeat them. There are two ways to do this — they can be combined freely, and **tool parameters always take precedence** over both.
+
+**CLI arguments** (passed in the `args` array of the MCP host config):
+
+| argument | applies to |
+| --- | --- |
+| `--store <id>` | default `StoreId` for all tools |
+| `--persistence-dir <path>` | default `PersistenceDir` for all tools |
+| `--server <url>` | default `ServerURL` for sync/token tools |
+| `--token <jwt>` | default client `Token` for sync tools |
+| `--admin-token <jwt>` | default `AdminToken` for `sds_token_issue` |
+
+**Environment variables** (set in the `env` block of the MCP host config, or in the shell):
+
+| variable | applies to |
+| --- | --- |
+| `SDS_STORE_ID` | default `StoreId` for all tools |
+| `SDS_PERSISTENCE_DIR` | default `PersistenceDir` for all tools |
+| `SDS_SERVER_URL` | default `ServerURL` for sync/token tools |
+| `SDS_TOKEN` | default client `Token` for sync tools |
+| `SDS_ADMIN_TOKEN` | default `AdminToken` for `sds_token_issue` |
+
+**Precedence** (highest to lowest): tool parameter → CLI argument → environment variable → built-in default (`~/.sds` for `PersistenceDir`).
+
+**Example — fixed store and data directory via CLI args:**
+
+```json
+{
+  "mcpServers": {
+    "sds": {
+      "command": "node",
+      "args": [
+        "/path/to/node_modules/@rozek/sds-mcp-server-jj/dist/sds-mcp-server-jj.js",
+        "--store",           "my-notes",
+        "--persistence-dir", "/home/alice/.my-sds-data"
+      ]
+    }
+  }
+}
+```
+
+**Example — sync server and token via environment variables:**
+
+```json
+{
+  "mcpServers": {
+    "sds": {
+      "command": "node",
+      "args": [ "/path/to/.../sds-mcp-server-jj.js" ],
+      "env": {
+        "SDS_SERVER_URL": "wss://sync.example.com",
+        "SDS_TOKEN":      "eyJhbGci..."
+      }
+    }
+  }
+}
+```
+
+---
+
+## Tool reference
+
+This package exposes 20 tools grouped into six categories. Full documentation for every tool — parameters, return values, error conditions, and examples — is in the [`@rozek/sds-mcp-server` README](../sds-mcp-server/README.md#tool-reference).
+
+| category | tools |
+| --- | --- |
+| **store** | `sds_store_info`, `sds_store_ping`, `sds_store_sync`, `sds_store_destroy`, `sds_store_export`, `sds_store_import` |
+| **entry** | `sds_entry_create`, `sds_entry_get`, `sds_entry_list`, `sds_entry_update`, `sds_entry_move`, `sds_entry_delete`, `sds_entry_restore`, `sds_entry_purge` |
+| **trash** | `sds_trash_list`, `sds_trash_purge_all`, `sds_trash_purge_expired` |
+| **tree** | `sds_tree_show` |
+| **token** | `sds_token_issue` |
+| **batch** | `sds_batch` |
+
+---
+
+## Examples
+
+### Local store — first steps
+
+```
+sds_entry_create  { StoreId: "notes", Label: "Recipes", MIMEType: "text/plain", Value: "Pasta: boil, sauce, enjoy" }
+sds_tree_show     { StoreId: "notes" }
+sds_entry_list    { StoreId: "notes", Id: "root", Fields: ["Label", "MIMEType"] }
+sds_entry_get     { StoreId: "notes", Id: "<uuid>" }
+```
+
+### Batch setup
+
+Initialise a folder structure in one round trip:
+
+```
+sds_batch {
+  StoreId:  "team-wiki",
+  Commands: [
+    { Tool: "sds_entry_create", Params: { Label: "Documentation", MIMEType: "text/plain" } },
+    { Tool: "sds_entry_create", Params: { Label: "Meeting Notes",  MIMEType: "text/plain" } },
+    { Tool: "sds_entry_create", Params: { Label: "Decisions",      MIMEType: "text/plain" } }
+  ]
+}
+```
+
+### Export and restore
+
+```
+sds_store_export  { StoreId: "notes", Encoding: "json", OutputFile: "/backups/notes.json" }
+sds_store_import  { StoreId: "notes-restored", InputFile: "/backups/notes.json", InputEncoding: "json" }
+```
+
+---
+
+## License
+
+[MIT License](../../LICENSE.md) © Andreas Rozek

packages/sds-mcp-server-jj/README.md

@@ -102,6 +102,7 @@ All tools are called via the MCP protocol through `StdioClientTransport`. Every
 | EL-05 | `recursive: true`, `Depth: 1` | nested children of top-level items not included |
 | EL-06 | `Fields: ["Label"]` | every entry has a `Label` field |
 | EL-07 | `InfoKeys: ["tag"]` | every entry has an `Info` object with only the `tag` key |
+| EL-08 | `only: "foobar"` (invalid value) | `isError: true`; message contains `'only'` |
 | EL-09 | link ID as container | `isError: true` |
 | EL-10 | `Id: "root"` output | Trash ID absent from result array |
 | EL-11 | `Id: "lost-and-found"` | alias resolves; `isError: false`; result is an array |
@@ -206,6 +207,8 @@ All tools are called via the MCP protocol through `StdioClientTransport`. Every
 | BA-06 | sync step with unreachable server, `onError: "continue"` | sync step `ok: false`; subsequent create step `ok: true` |
 | BA-07 | `StoreId` + `PersistenceDir` at batch level | commands without them use the correct store |
 | BA-08 | `sds_token_issue` in Commands (disallowed) | `isError: true` |
+| BA-09 | `sds_store_ping` in Commands (disallowed) | `isError: true` before any execution |
+| BA-10 | batch `sds_store_export` (JSON, no file) + `sds_store_import` (base64) into new store | both steps `ok: true`; imported store `EntryCount` equals exported |
 
 ## CF — Config Defaults