@appsoftwareltd/etherpk-mcp 0.18.5 → 0.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -237,7 +237,7 @@ install the package globally once with `npm install -g @appsoftwareltd/etherpk-m
237
237
  | `semantic remove` | Delete the runtime and model. Stored embeddings stay, and are reused if you set up again. |
238
238
  | `publish (--graph <id or name> \| --folder <path>) --publication <id> [--out <dir> \| --github <owner/name[#branch]> \| --dry-run] [--replace]` | Publish one publication of a graph to a folder, or as a commit to a GitHub repository, and print the report. |
239
239
  | `diagrams setup` | Install a Chromium into the cache directory, so a publish can draw Mermaid diagrams, maps and drawings. |
240
- | `diagrams status` | Which browser a publish would use, if any. |
240
+ | `diagrams status` | Which browser a publish would use, if any, and whether it starts from this terminal. Exits with 1 and the browser's error when it does not start. |
241
241
 
242
242
  ### Flags
243
243
 
package/dist/main.js CHANGED
@@ -714,7 +714,7 @@ function looksLikeAgentSetupCode(value) {
714
714
  }
715
715
  var package_default = {
716
716
  name: "@appsoftwareltd/etherpk-mcp",
717
- version: "0.18.5",
717
+ version: "0.19.1",
718
718
  license: "Elastic-2.0",
719
719
  description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
720
720
  type: "module",
@@ -859,7 +859,7 @@ function fromBase64Url(text) {
859
859
  * is indistinguishable from random, so the server can tell two assets in *one* graph are
860
860
  * identical and nothing more; the secret is per graph, so nothing compares across graphs.
861
861
  */
862
- var INFO$1 = "etherpk/asset-dedup/v1";
862
+ var INFO$2 = "etherpk/asset-dedup/v1";
863
863
  /** The graph's dedup secret (32 bytes) for its newest epoch. Derive once per epoch. */
864
864
  async function deriveAssetDedupSecret(keyring) {
865
865
  const newest = keyring.epochs.at(-1);
@@ -869,7 +869,7 @@ async function deriveAssetDedupSecret(keyring) {
869
869
  name: "HKDF",
870
870
  hash: "SHA-256",
871
871
  salt: utf8(keyring.graphId),
872
- info: utf8(INFO$1)
872
+ info: utf8(INFO$2)
873
873
  }, ikm, 256);
874
874
  return new Uint8Array(bits);
875
875
  }
@@ -1545,7 +1545,7 @@ contextAad("settings-vault", "v1");
1545
1545
  * epoch, so every member derives the same id. The server sees document ids already, and without
1546
1546
  * the key an id is indistinguishable from a random one, so it learns no day from it.
1547
1547
  */
1548
- var INFO = "etherpk/journal-doc-id/v1";
1548
+ var INFO$1 = "etherpk/journal-doc-id/v1";
1549
1549
  var DAY = /^\d{4}-\d{2}-\d{2}$/;
1550
1550
  /** The graph's journal id secret (32 bytes). It never changes, so derive it once per session. */
1551
1551
  async function deriveJournalIdSecret(keyring) {
@@ -1556,7 +1556,7 @@ async function deriveJournalIdSecret(keyring) {
1556
1556
  name: "HKDF",
1557
1557
  hash: "SHA-256",
1558
1558
  salt: utf8(keyring.graphId),
1559
- info: utf8(INFO)
1559
+ info: utf8(INFO$1)
1560
1560
  }, ikm, 256);
1561
1561
  return new Uint8Array(bits);
1562
1562
  }
@@ -8218,6 +8218,73 @@ async function findGraphByName(records, vault, wanted, readMeta) {
8218
8218
  }
8219
8219
  return null;
8220
8220
  }
8221
+ var MAX_NAME = 300;
8222
+ var isText = (value) => typeof value === "string" && value !== "";
8223
+ var isWhole = (value) => typeof value === "number" && Number.isInteger(value) && value >= 1;
8224
+ function sanitizeOne(raw) {
8225
+ if (typeof raw !== "object" || raw === null) return null;
8226
+ const { id, hash, target, name, page, createdAt } = raw;
8227
+ if (!isText(id) || !isText(target) || !isText(name) || typeof hash !== "string" || !/^[0-9a-f]{64}$/.test(hash)) return null;
8228
+ if (!isWhole(page) || typeof createdAt !== "number") return null;
8229
+ return {
8230
+ id,
8231
+ hash,
8232
+ target,
8233
+ name: name.slice(0, MAX_NAME),
8234
+ page,
8235
+ createdAt
8236
+ };
8237
+ }
8238
+ /** Keep the well-formed entries, the first of each id. */
8239
+ function sanitizePdfBookmarks(raw) {
8240
+ if (!Array.isArray(raw)) return [];
8241
+ const seen = /* @__PURE__ */ new Set();
8242
+ const out = [];
8243
+ for (const entry of raw) {
8244
+ const clean = sanitizeOne(entry);
8245
+ if (clean && !seen.has(clean.id) && out.length < 2e3) {
8246
+ seen.add(clean.id);
8247
+ out.push(clean);
8248
+ }
8249
+ }
8250
+ return out;
8251
+ }
8252
+ Promise.resolve();
8253
+ // ../client/src/lib/document/pdf/state-doc-id.ts
8254
+ /**
8255
+ * The document id of a person's private document for one PDF: derived as a [[Journal Entry]]'s is
8256
+ * (`journal-doc-id.ts`, ADR 0157), so each of their devices reaches the same document with nothing
8257
+ * stored in the root document to find it by. The id comes from the epoch 1 key, so it does not
8258
+ * change when the graph moves to a new Graph Key epoch. Without the key an id looks random, so the
8259
+ * server learns neither the person nor the PDF from it.
8260
+ *
8261
+ * secret = HKDF-SHA-256(ikm = epoch 1 key, salt = graph id, info = 'etherpk/pdf-state-doc-id/v1')
8262
+ * id = HMAC-SHA-256(secret, '<member>:<hash>'), first 128 bits, as a version 8 UUID
8263
+ */
8264
+ var INFO = "etherpk/pdf-state-doc-id/v1";
8265
+ async function derivePdfStateIdSecret(keyring) {
8266
+ const first = keyForEpoch(keyring, 1);
8267
+ if (!first) throw new Error("derivePdfStateIdSecret: keyring has no epoch 1 key");
8268
+ const ikm = await crypto.subtle.importKey("raw", first, "HKDF", false, ["deriveBits"]);
8269
+ const bits = await crypto.subtle.deriveBits({
8270
+ name: "HKDF",
8271
+ hash: "SHA-256",
8272
+ salt: utf8(keyring.graphId),
8273
+ info: utf8(INFO)
8274
+ }, ikm, 256);
8275
+ return new Uint8Array(bits);
8276
+ }
8277
+ async function pdfStateDocId(secret, member, hash) {
8278
+ const key = await crypto.subtle.importKey("raw", secret, {
8279
+ name: "HMAC",
8280
+ hash: "SHA-256"
8281
+ }, false, ["sign"]);
8282
+ const bytes = new Uint8Array(await crypto.subtle.sign("HMAC", key, utf8(`${member}:${hash}`))).slice(0, 16);
8283
+ bytes[6] = bytes[6] & 15 | 128;
8284
+ bytes[8] = bytes[8] & 63 | 128;
8285
+ const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
8286
+ return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
8287
+ }
8221
8288
  // ../client/src/lib/diagnostics/performance.ts
8222
8289
  function assertSafeName(name) {
8223
8290
  if (!/^[a-z0-9][a-z0-9._-]*$/u.test(name)) throw new Error("Performance metric names may contain only lower-case stable identifiers");
@@ -10126,15 +10193,17 @@ function sanitizeFavourite(raw) {
10126
10193
  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
10127
10194
  return sanitizeViewFavourite(raw);
10128
10195
  }
10129
- function sanitizeViewFavourite({ kind, concept }) {
10196
+ function sanitizeViewFavourite({ kind, concept, name }) {
10130
10197
  if (typeof kind !== "string") return null;
10131
10198
  const cleanKind = kind.trim();
10132
10199
  if (cleanKind === "" || cleanKind.length > MAX_KIND) return null;
10133
10200
  if (concept === void 0) return { kind: cleanKind };
10134
10201
  if (typeof concept !== "string" || concept.trim() === "") return null;
10202
+ const cleanName = typeof name === "string" && name.trim() !== "" ? name.trim() : void 0;
10135
10203
  return {
10136
10204
  kind: cleanKind,
10137
- concept: concept.trim()
10205
+ concept: concept.trim(),
10206
+ ...cleanName ? { name: cleanName } : {}
10138
10207
  };
10139
10208
  }
10140
10209
  /**
@@ -10243,14 +10312,18 @@ var MEMBER_LIST_KINDS = [
10243
10312
  "favourites",
10244
10313
  "quickNotes",
10245
10314
  "bookmarks",
10246
- "memberFlags"
10315
+ "memberFlags",
10316
+ "pdfStates",
10317
+ "pdfBookmarks"
10247
10318
  ];
10248
10319
  /** Which Yjs type each kind is, so a type received but never asked for by name is read as the right one. */
10249
10320
  var MEMBER_LIST_IS_ARRAY = {
10250
10321
  favourites: true,
10251
10322
  quickNotes: true,
10252
10323
  bookmarks: false,
10253
- memberFlags: false
10324
+ memberFlags: false,
10325
+ pdfStates: false,
10326
+ pdfBookmarks: false
10254
10327
  };
10255
10328
  /** `kind` and member key of a per-member type's name, or null for any other root-doc type. */
10256
10329
  function memberListName(name) {
@@ -11330,6 +11403,7 @@ function createGraphSync(deps) {
11330
11403
  }
11331
11404
  connect();
11332
11405
  let journalIdSecret;
11406
+ let pdfStateIdSecret;
11333
11407
  return {
11334
11408
  rootDoc: root.doc,
11335
11409
  docSync: (docId) => engine(docId),
@@ -11386,6 +11460,39 @@ function createGraphSync(deps) {
11386
11460
  compactDoc: (docId) => deps.cache.docCache(docId).compact(),
11387
11461
  uploadSnapshot: (docId) => engine(docId).compact(),
11388
11462
  registry: () => registryMap,
11463
+ pdfBookmarks(member) {
11464
+ requireMemberKey(member, "pdfBookmarks");
11465
+ const map = root.doc.getMap(`pdfBookmarks:${member}`);
11466
+ return {
11467
+ list: () => sanitizePdfBookmarks([...map.values()]),
11468
+ apply(change) {
11469
+ root.doc.transact(() => {
11470
+ for (const id of change.remove) map.delete(id);
11471
+ for (const bookmark of change.put) map.set(bookmark.id, bookmark);
11472
+ });
11473
+ },
11474
+ observe(listener) {
11475
+ map.observe(listener);
11476
+ return () => map.unobserve(listener);
11477
+ }
11478
+ };
11479
+ },
11480
+ pdfStateIndex(member) {
11481
+ const map = root.doc.getMap(`pdfStates:${member}`);
11482
+ return {
11483
+ hashes: () => [...map.keys()],
11484
+ add(hash) {
11485
+ if (!map.has(hash)) map.set(hash, Date.now());
11486
+ },
11487
+ remove(hash) {
11488
+ map.delete(hash);
11489
+ }
11490
+ };
11491
+ },
11492
+ pdfStateDocId(member, hash) {
11493
+ pdfStateIdSecret ??= derivePdfStateIdSecret(keyring());
11494
+ return pdfStateIdSecret.then((secret) => pdfStateDocId(secret, member, hash));
11495
+ },
11389
11496
  journalDocId(date) {
11390
11497
  journalIdSecret ??= deriveJournalIdSecret(keyring());
11391
11498
  return journalIdSecret.then((secret) => journalDocId(secret, date));
@@ -14713,11 +14820,13 @@ function createDocumentRenderer(options) {
14713
14820
  const defaultLinkOpen = md.renderer.rules.link_open ?? ((tokens, idx, opts, _env, self) => self.renderToken(tokens, idx, opts));
14714
14821
  md.renderer.rules.link_open = (tokens, idx, opts, env, self) => {
14715
14822
  const token = tokens[idx];
14716
- const name = assetNameOf(String(token.attrGet("href") ?? ""));
14823
+ const href = String(token.attrGet("href") ?? "");
14824
+ const name = assetNameOf(href);
14717
14825
  if (name !== null) {
14718
14826
  const rewritten = options.assetHref(name);
14719
14827
  if (rewritten !== null) {
14720
- token.attrSet("href", rewritten);
14828
+ const fragment = href.indexOf("#");
14829
+ token.attrSet("href", fragment === -1 ? rewritten : `${rewritten}${href.slice(fragment)}`);
14721
14830
  if (!state.assets.includes(name)) state.assets.push(name);
14722
14831
  }
14723
14832
  }
@@ -16416,6 +16525,26 @@ async function launchChromium(env) {
16416
16525
  });
16417
16526
  }
16418
16527
  /**
16528
+ * What a failed launch reports: the lines the browser wrote to stderr, each once, or the message's
16529
+ * first line when it wrote none. Playwright's message around them is its own log of the launch.
16530
+ */
16531
+ function browserLogErrors(message) {
16532
+ const said = [...message.split("Call log:")[0].matchAll(/\[pid=\d+\]\[err\] (.*)/g)].map((match) => match[1]);
16533
+ return said.length > 0 ? [...new Set(said)].join("\n") : message.split("\n")[0];
16534
+ }
16535
+ /**
16536
+ * Why the browser a publish would use does not start, or null when it starts or there is none. A file
16537
+ * that exists can still fail to run: a missing library, or a library path this process inherited.
16538
+ */
16539
+ async function chromiumStartFailure(env) {
16540
+ try {
16541
+ await (await launchChromium(env))?.close();
16542
+ return null;
16543
+ } catch (error) {
16544
+ return browserLogErrors(error instanceof Error ? error.message : String(error));
16545
+ }
16546
+ }
16547
+ /**
16419
16548
  * A renderer over one headless browser, opened for a publish and closed after it. Null when no
16420
16549
  * browser is available; the caller decides what that means (a publish with diagrams refuses).
16421
16550
  */
@@ -17689,6 +17818,13 @@ function createAssetStore(adapter) {
17689
17818
  dispose() {
17690
17819
  for (const url of urlCache.values()) URL.revokeObjectURL(url);
17691
17820
  urlCache.clear();
17821
+ },
17822
+ renamed(from, to) {
17823
+ const url = urlCache.get(from);
17824
+ if (url) URL.revokeObjectURL(url);
17825
+ urlCache.delete(from);
17826
+ const parsed = assetHashFromName(to);
17827
+ if (parsed) contentIndex?.set(contentKey(parsed.hash, parsed.ext), to);
17692
17828
  }
17693
17829
  };
17694
17830
  }
@@ -17886,7 +18022,7 @@ async function sha256Hex(bytes) {
17886
18022
  * on the Asset rather than on whichever reference opened it — and that has to resolve too.
17887
18023
  */
17888
18024
  function assetIdFromRef(ref) {
17889
- const file = ref.split("/").pop() ?? ref;
18025
+ const file = ref.split(/[?#]/)[0].split("/").pop() ?? ref;
17890
18026
  const m = /(?:^|\.)([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:\.[^.]+)?$/.exec(file);
17891
18027
  return m ? m[1] : null;
17892
18028
  }
@@ -18059,6 +18195,19 @@ function createServerAssetStore(deps) {
18059
18195
  console.warn(`[assets] could not keep a copy of ${assetId} on this device`, error);
18060
18196
  });
18061
18197
  }
18198
+ /** The chunks at signed addresses, in order, or null when storage refuses one for good. */
18199
+ async function downloadChunks(downloadUrls) {
18200
+ const encrypted = [];
18201
+ for (const url of downloadUrls) {
18202
+ const chunkRes = await readRequest(url);
18203
+ if (!chunkRes.ok) {
18204
+ if (chunkRes.status !== 401 && isTransientStatus(chunkRes.status)) throw new AssetUnavailableError(`Storage could not hand over the file just now (HTTP ${chunkRes.status}).`, { status: chunkRes.status });
18205
+ return null;
18206
+ }
18207
+ encrypted.push(new Uint8Array(await chunkRes.arrayBuffer()));
18208
+ }
18209
+ return encrypted;
18210
+ }
18062
18211
  async function fetchAssetBytesOnce(ref) {
18063
18212
  const assetId = assetIdFromRef(ref);
18064
18213
  if (!assetId) return null;
@@ -18068,15 +18217,8 @@ function createServerAssetStore(deps) {
18068
18217
  if (!body) return null;
18069
18218
  const metadata = await openMetadata(assetId, body.encryptedMetadata);
18070
18219
  if (typeof metadata.chunkCount === "number" && body.downloadUrls.length !== metadata.chunkCount) throw new AssetIntegrityError();
18071
- const encrypted = [];
18072
- for (let n = 0; n < body.downloadUrls.length; n++) {
18073
- const chunkRes = await readRequest(body.downloadUrls[n]);
18074
- if (!chunkRes.ok) {
18075
- if (chunkRes.status !== 401 && isTransientStatus(chunkRes.status)) throw new AssetUnavailableError(`Storage could not hand over the file just now (HTTP ${chunkRes.status}).`, { status: chunkRes.status });
18076
- return null;
18077
- }
18078
- encrypted.push(new Uint8Array(await chunkRes.arrayBuffer()));
18079
- }
18220
+ const encrypted = await downloadChunks(body.downloadUrls);
18221
+ if (!encrypted) return null;
18080
18222
  const asset = await openChunks(ref, assetId, metadata, encrypted);
18081
18223
  await keepCopy(assetId, {
18082
18224
  encryptedMetadata: body.encryptedMetadata,
@@ -18283,6 +18425,63 @@ function createServerAssetStore(deps) {
18283
18425
  });
18284
18426
  return saved(assetId, false);
18285
18427
  },
18428
+ async renameAsset(ref, name) {
18429
+ const assetId = assetIdFromRef(ref);
18430
+ const body = assetId ? await requestAsset(assetId) : null;
18431
+ if (!assetId || !body) throw new Error("The sync server no longer holds this file.");
18432
+ const metadata = await openMetadata(assetId, body.encryptedMetadata);
18433
+ const ring = keyring();
18434
+ const encryptedMetadata = toBase64Url(await sealSymmetric({
18435
+ key: currentEpoch(ring).key,
18436
+ epochId: currentEpoch(ring).epochId,
18437
+ plaintext: utf8(JSON.stringify({
18438
+ ...metadata,
18439
+ name
18440
+ })),
18441
+ aad: contextAad("asset-meta", `graph:${deps.graphId}`, `id:${assetId}`)
18442
+ }));
18443
+ await step(async (fresh) => {
18444
+ const res = await f(`${base}/api/v1/sync/assets/${deps.graphId}/${assetId}`, {
18445
+ method: "PATCH",
18446
+ headers: await authHeaders(fresh),
18447
+ body: JSON.stringify({ encryptedMetadata })
18448
+ });
18449
+ if (!res.ok) throw new HttpFailure(res.status, `Could not rename the file (HTTP ${res.status}).`);
18450
+ });
18451
+ await deps.copies?.updateMetadata(deps.graphId, assetId, encryptedMetadata);
18452
+ return name;
18453
+ },
18454
+ async currentName(ref) {
18455
+ const assetId = assetIdFromRef(ref);
18456
+ if (!assetId) return null;
18457
+ try {
18458
+ const body = await requestAsset(assetId);
18459
+ if (!body) return null;
18460
+ const { name } = await openMetadata(assetId, body.encryptedMetadata);
18461
+ await deps.copies?.updateMetadata(deps.graphId, assetId, body.encryptedMetadata);
18462
+ return name;
18463
+ } catch {
18464
+ return null;
18465
+ }
18466
+ },
18467
+ async keptOnDevice(ref) {
18468
+ const assetId = assetIdFromRef(ref);
18469
+ return assetId && deps.copies ? deps.copies.isPinned(deps.graphId, assetId) : false;
18470
+ },
18471
+ async setKeptOnDevice(ref, keep) {
18472
+ const assetId = assetIdFromRef(ref);
18473
+ const copies = deps.copies;
18474
+ if (!assetId || !copies) throw new Error("This device cannot keep files.");
18475
+ if (await copies.setPinned(deps.graphId, assetId, keep)) return;
18476
+ if (!keep) return;
18477
+ const body = await requestAsset(assetId);
18478
+ const chunks = body ? await downloadChunks(body.downloadUrls) : null;
18479
+ if (!body || !chunks) throw new Error("The file could not be fetched just now, so it was not kept.");
18480
+ await copies.keep(deps.graphId, assetId, {
18481
+ encryptedMetadata: body.encryptedMetadata,
18482
+ chunks
18483
+ }, { pinned: true });
18484
+ },
18286
18485
  uploadQueued() {
18287
18486
  sending ??= sendQueued().finally(() => {
18288
18487
  sending = null;
@@ -26218,8 +26417,8 @@ function createServerDocumentStore(graph, options) {
26218
26417
  const unobserveDocUpdates = graph.onDocUpdate((docId) => {
26219
26418
  if (graph.docSync(docId).doc === graph.rootDoc) return;
26220
26419
  const entry = entryFor(docId);
26221
- const change = entry ? { concept: conceptOf(entry) } : void 0;
26222
- changeListeners.forEach((l) => l(change));
26420
+ if (!entry) return;
26421
+ changeListeners.forEach((l) => l({ concept: conceptOf(entry) }));
26223
26422
  });
26224
26423
  /** Find the registry docId whose concept matches `target` (case-insensitive). */
26225
26424
  function docIdFor(target) {
@@ -28630,7 +28829,8 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
28630
28829
  diagrams, maps or drawings refuses until this has run. Set ETHERPK_CHROMIUM=<path> to use a browser
28631
28830
  already on this machine instead (NixOS needs this).
28632
28831
  ${CMD} diagrams status
28633
- Which browser a publish would use, if any.
28832
+ Which browser a publish would use, if any, and whether it starts from this terminal. An agent's
28833
+ publish runs in the graph's background process, with the environment of the agent that started it.
28634
28834
 
28635
28835
  This machine can hold logins for several Sync Servers at once. The --sync-server flag says
28636
28836
  which one a command means, and can be left out while there is only one. The config file is
@@ -29012,8 +29212,17 @@ async function diagramsCommand(what) {
29012
29212
  return;
29013
29213
  case "status": {
29014
29214
  const status = await chromiumStatus(process.env, CMD);
29015
- if (status.executable) console.log(`Chromium: ${status.executable} (${status.source === "env" ? "from ETHERPK_CHROMIUM" : "installed by diagrams setup"}). A publish can draw Mermaid diagrams and maps.`);
29016
- else console.log(status.source === "env" ? `ETHERPK_CHROMIUM is set but names no file: ${process.env.ETHERPK_CHROMIUM}` : `No browser is set up. Run: ${status.setupCommand}`);
29215
+ if (!status.executable) {
29216
+ console.log(status.source === "env" ? `ETHERPK_CHROMIUM is set but names no file: ${process.env.ETHERPK_CHROMIUM}` : `No browser is set up. Run: ${status.setupCommand}`);
29217
+ return;
29218
+ }
29219
+ const browser = `Chromium: ${status.executable} (${status.source === "env" ? "from ETHERPK_CHROMIUM" : "installed by diagrams setup"})`;
29220
+ const failure = await chromiumStartFailure(process.env);
29221
+ if (failure === null) console.log(`${browser} started. A publish can draw Mermaid diagrams, maps and drawings.`);
29222
+ else {
29223
+ console.log(`${browser} did not start, so a publish cannot draw Mermaid diagrams, maps or drawings:\n${failure}`);
29224
+ process.exitCode = 1;
29225
+ }
29017
29226
  return;
29018
29227
  }
29019
29228
  default: fail(`diagrams needs one of: setup, status.\n\n${USAGE}`);