dsh-mnemon-source-documents 0.5.10 → 0.5.11

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
@@ -25,6 +25,10 @@ The `create` Action accepts `title`, `content`, and optional `description`, `sou
25
25
 
26
26
  `create` Action 接收 `title`、`content`,以及可选的 `description`、`sourcePaths`、`sessionIds`。它始终新建独立档案,拒绝 `action`、`id` 等 mutation 选择字段;容量不足时失败,不更新或归档已有档案。原有 `manage` Action 继续支持创建和更新。Mnemon 后台审查只获得仅创建档案工具,已有内容覆盖候选时跳过。本变更无需迁移档案格式。
27
27
 
28
+ ## Storage files
29
+
30
+ The `./contracts` entry names this Source's directory, index and lock under a storage root (`documents/`, `index.json`, `.index.lock`; each document lies in `active/` or `archived/` by its status) and exports `parseDocumentIndex`, which reads an index as a backup or sync carries it, and `summarizeDocumentIndex`, which counts one for an inventory. They are pure and browser-safe. The `dsh-mnemon` Starter's backup, sync and storage inventory use them instead of keeping copies.
31
+
28
32
  ## Source-owned UI and tests
29
33
 
30
34
  The optional `./client` entry is an ordinary DSH Client plugin. This package owns its pages and `presentation/` resources and uses `dsh-mnemon/client` for the shared frame and scoped management client. It never receives a Host Context, credentials or another Source's controller.
@@ -85,5 +85,41 @@ interface DocumentCapacityPlan {
85
85
  }
86
86
  declare const DOCUMENTS_VERSION = 1;
87
87
  declare const DOCUMENTS_ACTIVE_LIMIT_BYTES: number;
88
+ /** The Documents Source's directory under a storage root; each document sits in `<status>/<filename>` below it. */
89
+ declare const DOCUMENTS_DIRECTORY = "documents";
90
+ /** The metadata of every document, the source of truth for which files belong to the Source. */
91
+ declare const DOCUMENTS_INDEX_FILE = "index.json";
92
+ /** Created exclusively while the index or a document is read or written; whoever copies them takes it too. */
93
+ declare const DOCUMENTS_LOCK_FILE = ".index.lock";
94
+ /** A lock file older than this was left by a process that stopped, and may be taken over. */
95
+ declare const DOCUMENTS_LOCK_STALE_MS = 30000;
96
+ /** The file name a document may have: one path segment, so it never leaves its status directory. */
97
+ declare const DOCUMENT_FILENAME_PATTERN: RegExp;
98
+ interface DocumentIndex {
99
+ version: typeof DOCUMENTS_VERSION;
100
+ documents: DocumentRecord[];
101
+ }
102
+ /**
103
+ * Read an index as a copy of it carries it, such as a Mnemon Pack or a sync branch: every record
104
+ * complete, each id unique and each file name safe, or the whole index is refused. A record's path
105
+ * is where its status puts it, whatever the copy says. Unknown fields are dropped, and so are
106
+ * list items that are not strings. Reading the index does not judge a record's content hash: a
107
+ * store that needs repair still has to be copied as one.
108
+ */
109
+ declare function parseDocumentIndex(value: unknown): DocumentIndex;
110
+ /** What a stored index.json holds, counted without judging each record. */
111
+ interface DocumentIndexSummary {
112
+ /** Whether the index has a record list at all. Without one, every count is 0. */
113
+ valid: boolean;
114
+ /** Every record that is an object, whatever its status. */
115
+ documents: number;
116
+ active: number;
117
+ archived: number;
118
+ }
119
+ /**
120
+ * Count the records of a parsed index.json for a read-only inventory. It never throws: an index
121
+ * without a record list is not `valid`, and a malformed record is counted or skipped, never refused.
122
+ */
123
+ declare function summarizeDocumentIndex(value: unknown): DocumentIndexSummary;
88
124
  //#endregion
89
- export { DOCUMENTS_ACTIVE_LIMIT_BYTES, DOCUMENTS_VERSION, DocumentCapacityPlan, DocumentMutation, DocumentMutationResult, DocumentRecord, DocumentSearchResult, DocumentSnapshot, DocumentStatus, DocumentView };
125
+ export { DOCUMENTS_ACTIVE_LIMIT_BYTES, DOCUMENTS_DIRECTORY, DOCUMENTS_INDEX_FILE, DOCUMENTS_LOCK_FILE, DOCUMENTS_LOCK_STALE_MS, DOCUMENTS_VERSION, DOCUMENT_FILENAME_PATTERN, DocumentCapacityPlan, DocumentIndex, DocumentIndexSummary, DocumentMutation, DocumentMutationResult, DocumentRecord, DocumentSearchResult, DocumentSnapshot, DocumentStatus, DocumentView, parseDocumentIndex, summarizeDocumentIndex };
package/lib/contracts.js CHANGED
@@ -1,5 +1,74 @@
1
1
  //#region src/contracts.ts
2
2
  const DOCUMENTS_VERSION = 1;
3
3
  const DOCUMENTS_ACTIVE_LIMIT_BYTES = 10485760;
4
+ /** The Documents Source's directory under a storage root; each document sits in `<status>/<filename>` below it. */
5
+ const DOCUMENTS_DIRECTORY = "documents";
6
+ /** The metadata of every document, the source of truth for which files belong to the Source. */
7
+ const DOCUMENTS_INDEX_FILE = "index.json";
8
+ /** Created exclusively while the index or a document is read or written; whoever copies them takes it too. */
9
+ const DOCUMENTS_LOCK_FILE = ".index.lock";
10
+ /** A lock file older than this was left by a process that stopped, and may be taken over. */
11
+ const DOCUMENTS_LOCK_STALE_MS = 3e4;
12
+ /** The file name a document may have: one path segment, so it never leaves its status directory. */
13
+ const DOCUMENT_FILENAME_PATTERN = /^[a-zA-Z0-9._-]+\.md$/u;
14
+ function isObject(value) {
15
+ return typeof value === "object" && value !== null && !Array.isArray(value);
16
+ }
17
+ /**
18
+ * Read an index as a copy of it carries it, such as a Mnemon Pack or a sync branch: every record
19
+ * complete, each id unique and each file name safe, or the whole index is refused. A record's path
20
+ * is where its status puts it, whatever the copy says. Unknown fields are dropped, and so are
21
+ * list items that are not strings. Reading the index does not judge a record's content hash: a
22
+ * store that needs repair still has to be copied as one.
23
+ */
24
+ function parseDocumentIndex(value) {
25
+ const index = isObject(value) ? value : void 0;
26
+ if (index?.version !== 1 || !Array.isArray(index.documents)) throw new Error("Documents index.json is invalid");
27
+ const ids = /* @__PURE__ */ new Set();
28
+ return {
29
+ version: 1,
30
+ documents: index.documents.map((raw) => {
31
+ const item = isObject(raw) ? raw : void 0;
32
+ if (typeof item?.id !== "string" || item.id.trim() === "" || ids.has(item.id)) throw new Error("Documents index contains an invalid or duplicate id");
33
+ if (typeof item.title !== "string" || typeof item.description !== "string" || item.status !== "active" && item.status !== "archived") throw new Error("Documents index contains an invalid record");
34
+ if (typeof item.filename !== "string" || !DOCUMENT_FILENAME_PATTERN.test(item.filename)) throw new Error("Documents index contains an unsafe filename");
35
+ if (typeof item.createdAt !== "string" || typeof item.updatedAt !== "string" || typeof item.lastAccessedAt !== "string" || !Number.isSafeInteger(item.revision) || typeof item.contentHash !== "string" || !Number.isSafeInteger(item.sizeBytes)) throw new Error("Documents index contains invalid metadata");
36
+ if (!Array.isArray(item.sourcePaths) || !Array.isArray(item.sessionIds) || !Array.isArray(item.memoryBodyIds)) throw new Error("Documents index contains invalid lists");
37
+ ids.add(item.id);
38
+ return {
39
+ id: item.id,
40
+ title: item.title,
41
+ description: item.description,
42
+ status: item.status,
43
+ filename: item.filename,
44
+ relativePath: `${DOCUMENTS_DIRECTORY}/${item.status}/${item.filename}`,
45
+ sourcePaths: item.sourcePaths.filter((entry) => typeof entry === "string"),
46
+ sessionIds: item.sessionIds.filter((entry) => typeof entry === "string"),
47
+ createdAt: item.createdAt,
48
+ updatedAt: item.updatedAt,
49
+ lastAccessedAt: item.lastAccessedAt,
50
+ revision: Number(item.revision),
51
+ contentHash: item.contentHash,
52
+ sizeBytes: Number(item.sizeBytes),
53
+ ...typeof item.archivedAt === "string" ? { archivedAt: item.archivedAt } : {},
54
+ ...typeof item.archiveSummary === "string" ? { archiveSummary: item.archiveSummary } : {},
55
+ memoryBodyIds: item.memoryBodyIds.filter((entry) => typeof entry === "string")
56
+ };
57
+ })
58
+ };
59
+ }
60
+ /**
61
+ * Count the records of a parsed index.json for a read-only inventory. It never throws: an index
62
+ * without a record list is not `valid`, and a malformed record is counted or skipped, never refused.
63
+ */
64
+ function summarizeDocumentIndex(value) {
65
+ const documents = isObject(value) && Array.isArray(value.documents) ? value.documents.filter(isObject) : [];
66
+ return {
67
+ valid: isObject(value) && Array.isArray(value.documents),
68
+ documents: documents.length,
69
+ active: documents.filter((document) => document.status === "active").length,
70
+ archived: documents.filter((document) => document.status === "archived").length
71
+ };
72
+ }
4
73
  //#endregion
5
- export { DOCUMENTS_ACTIVE_LIMIT_BYTES, DOCUMENTS_VERSION };
74
+ export { DOCUMENTS_ACTIVE_LIMIT_BYTES, DOCUMENTS_DIRECTORY, DOCUMENTS_INDEX_FILE, DOCUMENTS_LOCK_FILE, DOCUMENTS_LOCK_STALE_MS, DOCUMENTS_VERSION, DOCUMENT_FILENAME_PATTERN, parseDocumentIndex, summarizeDocumentIndex };
package/lib/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { DOCUMENTS_ACTIVE_LIMIT_BYTES, DOCUMENTS_VERSION, DocumentCapacityPlan, DocumentMutation, DocumentMutationResult, DocumentRecord, DocumentSearchResult, DocumentSnapshot, DocumentStatus, DocumentView } from "./contracts.js";
1
+ import { DOCUMENTS_ACTIVE_LIMIT_BYTES, DOCUMENTS_DIRECTORY, DOCUMENTS_INDEX_FILE, DOCUMENTS_LOCK_FILE, DOCUMENTS_LOCK_STALE_MS, DOCUMENTS_VERSION, DOCUMENT_FILENAME_PATTERN, DocumentCapacityPlan, DocumentIndex, DocumentIndexSummary, DocumentMutation, DocumentMutationResult, DocumentRecord, DocumentSearchResult, DocumentSnapshot, DocumentStatus, DocumentView, parseDocumentIndex, summarizeDocumentIndex } from "./contracts.js";
2
2
  import z from "@deepseek-ai/schemastery";
3
3
  import { MemorySourceDefinition } from "dsh-mnemon/contracts";
4
4
  import { Context } from "@deepseek-ai/cordis";
@@ -19,4 +19,4 @@ declare const inject: string[];
19
19
  declare const memoryPlugin: import("dsh-mnemon/extension-sdk").MemoryPluginDescriptor;
20
20
  declare function apply(ctx: Context, config?: Config): void;
21
21
  //#endregion
22
- export { Config, type DOCUMENTS_ACTIVE_LIMIT_BYTES, DOCUMENTS_MEMORY_SOURCE, type DOCUMENTS_VERSION, type DocumentCapacityPlan, type DocumentMutation, type DocumentMutationResult, type DocumentRecord, type DocumentSearchResult, type DocumentSnapshot, type DocumentStatus, type DocumentView, apply, createDocumentsMemorySource, inject, memoryPlugin, name };
22
+ export { Config, type DOCUMENTS_ACTIVE_LIMIT_BYTES, type DOCUMENTS_DIRECTORY, type DOCUMENTS_INDEX_FILE, type DOCUMENTS_LOCK_FILE, type DOCUMENTS_LOCK_STALE_MS, DOCUMENTS_MEMORY_SOURCE, type DOCUMENTS_VERSION, type DOCUMENT_FILENAME_PATTERN, type DocumentCapacityPlan, type DocumentIndex, type DocumentIndexSummary, type DocumentMutation, type DocumentMutationResult, type DocumentRecord, type DocumentSearchResult, type DocumentSnapshot, type DocumentStatus, type DocumentView, apply, createDocumentsMemorySource, inject, memoryPlugin, name, type parseDocumentIndex, type summarizeDocumentIndex };
package/lib/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { DOCUMENTS_ACTIVE_LIMIT_BYTES } from "./contracts.js";
1
+ import { DOCUMENTS_ACTIVE_LIMIT_BYTES, DOCUMENTS_DIRECTORY, DOCUMENTS_INDEX_FILE, DOCUMENTS_LOCK_FILE } from "./contracts.js";
2
2
  import { createMemoryMutationReceipt, defineMemoryPlugin, defineMemorySource, installMemory, memoryConfigurationDigest, memoryInputRecord, memoryInputStringArray, memoryInputText, truncateMemoryText } from "dsh-mnemon/extension-sdk";
3
3
  import { homedir } from "node:os";
4
4
  import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -47,7 +47,6 @@ function lexicalRequiredMatchCount(tokens) {
47
47
  //#region src/controller.ts
48
48
  const MAX_DOCUMENT_BYTES = 2097152;
49
49
  const LOCK_TIMEOUT_MS = 5e3;
50
- const LOCK_STALE_MS = 3e4;
51
50
  const LOCK_RETRY_MS = 20;
52
51
  const MAX_EXCERPT_CACHE_ENTRIES = 2048;
53
52
  var DocumentCapacityError = class extends Error {
@@ -200,12 +199,12 @@ var DocumentController = class {
200
199
  if (!existsSync(this.workspaceRoot) || !statSync(this.workspaceRoot).isDirectory()) throw new Error(`document workspace is unavailable: ${this.workspaceRoot}`);
201
200
  if (!Number.isSafeInteger(limitBytes) || limitBytes < 1) throw new Error("active document limit must be a positive integer");
202
201
  this.storageRoot = storageRoot === void 0 ? join(this.workspaceRoot, ".mnemon") : resolve(storageRoot);
203
- this.managedRelativePrefix = storageRoot === void 0 ? [".mnemon", "documents"].join("/") : "documents";
204
- this.directory = join(this.storageRoot, "documents");
202
+ this.managedRelativePrefix = storageRoot === void 0 ? [".mnemon", DOCUMENTS_DIRECTORY].join("/") : DOCUMENTS_DIRECTORY;
203
+ this.directory = join(this.storageRoot, DOCUMENTS_DIRECTORY);
205
204
  this.activeDirectory = join(this.directory, "active");
206
205
  this.archivedDirectory = join(this.directory, "archived");
207
- this.indexPath = join(this.directory, "index.json");
208
- this.lockPath = join(this.directory, ".index.lock");
206
+ this.indexPath = join(this.directory, DOCUMENTS_INDEX_FILE);
207
+ this.lockPath = join(this.directory, DOCUMENTS_LOCK_FILE);
209
208
  this.initialize();
210
209
  }
211
210
  snapshot() {
@@ -578,7 +577,7 @@ var DocumentController = class {
578
577
  ].join("/");
579
578
  }
580
579
  pathFor(record) {
581
- const legacyPrefix = [".mnemon", "documents"].join("/");
580
+ const legacyPrefix = [".mnemon", DOCUMENTS_DIRECTORY].join("/");
582
581
  const relativePath = record.relativePath === legacyPrefix || record.relativePath.startsWith(`${legacyPrefix}/`) ? record.relativePath.slice(8) : record.relativePath;
583
582
  const path = resolve(this.storageRoot, relativePath);
584
583
  const managedRoot = `${resolve(this.directory)}${sep}`;
@@ -618,7 +617,7 @@ var DocumentController = class {
618
617
  } catch (error) {
619
618
  if (error.code !== "EEXIST") throw error;
620
619
  try {
621
- if (Date.now() - statSync(this.lockPath).mtimeMs > LOCK_STALE_MS) rmSync(this.lockPath, { force: true });
620
+ if (Date.now() - statSync(this.lockPath).mtimeMs > 3e4) rmSync(this.lockPath, { force: true });
622
621
  } catch {}
623
622
  if (Date.now() >= deadline) throw new Error(`timed out waiting for document lock: ${this.lockPath}`);
624
623
  sleepSync(LOCK_RETRY_MS);
@@ -84,3 +84,39 @@ export interface DocumentCapacityPlan {
84
84
  }
85
85
  export declare const DOCUMENTS_VERSION = 1;
86
86
  export declare const DOCUMENTS_ACTIVE_LIMIT_BYTES: number;
87
+ /** The Documents Source's directory under a storage root; each document sits in `<status>/<filename>` below it. */
88
+ export declare const DOCUMENTS_DIRECTORY = "documents";
89
+ /** The metadata of every document, the source of truth for which files belong to the Source. */
90
+ export declare const DOCUMENTS_INDEX_FILE = "index.json";
91
+ /** Created exclusively while the index or a document is read or written; whoever copies them takes it too. */
92
+ export declare const DOCUMENTS_LOCK_FILE = ".index.lock";
93
+ /** A lock file older than this was left by a process that stopped, and may be taken over. */
94
+ export declare const DOCUMENTS_LOCK_STALE_MS = 30000;
95
+ /** The file name a document may have: one path segment, so it never leaves its status directory. */
96
+ export declare const DOCUMENT_FILENAME_PATTERN: RegExp;
97
+ export interface DocumentIndex {
98
+ version: typeof DOCUMENTS_VERSION;
99
+ documents: DocumentRecord[];
100
+ }
101
+ /**
102
+ * Read an index as a copy of it carries it, such as a Mnemon Pack or a sync branch: every record
103
+ * complete, each id unique and each file name safe, or the whole index is refused. A record's path
104
+ * is where its status puts it, whatever the copy says. Unknown fields are dropped, and so are
105
+ * list items that are not strings. Reading the index does not judge a record's content hash: a
106
+ * store that needs repair still has to be copied as one.
107
+ */
108
+ export declare function parseDocumentIndex(value: unknown): DocumentIndex;
109
+ /** What a stored index.json holds, counted without judging each record. */
110
+ export interface DocumentIndexSummary {
111
+ /** Whether the index has a record list at all. Without one, every count is 0. */
112
+ valid: boolean;
113
+ /** Every record that is an object, whatever its status. */
114
+ documents: number;
115
+ active: number;
116
+ archived: number;
117
+ }
118
+ /**
119
+ * Count the records of a parsed index.json for a read-only inventory. It never throws: an index
120
+ * without a record list is not `valid`, and a malformed record is counted or skipped, never refused.
121
+ */
122
+ export declare function summarizeDocumentIndex(value: unknown): DocumentIndexSummary;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-mnemon-source-documents",
3
- "version": "0.5.10",
3
+ "version": "0.5.11",
4
4
  "description": "Self-contained documents Source for Composable View Memory.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -56,12 +56,12 @@
56
56
  "react": "^18.2.0"
57
57
  },
58
58
  "devDependencies": {
59
- "@deepseek-ai/dsh-client-ui-primitives": "0.1.7-rc.2",
59
+ "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.2",
60
60
  "@testing-library/react": "^16.3.0",
61
61
  "@types/node": "^22.0.0",
62
62
  "@types/react": "^18.3.0",
63
63
  "@types/react-dom": "^18.3.0",
64
- "dsh-mnemon": "^0.5.25",
64
+ "dsh-mnemon": "^0.5.32",
65
65
  "jsdom": "^26.0.0",
66
66
  "react": "^18.2.0",
67
67
  "react-dom": "^18.2.0",
@@ -85,9 +85,9 @@
85
85
  "micromark-util-sanitize-uri": "^2.0.1",
86
86
  "micromark-util-symbol": "^2.0.1",
87
87
  "shiki": "^4.3.1",
88
- "@deepseek-ai/dsh-client-store": "0.1.7-rc.2",
89
- "@deepseek-ai/dsh-util-code-language": "0.1.7-rc.2",
90
- "@deepseek-ai/dsh-util-workspace-path": "0.1.7-rc.2",
88
+ "@deepseek-ai/dsh-client-store": "0.2.1-rc.2",
89
+ "@deepseek-ai/dsh-util-code-language": "0.2.1-rc.2",
90
+ "@deepseek-ai/dsh-util-workspace-path": "0.2.1-rc.2",
91
91
  "diff": "^9.0.0",
92
92
  "immer": "^10.1.1",
93
93
  "simple-icons": "16.31.0",