@narumitw/pi-notes 0.0.0

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/src/storage.ts ADDED
@@ -0,0 +1,514 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import { type Dir, constants as fsConstants } from "node:fs";
3
+ import { lstat, mkdir, open, opendir, readFile, realpath, rename, stat, unlink } from "node:fs/promises";
4
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32 } from "node:path";
5
+ import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
6
+ import { sanitizeTerminalText } from "@narumitw/pi-tui-kit/terminal-text";
7
+ import {
8
+ MAX_DISCOVERED_FILES,
9
+ MAX_MARKDOWN_BYTES,
10
+ MAX_MARKDOWN_LINES,
11
+ MAX_SCAN_DEPTH,
12
+ MAX_SCAN_ERRORS,
13
+ NOTES_DIRECTORY,
14
+ SESSIONS_DIRECTORY,
15
+ TEMPLATES_DIRECTORY,
16
+ } from "./constants.js";
17
+
18
+ export interface NotesPaths {
19
+ root: string;
20
+ notes: string;
21
+ templates: string;
22
+ sessions: string;
23
+ }
24
+
25
+ export interface MarkdownEntry {
26
+ /** Raw normalized relative path used as the stable file identity. */
27
+ relativePath: string;
28
+ /** Presentation-only path with terminal controls removed. */
29
+ displayPath: string;
30
+ size: number;
31
+ }
32
+
33
+ export interface DiscoveryError {
34
+ relativePath?: string;
35
+ message: string;
36
+ }
37
+
38
+ export interface DiscoveryResult {
39
+ entries: MarkdownEntry[];
40
+ errors: DiscoveryError[];
41
+ limited: boolean;
42
+ }
43
+
44
+ export interface NoteSnapshot {
45
+ relativePath: string;
46
+ content: string;
47
+ revision: string;
48
+ size: number;
49
+ }
50
+
51
+ export interface NotesStorageOptions {
52
+ /** Test seam invoked after a complete temporary file is synced and before publication. */
53
+ beforePublish?(targetPath: string, temporaryPath: string): Promise<void> | void;
54
+ }
55
+
56
+ export class NotesStorage {
57
+ readonly paths: NotesPaths;
58
+ private readonly beforePublish?: NotesStorageOptions["beforePublish"];
59
+
60
+ constructor(agentDir: string, options: NotesStorageOptions = {}) {
61
+ const root = join(agentDir, "pi-notes");
62
+ this.paths = {
63
+ root,
64
+ notes: join(root, NOTES_DIRECTORY),
65
+ templates: join(root, TEMPLATES_DIRECTORY),
66
+ sessions: join(root, SESSIONS_DIRECTORY),
67
+ };
68
+ this.beforePublish = options.beforePublish;
69
+ }
70
+
71
+ async initialize(signal?: AbortSignal): Promise<NotesPaths> {
72
+ throwIfAborted(signal);
73
+ await mkdir(this.paths.root, { recursive: true, mode: 0o700 });
74
+ await verifyManagedDirectory(this.paths.root, signal);
75
+ for (const directory of [this.paths.notes, this.paths.templates, this.paths.sessions]) {
76
+ await mkdir(directory, { recursive: true, mode: 0o700 });
77
+ await verifyManagedDirectory(directory, signal);
78
+ }
79
+ return this.paths;
80
+ }
81
+
82
+ async discoverNotes(signal?: AbortSignal): Promise<DiscoveryResult> {
83
+ return discoverMarkdown(this.paths.notes, signal);
84
+ }
85
+
86
+ async discoverTemplates(signal?: AbortSignal): Promise<DiscoveryResult> {
87
+ return discoverMarkdown(this.paths.templates, signal);
88
+ }
89
+
90
+ async readNote(relativePath: string, signal?: AbortSignal): Promise<NoteSnapshot> {
91
+ const resolved = await resolveExistingMarkdown(this.paths.notes, relativePath, signal);
92
+ const content = await readBoundedMarkdown(resolved.absolutePath, "Note", signal);
93
+ return snapshot(resolved.relativePath, content);
94
+ }
95
+
96
+ async readTemplate(relativePath: string, signal?: AbortSignal): Promise<string> {
97
+ const resolved = await resolveExistingMarkdown(this.paths.templates, relativePath, signal);
98
+ return readBoundedMarkdown(resolved.absolutePath, "Template", signal);
99
+ }
100
+
101
+ async createNote(
102
+ relativePath: string,
103
+ options: { templatePath?: string; signal?: AbortSignal } = {},
104
+ ): Promise<NoteSnapshot> {
105
+ const normalized = normalizeRelativeMarkdownPath(relativePath);
106
+ const content = options.templatePath ? await this.readTemplate(options.templatePath, options.signal) : "";
107
+ validateMarkdownContent(content, "Note");
108
+ const root = await canonicalDirectory(this.paths.notes, options.signal);
109
+ const target = resolve(root, ...normalized.split("/"));
110
+ assertContained(root, target);
111
+ return withFileMutationQueue(target, async () => {
112
+ await ensureSafeParent(root, dirname(target), options.signal);
113
+ throwIfAborted(options.signal);
114
+ await assertMissingNote(target, normalized, options.signal);
115
+ await atomicCreate(root, target, normalized, content, options.signal, this.beforePublish);
116
+ return snapshot(normalized, content);
117
+ });
118
+ }
119
+
120
+ async editNote(
121
+ relativePath: string,
122
+ expectedRevision: string,
123
+ oldText: string,
124
+ newText: string,
125
+ signal?: AbortSignal,
126
+ ): Promise<NoteSnapshot> {
127
+ if (!oldText) throw new Error("oldText must not be empty; use replace_current_note for a full replacement");
128
+ const normalized = normalizeExistingMarkdownPath(relativePath);
129
+ const queuePath = resolve(this.paths.notes, ...normalized.split("/"));
130
+ return withFileMutationQueue(queuePath, async () => {
131
+ throwIfAborted(signal);
132
+ const current = await this.readNote(normalized, signal);
133
+ assertRevision(current, expectedRevision);
134
+ const index = current.content.indexOf(oldText);
135
+ if (index < 0) throw new Error("oldText was not found in the current note");
136
+ if (current.content.indexOf(oldText, index + oldText.length) >= 0) {
137
+ throw new Error("oldText is not unique in the current note");
138
+ }
139
+ const content = `${current.content.slice(0, index)}${newText}${current.content.slice(index + oldText.length)}`;
140
+ validateMarkdownContent(content, "Note");
141
+ await atomicReplace(this.paths.notes, queuePath, content, current.revision, signal, this.beforePublish);
142
+ return snapshot(normalized, content);
143
+ });
144
+ }
145
+
146
+ async replaceNote(
147
+ relativePath: string,
148
+ expectedRevision: string,
149
+ content: string,
150
+ signal?: AbortSignal,
151
+ ): Promise<NoteSnapshot> {
152
+ const normalized = normalizeExistingMarkdownPath(relativePath);
153
+ validateMarkdownContent(content, "Note");
154
+ const queuePath = resolve(this.paths.notes, ...normalized.split("/"));
155
+ return withFileMutationQueue(queuePath, async () => {
156
+ throwIfAborted(signal);
157
+ const current = await this.readNote(normalized, signal);
158
+ assertRevision(current, expectedRevision);
159
+ await atomicReplace(this.paths.notes, queuePath, content, current.revision, signal, this.beforePublish);
160
+ return snapshot(normalized, content);
161
+ });
162
+ }
163
+ }
164
+
165
+ export function normalizeRelativeMarkdownPath(input: string): string {
166
+ if (input !== input.trim()) throw new Error("Note path must not start or end with whitespace");
167
+ if (!input) throw new Error("Note path is required");
168
+ if (
169
+ [...input].some((character) => {
170
+ const codePoint = character.codePointAt(0) ?? 0;
171
+ return codePoint <= 0x1f || codePoint === 0x7f;
172
+ })
173
+ ) {
174
+ throw new Error("Note path must not contain control characters");
175
+ }
176
+ if (isAbsolute(input) || win32.isAbsolute(input)) throw new Error("Note path must be relative");
177
+ const portable = input.replaceAll("\\", "/");
178
+ const segments = portable.split("/");
179
+ if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
180
+ throw new Error("Note path must not contain empty, . or .. segments");
181
+ }
182
+ if (!portable.toLowerCase().endsWith(".md")) throw new Error("Note path must end in .md");
183
+ return segments.join("/");
184
+ }
185
+
186
+ function normalizeExistingMarkdownPath(input: string): string {
187
+ if (!input) throw new Error("Markdown path is required");
188
+ if (isAbsolute(input) || win32.isAbsolute(input)) throw new Error("Markdown path must be relative");
189
+ const segments = input.split("/");
190
+ if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
191
+ throw new Error("Markdown path must not contain empty, . or .. segments");
192
+ }
193
+ if (!input.toLowerCase().endsWith(".md")) throw new Error("Markdown path must end in .md");
194
+ return segments.join("/");
195
+ }
196
+
197
+ export function revisionFor(content: string): string {
198
+ return createHash("sha256").update(content).digest("hex");
199
+ }
200
+
201
+ export function validateMarkdownContent(content: string, label: string): void {
202
+ const bytes = Buffer.byteLength(content, "utf8");
203
+ if (bytes > MAX_MARKDOWN_BYTES) {
204
+ throw new Error(`${label} exceeds the ${MAX_MARKDOWN_BYTES}-byte limit`);
205
+ }
206
+ const lines = content.length === 0 ? 0 : content.split("\n").length;
207
+ if (lines > MAX_MARKDOWN_LINES) {
208
+ throw new Error(`${label} exceeds the ${MAX_MARKDOWN_LINES}-line limit`);
209
+ }
210
+ }
211
+
212
+ async function discoverMarkdown(rootPath: string, signal?: AbortSignal): Promise<DiscoveryResult> {
213
+ const root = await canonicalDirectory(rootPath, signal);
214
+ const entries: MarkdownEntry[] = [];
215
+ const errors: DiscoveryError[] = [];
216
+ let limited = false;
217
+
218
+ const report = (message: string, relativePath?: string) => {
219
+ if (errors.length >= MAX_SCAN_ERRORS) {
220
+ limited = true;
221
+ return;
222
+ }
223
+ errors.push({ ...(relativePath ? { relativePath } : {}), message });
224
+ };
225
+
226
+ const visit = async (directory: string, depth: number): Promise<void> => {
227
+ if (entries.length >= MAX_DISCOVERED_FILES || limited) {
228
+ limited = true;
229
+ return;
230
+ }
231
+ if (depth > MAX_SCAN_DEPTH) {
232
+ report(`Directory nesting exceeds the ${MAX_SCAN_DEPTH}-level limit`, normalizeDiscoveredPath(root, directory));
233
+ return;
234
+ }
235
+ throwIfAborted(signal);
236
+ let handle: Dir | undefined;
237
+ try {
238
+ handle = await opendir(directory);
239
+ } catch (error) {
240
+ report(safeErrorMessage(error), normalizeDiscoveredPath(root, directory));
241
+ return;
242
+ }
243
+ try {
244
+ for await (const entry of handle) {
245
+ throwIfAborted(signal);
246
+ const absolutePath = join(directory, entry.name);
247
+ const relativePath = normalizeDiscoveredPath(root, absolutePath);
248
+ if (entry.isSymbolicLink()) {
249
+ report("Symbolic links are not managed", relativePath);
250
+ continue;
251
+ }
252
+ if (entry.isDirectory()) {
253
+ await visit(absolutePath, depth + 1);
254
+ continue;
255
+ }
256
+ if (!entry.name.toLowerCase().endsWith(".md")) continue;
257
+ if (!entry.isFile()) {
258
+ report("Entry is not a regular file", relativePath);
259
+ continue;
260
+ }
261
+ if (entries.length >= MAX_DISCOVERED_FILES) {
262
+ limited = true;
263
+ break;
264
+ }
265
+ try {
266
+ const info = await stat(absolutePath);
267
+ throwIfAborted(signal);
268
+ if (!info.isFile()) {
269
+ report("Entry is not a regular file", relativePath);
270
+ continue;
271
+ }
272
+ if (info.size > MAX_MARKDOWN_BYTES) {
273
+ report(`File exceeds the ${MAX_MARKDOWN_BYTES}-byte limit`, relativePath);
274
+ continue;
275
+ }
276
+ await readBoundedMarkdown(absolutePath, "File", signal);
277
+ entries.push({
278
+ relativePath,
279
+ displayPath: sanitizeTerminalText(relativePath),
280
+ size: info.size,
281
+ });
282
+ } catch (error) {
283
+ report(safeErrorMessage(error), relativePath);
284
+ }
285
+ }
286
+ } finally {
287
+ await handle?.close().catch(() => undefined);
288
+ }
289
+ };
290
+
291
+ await visit(root, 0);
292
+ entries.sort((first, second) => first.relativePath.localeCompare(second.relativePath));
293
+ errors.sort((first, second) => (first.relativePath ?? "").localeCompare(second.relativePath ?? ""));
294
+ if (limited && errors.length < MAX_SCAN_ERRORS) {
295
+ report(`Discovery stopped at ${MAX_DISCOVERED_FILES} files or ${MAX_SCAN_ERRORS} errors`);
296
+ }
297
+ return { entries, errors, limited };
298
+ }
299
+
300
+ async function resolveExistingMarkdown(
301
+ rootPath: string,
302
+ relativePath: string,
303
+ signal?: AbortSignal,
304
+ ): Promise<{ relativePath: string; absolutePath: string }> {
305
+ const normalized = normalizeExistingMarkdownPath(relativePath);
306
+ const root = await canonicalDirectory(rootPath, signal);
307
+ const candidate = resolve(root, ...normalized.split("/"));
308
+ assertContained(root, candidate);
309
+ throwIfAborted(signal);
310
+ const linkInfo = await lstat(candidate);
311
+ throwIfAborted(signal);
312
+ if (linkInfo.isSymbolicLink()) throw new Error(`Symbolic-link notes are not supported: ${normalized}`);
313
+ if (!linkInfo.isFile()) throw new Error(`Note is not a regular file: ${normalized}`);
314
+ const canonical = await realpath(candidate);
315
+ throwIfAborted(signal);
316
+ assertContained(root, canonical);
317
+ if (canonical !== candidate) throw new Error(`Note path is not canonical: ${normalized}`);
318
+ return { relativePath: normalized, absolutePath: canonical };
319
+ }
320
+
321
+ async function verifyManagedDirectory(path: string, signal?: AbortSignal): Promise<void> {
322
+ throwIfAborted(signal);
323
+ const info = await lstat(path);
324
+ throwIfAborted(signal);
325
+ if (info.isSymbolicLink() || !info.isDirectory()) throw new Error(`${path} is not a regular directory`);
326
+ }
327
+
328
+ async function canonicalDirectory(path: string, signal?: AbortSignal): Promise<string> {
329
+ throwIfAborted(signal);
330
+ const directInfo = await lstat(path);
331
+ throwIfAborted(signal);
332
+ if (directInfo.isSymbolicLink() || !directInfo.isDirectory()) throw new Error(`${path} is not a regular directory`);
333
+ const canonical = await realpath(path);
334
+ throwIfAborted(signal);
335
+ const info = await stat(canonical);
336
+ throwIfAborted(signal);
337
+ if (!info.isDirectory()) throw new Error(`${path} is not a directory`);
338
+ return canonical;
339
+ }
340
+
341
+ async function ensureSafeParent(root: string, targetParent: string, signal?: AbortSignal): Promise<void> {
342
+ assertContained(root, targetParent);
343
+ const relativeParent = relative(root, targetParent);
344
+ let current = root;
345
+ if (!relativeParent) return;
346
+ for (const segment of relativeParent.split(sep)) {
347
+ current = join(current, segment);
348
+ throwIfAborted(signal);
349
+ try {
350
+ await lstat(current);
351
+ } catch (error) {
352
+ if (!isNodeError(error, "ENOENT")) throw error;
353
+ try {
354
+ await mkdir(current, { mode: 0o700 });
355
+ } catch (mkdirError) {
356
+ if (!isNodeError(mkdirError, "EEXIST")) throw mkdirError;
357
+ }
358
+ }
359
+ throwIfAborted(signal);
360
+ const info = await lstat(current);
361
+ throwIfAborted(signal);
362
+ if (info.isSymbolicLink()) throw new Error(`Parent directory is a symbolic link: ${current}`);
363
+ if (!info.isDirectory()) throw new Error(`Parent path is not a directory: ${current}`);
364
+ const canonical = await realpath(current);
365
+ throwIfAborted(signal);
366
+ assertContained(root, canonical);
367
+ if (canonical !== current) throw new Error(`Parent directory is not canonical: ${current}`);
368
+ }
369
+ }
370
+
371
+ async function readBoundedMarkdown(path: string, label: string, signal?: AbortSignal): Promise<string> {
372
+ throwIfAborted(signal);
373
+ const info = await stat(path);
374
+ throwIfAborted(signal);
375
+ if (!info.isFile()) throw new Error(`${label} is not a regular file`);
376
+ if (info.size > MAX_MARKDOWN_BYTES) throw new Error(`${label} exceeds the ${MAX_MARKDOWN_BYTES}-byte limit`);
377
+ const content = await readFile(path, "utf8");
378
+ throwIfAborted(signal);
379
+ validateMarkdownContent(content, label);
380
+ return content;
381
+ }
382
+
383
+ async function atomicCreate(
384
+ rootPath: string,
385
+ targetPath: string,
386
+ relativePath: string,
387
+ content: string,
388
+ signal?: AbortSignal,
389
+ beforePublish?: NotesStorageOptions["beforePublish"],
390
+ ): Promise<void> {
391
+ const temporaryPath = temporaryName(targetPath);
392
+ try {
393
+ await writeTemporary(temporaryPath, content, 0o600, signal);
394
+ throwIfAborted(signal);
395
+ await beforePublish?.(targetPath, temporaryPath);
396
+ throwIfAborted(signal);
397
+ await revalidateCanonicalParent(rootPath, targetPath, signal);
398
+ await assertMissingNote(targetPath, relativePath, signal);
399
+ await rename(temporaryPath, targetPath);
400
+ } catch (error) {
401
+ await unlink(temporaryPath).catch(() => undefined);
402
+ throw error;
403
+ }
404
+ }
405
+
406
+ async function assertMissingNote(targetPath: string, relativePath: string, signal?: AbortSignal): Promise<void> {
407
+ throwIfAborted(signal);
408
+ try {
409
+ await lstat(targetPath);
410
+ throw new Error(`Note already exists: ${relativePath}`);
411
+ } catch (error) {
412
+ if (!isNodeError(error, "ENOENT")) throw error;
413
+ }
414
+ throwIfAborted(signal);
415
+ }
416
+
417
+ async function atomicReplace(
418
+ rootPath: string,
419
+ targetPath: string,
420
+ content: string,
421
+ expectedRevision: string,
422
+ signal?: AbortSignal,
423
+ beforePublish?: NotesStorageOptions["beforePublish"],
424
+ ): Promise<void> {
425
+ const relativePath = relative(rootPath, targetPath).split(sep).join("/");
426
+ const resolved = await resolveExistingMarkdown(rootPath, relativePath, signal);
427
+ const current = await readBoundedMarkdown(resolved.absolutePath, "Note", signal);
428
+ if (revisionFor(current) !== expectedRevision) throw new Error("Note changed before publication; read it again");
429
+ const info = await stat(resolved.absolutePath);
430
+ throwIfAborted(signal);
431
+ const temporaryPath = temporaryName(targetPath);
432
+ try {
433
+ await writeTemporary(temporaryPath, content, info.mode & 0o777, signal);
434
+ throwIfAborted(signal);
435
+ await beforePublish?.(targetPath, temporaryPath);
436
+ throwIfAborted(signal);
437
+ const latestResolved = await resolveExistingMarkdown(rootPath, relativePath, signal);
438
+ if (latestResolved.absolutePath !== resolved.absolutePath) {
439
+ throw new Error("Note path changed before publication; read it again");
440
+ }
441
+ const latest = await readBoundedMarkdown(latestResolved.absolutePath, "Note", signal);
442
+ if (revisionFor(latest) !== expectedRevision) throw new Error("Note changed before publication; read it again");
443
+ throwIfAborted(signal);
444
+ await rename(temporaryPath, latestResolved.absolutePath);
445
+ } catch (error) {
446
+ await unlink(temporaryPath).catch(() => undefined);
447
+ throw error;
448
+ }
449
+ }
450
+
451
+ async function revalidateCanonicalParent(rootPath: string, targetPath: string, signal?: AbortSignal): Promise<void> {
452
+ const parent = dirname(targetPath);
453
+ assertContained(rootPath, parent);
454
+ throwIfAborted(signal);
455
+ const canonical = await realpath(parent);
456
+ throwIfAborted(signal);
457
+ assertContained(rootPath, canonical);
458
+ if (canonical !== parent) throw new Error("Note parent changed before publication");
459
+ }
460
+
461
+ async function writeTemporary(path: string, content: string, mode: number, signal?: AbortSignal): Promise<void> {
462
+ throwIfAborted(signal);
463
+ const handle = await open(path, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, mode);
464
+ try {
465
+ throwIfAborted(signal);
466
+ await handle.writeFile(content, "utf8");
467
+ throwIfAborted(signal);
468
+ await handle.sync();
469
+ throwIfAborted(signal);
470
+ } finally {
471
+ await handle.close();
472
+ }
473
+ }
474
+
475
+ function snapshot(relativePath: string, content: string): NoteSnapshot {
476
+ return {
477
+ relativePath,
478
+ content,
479
+ revision: revisionFor(content),
480
+ size: Buffer.byteLength(content, "utf8"),
481
+ };
482
+ }
483
+
484
+ function assertRevision(current: NoteSnapshot, expectedRevision: string): void {
485
+ if (current.revision !== expectedRevision)
486
+ throw new Error("Note revision is stale; read the current note before editing");
487
+ }
488
+
489
+ function assertContained(root: string, candidate: string): void {
490
+ const nested = relative(root, candidate);
491
+ if (nested === "" || (!nested.startsWith(`..${sep}`) && nested !== ".." && !isAbsolute(nested))) return;
492
+ throw new Error("Path escapes the managed notes directory");
493
+ }
494
+
495
+ function normalizeDiscoveredPath(root: string, absolutePath: string): string {
496
+ return relative(root, absolutePath).split(sep).join("/") || ".";
497
+ }
498
+
499
+ function temporaryName(targetPath: string): string {
500
+ return join(dirname(targetPath), `.${basename(targetPath)}.${process.pid}.${randomUUID()}.tmp`);
501
+ }
502
+
503
+ function safeErrorMessage(error: unknown): string {
504
+ return error instanceof Error ? error.message : String(error);
505
+ }
506
+
507
+ function isNodeError(error: unknown, code: string): error is NodeJS.ErrnoException {
508
+ return error instanceof Error && "code" in error && error.code === code;
509
+ }
510
+
511
+ function throwIfAborted(signal?: AbortSignal): void {
512
+ if (!signal?.aborted) return;
513
+ throw signal.reason instanceof Error ? signal.reason : new DOMException("Operation aborted", "AbortError");
514
+ }