@narumitw/pi-notes 0.0.0 → 0.2.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.
@@ -4,8 +4,9 @@ import {
4
4
  type ExtensionContext,
5
5
  getAgentDir,
6
6
  } from "@earendil-works/pi-coding-agent";
7
+ import { sanitizeTerminalText } from "@narumitw/pi-tui-kit/terminal-text";
7
8
  import type { NotesManagerResult } from "./menu.js";
8
- import { NotesStorage } from "./storage.js";
9
+ import { NotesStorage, type TemplateSnapshot } from "./storage.js";
9
10
  import type { OpenNotesWorkspaceOptions } from "./workspace.js";
10
11
 
11
12
  interface NotesExtensionDependencies {
@@ -16,6 +17,11 @@ interface NotesExtensionDependencies {
16
17
  storage: NotesStorage,
17
18
  ownership: { signal: AbortSignal; isCurrent(): boolean },
18
19
  ): Promise<NotesManagerResult>;
20
+ editTemplate(
21
+ ctx: ExtensionCommandContext,
22
+ template: TemplateSnapshot,
23
+ ownership: { signal: AbortSignal; isCurrent(): boolean },
24
+ ): Promise<string | undefined>;
19
25
  openWorkspace(options: OpenNotesWorkspaceOptions): Promise<void>;
20
26
  }
21
27
 
@@ -32,6 +38,13 @@ export function createNotesExtension(
32
38
  if (ownership.signal.aborted || !ownership.isCurrent()) return { kind: "closed" };
33
39
  return showNotesManager(ctx, storage, ownership);
34
40
  }),
41
+ editTemplate:
42
+ dependencies.editTemplate ??
43
+ (async (ctx, template, ownership) => {
44
+ const { showTemplateEditor } = await import("./template-editor.js");
45
+ if (ownership.signal.aborted || !ownership.isCurrent()) return undefined;
46
+ return showTemplateEditor(ctx, template, ownership);
47
+ }),
35
48
  openWorkspace:
36
49
  dependencies.openWorkspace ??
37
50
  (async (options) => {
@@ -67,25 +80,76 @@ export function createNotesExtension(
67
80
  const signal = ctx.signal ? AbortSignal.any([ctx.signal, ownerController.signal]) : ownerController.signal;
68
81
  const isCurrent = () =>
69
82
  activeSessionManager === owner && generation === ownerGeneration && !ownerController.signal.aborted;
70
- if (!isCurrent()) throw new Error("Pi Notes session is no longer active.");
83
+ const isOwned = () => isCurrent() && !signal.aborted;
84
+ if (!isOwned()) throw new Error("Pi Notes session is no longer active.");
71
85
 
72
86
  const agentDir = deps.getAgentDir();
73
87
  const storage = deps.createStorage(agentDir);
74
88
  await storage.initialize(signal);
75
- if (!isCurrent() || signal.aborted) return;
76
- const selected = await deps.showManager(ctx, storage, { signal, isCurrent });
77
- if (!isCurrent() || signal.aborted || selected.kind !== "open" || !selected.notePath) return;
78
- const thinkingLevel = pi.getThinkingLevel();
79
- if (!isCurrent() || signal.aborted) return;
80
- await deps.openWorkspace({
81
- ctx,
82
- agentDir,
83
- storage,
84
- notePath: selected.notePath,
85
- thinkingLevel,
86
- signal,
87
- isCurrent,
88
- });
89
+ if (!isOwned()) return;
90
+
91
+ while (isOwned()) {
92
+ const selected = await deps.showManager(ctx, storage, { signal, isCurrent });
93
+ if (!isOwned()) return;
94
+ if (selected.kind === "closed") return;
95
+
96
+ if (selected.kind === "pastePath") {
97
+ let absolutePath: string;
98
+ try {
99
+ absolutePath = await storage.resolveCanonicalNotePath(selected.notePath, signal);
100
+ } catch (error) {
101
+ if (!isOwned()) return;
102
+ safeNotify(ctx, `Pi Notes failed to resolve the selected note: ${safeErrorMessage(error)}`, "error");
103
+ continue;
104
+ }
105
+ if (!isOwned()) return;
106
+ if (sanitizeTerminalText(absolutePath) !== absolutePath) {
107
+ safeNotify(ctx, "Pi Notes cannot paste a path that contains terminal or direction controls.", "error");
108
+ continue;
109
+ }
110
+ ctx.ui.pasteToEditor(absolutePath);
111
+ return;
112
+ }
113
+
114
+ if (selected.kind === "editTemplate") {
115
+ let template: TemplateSnapshot;
116
+ try {
117
+ template = await storage.readTemplate(selected.templatePath, signal);
118
+ } catch (error) {
119
+ if (!isOwned()) return;
120
+ safeNotify(ctx, `Pi Notes failed to read the selected template: ${safeErrorMessage(error)}`, "error");
121
+ continue;
122
+ }
123
+ if (!isOwned()) return;
124
+ const content = await deps.editTemplate(ctx, template, { signal, isCurrent });
125
+ if (!isOwned()) return;
126
+ if (content === undefined || content === template.content) continue;
127
+ try {
128
+ await storage.replaceTemplate(template.relativePath, template.revision, content, signal);
129
+ } catch (error) {
130
+ if (!isOwned()) return;
131
+ safeNotify(ctx, `Pi Notes failed to save template: ${safeErrorMessage(error)}`, "error");
132
+ continue;
133
+ }
134
+ if (!isOwned()) return;
135
+ safeNotify(ctx, `Saved template: ${template.relativePath}`, "info");
136
+ continue;
137
+ }
138
+
139
+ const thinkingLevel = pi.getThinkingLevel();
140
+ if (!isOwned()) return;
141
+ await deps.openWorkspace({
142
+ ctx,
143
+ agentDir,
144
+ storage,
145
+ notePath: selected.notePath,
146
+ thinkingLevel,
147
+ signal,
148
+ isCurrent,
149
+ });
150
+ if (!isOwned()) return;
151
+ return;
152
+ }
89
153
  };
90
154
 
91
155
  pi.registerCommand("notes", {
@@ -119,6 +183,18 @@ export function createNotesExtension(
119
183
  };
120
184
  }
121
185
 
186
+ function safeNotify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error"): void {
187
+ try {
188
+ ctx.ui.notify(sanitizeTerminalText(message), level);
189
+ } catch {
190
+ // A replaced session can invalidate the old UI immediately.
191
+ }
192
+ }
193
+
194
+ function safeErrorMessage(error: unknown): string {
195
+ return sanitizeTerminalText(error instanceof Error ? error.message : String(error)).slice(0, 500);
196
+ }
197
+
122
198
  function rejectCommand(ctx: ExtensionContext, message: string): void {
123
199
  if (ctx.hasUI) {
124
200
  try {
package/src/storage.ts CHANGED
@@ -48,6 +48,13 @@ export interface NoteSnapshot {
48
48
  size: number;
49
49
  }
50
50
 
51
+ export interface TemplateSnapshot {
52
+ relativePath: string;
53
+ content: string;
54
+ revision: string;
55
+ size: number;
56
+ }
57
+
51
58
  export interface NotesStorageOptions {
52
59
  /** Test seam invoked after a complete temporary file is synced and before publication. */
53
60
  beforePublish?(targetPath: string, temporaryPath: string): Promise<void> | void;
@@ -88,14 +95,45 @@ export class NotesStorage {
88
95
  }
89
96
 
90
97
  async readNote(relativePath: string, signal?: AbortSignal): Promise<NoteSnapshot> {
91
- const resolved = await resolveExistingMarkdown(this.paths.notes, relativePath, signal);
98
+ const resolved = await resolveExistingMarkdown(this.paths.notes, relativePath, "Note", signal);
92
99
  const content = await readBoundedMarkdown(resolved.absolutePath, "Note", signal);
93
100
  return snapshot(resolved.relativePath, content);
94
101
  }
95
102
 
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);
103
+ async resolveCanonicalNotePath(relativePath: string, signal?: AbortSignal): Promise<string> {
104
+ return (await resolveExistingMarkdown(this.paths.notes, relativePath, "Note", signal)).absolutePath;
105
+ }
106
+
107
+ async deleteNote(relativePath: string, expectedRevision: string, signal?: AbortSignal): Promise<void> {
108
+ const normalized = normalizeExistingMarkdownPath(relativePath);
109
+ const root = await canonicalDirectory(this.paths.notes, signal);
110
+ const target = resolve(root, ...normalized.split("/"));
111
+ assertContained(root, target);
112
+ await withFileMutationQueue(root, async () => {
113
+ throwIfAborted(signal);
114
+ const resolved = await resolveExistingMarkdown(root, normalized, "Note", signal);
115
+ const current = await readBoundedMarkdown(resolved.absolutePath, "Note", signal);
116
+ if (revisionFor(current) !== expectedRevision) {
117
+ throw new Error("Note revision is stale; read the current note before deleting it");
118
+ }
119
+ throwIfAborted(signal);
120
+ const latest = await resolveExistingMarkdown(root, normalized, "Note", signal);
121
+ if (latest.absolutePath !== resolved.absolutePath) {
122
+ throw new Error("Note path changed before deletion; read it again");
123
+ }
124
+ const latestContent = await readBoundedMarkdown(latest.absolutePath, "Note", signal);
125
+ if (revisionFor(latestContent) !== expectedRevision) {
126
+ throw new Error("Note changed before deletion; read it again");
127
+ }
128
+ throwIfAborted(signal);
129
+ await unlink(latest.absolutePath);
130
+ });
131
+ }
132
+
133
+ async readTemplate(relativePath: string, signal?: AbortSignal): Promise<TemplateSnapshot> {
134
+ const resolved = await resolveExistingMarkdown(this.paths.templates, relativePath, "Template", signal);
135
+ const content = await readBoundedMarkdown(resolved.absolutePath, "Template", signal);
136
+ return snapshot(resolved.relativePath, content);
99
137
  }
100
138
 
101
139
  async createNote(
@@ -103,12 +141,13 @@ export class NotesStorage {
103
141
  options: { templatePath?: string; signal?: AbortSignal } = {},
104
142
  ): Promise<NoteSnapshot> {
105
143
  const normalized = normalizeRelativeMarkdownPath(relativePath);
106
- const content = options.templatePath ? await this.readTemplate(options.templatePath, options.signal) : "";
144
+ const content = options.templatePath ? (await this.readTemplate(options.templatePath, options.signal)).content : "";
107
145
  validateMarkdownContent(content, "Note");
108
146
  const root = await canonicalDirectory(this.paths.notes, options.signal);
109
147
  const target = resolve(root, ...normalized.split("/"));
110
148
  assertContained(root, target);
111
- return withFileMutationQueue(target, async () => {
149
+ // One canonical root key serializes destination aliases on case-insensitive filesystems.
150
+ return withFileMutationQueue(root, async () => {
112
151
  await ensureSafeParent(root, dirname(target), options.signal);
113
152
  throwIfAborted(options.signal);
114
153
  await assertMissingNote(target, normalized, options.signal);
@@ -117,6 +156,71 @@ export class NotesStorage {
117
156
  });
118
157
  }
119
158
 
159
+ async createAutomaticNote(options: { templatePath?: string; signal?: AbortSignal } = {}): Promise<NoteSnapshot> {
160
+ const content = options.templatePath ? (await this.readTemplate(options.templatePath, options.signal)).content : "";
161
+ validateMarkdownContent(content, "Note");
162
+ const root = await canonicalDirectory(this.paths.notes, options.signal);
163
+ const sessionsRoot = await canonicalDirectory(this.paths.sessions, options.signal);
164
+ return withFileMutationQueue(root, async () => {
165
+ const createIfAvailable = async (relativePath: string): Promise<NoteSnapshot | undefined> => {
166
+ const target = resolve(root, relativePath);
167
+ if (await entryExists(join(sessionsRoot, noteSessionKey(relativePath)), options.signal)) return undefined;
168
+ try {
169
+ await assertMissingNote(target, relativePath, options.signal);
170
+ await atomicCreate(root, target, relativePath, content, options.signal, this.beforePublish);
171
+ return snapshot(relativePath, content);
172
+ } catch (error) {
173
+ if (!(error instanceof NoteAlreadyExistsError)) throw error;
174
+ return undefined;
175
+ }
176
+ };
177
+
178
+ for (let index = 1; index <= MAX_DISCOVERED_FILES + 1; index += 1) {
179
+ throwIfAborted(options.signal);
180
+ const note = await createIfAvailable(index === 1 ? "untitled.md" : `untitled-${index}.md`);
181
+ if (note) return note;
182
+ }
183
+ while (true) {
184
+ throwIfAborted(options.signal);
185
+ const note = await createIfAvailable(`untitled-${randomUUID()}.md`);
186
+ if (note) return note;
187
+ }
188
+ });
189
+ }
190
+
191
+ async renameNote(
192
+ relativePath: string,
193
+ expectedRevision: string,
194
+ newRelativePath: string,
195
+ signal?: AbortSignal,
196
+ ): Promise<NoteSnapshot> {
197
+ const normalized = normalizeExistingMarkdownPath(relativePath);
198
+ const renamed = normalizeRelativeMarkdownPath(newRelativePath);
199
+ if (renamed.split("/").length - 1 > MAX_SCAN_DEPTH) {
200
+ throw new Error(`Rename destination must contain at most ${MAX_SCAN_DEPTH} parent directories`);
201
+ }
202
+ if (renamed === normalized) throw new Error(`The current note is already named ${renamed}`);
203
+ const root = await canonicalDirectory(this.paths.notes, signal);
204
+ const source = resolve(root, ...normalized.split("/"));
205
+ const target = resolve(root, ...renamed.split("/"));
206
+ assertContained(root, source);
207
+ assertContained(root, target);
208
+ return withFileMutationQueue(root, async () => {
209
+ throwIfAborted(signal);
210
+ const current = await this.readNote(normalized, signal);
211
+ assertRevision(current, expectedRevision);
212
+ await ensureSafeParent(root, dirname(target), signal);
213
+ await assertMissingNote(target, renamed, signal);
214
+ await revalidateCanonicalParent(root, target, signal);
215
+ const latest = await this.readNote(normalized, signal);
216
+ assertRevision(latest, expectedRevision);
217
+ await assertMissingNote(target, renamed, signal);
218
+ throwIfAborted(signal);
219
+ await rename(source, target);
220
+ return snapshot(renamed, latest.content);
221
+ });
222
+ }
223
+
120
224
  async editNote(
121
225
  relativePath: string,
122
226
  expectedRevision: string,
@@ -126,8 +230,10 @@ export class NotesStorage {
126
230
  ): Promise<NoteSnapshot> {
127
231
  if (!oldText) throw new Error("oldText must not be empty; use replace_current_note for a full replacement");
128
232
  const normalized = normalizeExistingMarkdownPath(relativePath);
129
- const queuePath = resolve(this.paths.notes, ...normalized.split("/"));
130
- return withFileMutationQueue(queuePath, async () => {
233
+ const root = await canonicalDirectory(this.paths.notes, signal);
234
+ const target = resolve(root, ...normalized.split("/"));
235
+ assertContained(root, target);
236
+ return withFileMutationQueue(root, async () => {
131
237
  throwIfAborted(signal);
132
238
  const current = await this.readNote(normalized, signal);
133
239
  assertRevision(current, expectedRevision);
@@ -138,7 +244,7 @@ export class NotesStorage {
138
244
  }
139
245
  const content = `${current.content.slice(0, index)}${newText}${current.content.slice(index + oldText.length)}`;
140
246
  validateMarkdownContent(content, "Note");
141
- await atomicReplace(this.paths.notes, queuePath, content, current.revision, signal, this.beforePublish);
247
+ await atomicReplace(root, target, content, current.revision, "Note", signal, this.beforePublish);
142
248
  return snapshot(normalized, content);
143
249
  });
144
250
  }
@@ -151,12 +257,34 @@ export class NotesStorage {
151
257
  ): Promise<NoteSnapshot> {
152
258
  const normalized = normalizeExistingMarkdownPath(relativePath);
153
259
  validateMarkdownContent(content, "Note");
154
- const queuePath = resolve(this.paths.notes, ...normalized.split("/"));
155
- return withFileMutationQueue(queuePath, async () => {
260
+ const root = await canonicalDirectory(this.paths.notes, signal);
261
+ const target = resolve(root, ...normalized.split("/"));
262
+ assertContained(root, target);
263
+ return withFileMutationQueue(root, async () => {
156
264
  throwIfAborted(signal);
157
265
  const current = await this.readNote(normalized, signal);
158
266
  assertRevision(current, expectedRevision);
159
- await atomicReplace(this.paths.notes, queuePath, content, current.revision, signal, this.beforePublish);
267
+ await atomicReplace(root, target, content, current.revision, "Note", signal, this.beforePublish);
268
+ return snapshot(normalized, content);
269
+ });
270
+ }
271
+
272
+ async replaceTemplate(
273
+ relativePath: string,
274
+ expectedRevision: string,
275
+ content: string,
276
+ signal?: AbortSignal,
277
+ ): Promise<TemplateSnapshot> {
278
+ const normalized = normalizeExistingMarkdownPath(relativePath);
279
+ validateMarkdownContent(content, "Template");
280
+ const root = await canonicalDirectory(this.paths.templates, signal);
281
+ const target = resolve(root, ...normalized.split("/"));
282
+ assertContained(root, target);
283
+ return withFileMutationQueue(root, async () => {
284
+ throwIfAborted(signal);
285
+ const current = await this.readTemplate(normalized, signal);
286
+ assertRevision(current, expectedRevision, "Template");
287
+ await atomicReplace(root, target, content, current.revision, "Template", signal, this.beforePublish);
160
288
  return snapshot(normalized, content);
161
289
  });
162
290
  }
@@ -198,6 +326,10 @@ export function revisionFor(content: string): string {
198
326
  return createHash("sha256").update(content).digest("hex");
199
327
  }
200
328
 
329
+ export function noteSessionKey(notePath: string): string {
330
+ return createHash("sha256").update(notePath).digest("hex");
331
+ }
332
+
201
333
  export function validateMarkdownContent(content: string, label: string): void {
202
334
  const bytes = Buffer.byteLength(content, "utf8");
203
335
  if (bytes > MAX_MARKDOWN_BYTES) {
@@ -300,6 +432,7 @@ async function discoverMarkdown(rootPath: string, signal?: AbortSignal): Promise
300
432
  async function resolveExistingMarkdown(
301
433
  rootPath: string,
302
434
  relativePath: string,
435
+ label: string,
303
436
  signal?: AbortSignal,
304
437
  ): Promise<{ relativePath: string; absolutePath: string }> {
305
438
  const normalized = normalizeExistingMarkdownPath(relativePath);
@@ -309,12 +442,12 @@ async function resolveExistingMarkdown(
309
442
  throwIfAborted(signal);
310
443
  const linkInfo = await lstat(candidate);
311
444
  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}`);
445
+ if (linkInfo.isSymbolicLink()) throw new Error(`${label} path is a symbolic link: ${normalized}`);
446
+ if (!linkInfo.isFile()) throw new Error(`${label} is not a regular file: ${normalized}`);
314
447
  const canonical = await realpath(candidate);
315
448
  throwIfAborted(signal);
316
449
  assertContained(root, canonical);
317
- if (canonical !== candidate) throw new Error(`Note path is not canonical: ${normalized}`);
450
+ if (canonical !== candidate) throw new Error(`${label} path is not canonical: ${normalized}`);
318
451
  return { relativePath: normalized, absolutePath: canonical };
319
452
  }
320
453
 
@@ -403,29 +536,45 @@ async function atomicCreate(
403
536
  }
404
537
  }
405
538
 
539
+ class NoteAlreadyExistsError extends Error {}
540
+
406
541
  async function assertMissingNote(targetPath: string, relativePath: string, signal?: AbortSignal): Promise<void> {
407
542
  throwIfAborted(signal);
408
543
  try {
409
544
  await lstat(targetPath);
410
- throw new Error(`Note already exists: ${relativePath}`);
545
+ throw new NoteAlreadyExistsError(`Note already exists: ${relativePath}`);
411
546
  } catch (error) {
412
547
  if (!isNodeError(error, "ENOENT")) throw error;
413
548
  }
414
549
  throwIfAborted(signal);
415
550
  }
416
551
 
552
+ async function entryExists(path: string, signal?: AbortSignal): Promise<boolean> {
553
+ throwIfAborted(signal);
554
+ try {
555
+ await lstat(path);
556
+ throwIfAborted(signal);
557
+ return true;
558
+ } catch (error) {
559
+ if (!isNodeError(error, "ENOENT")) throw error;
560
+ throwIfAborted(signal);
561
+ return false;
562
+ }
563
+ }
564
+
417
565
  async function atomicReplace(
418
566
  rootPath: string,
419
567
  targetPath: string,
420
568
  content: string,
421
569
  expectedRevision: string,
570
+ label: string,
422
571
  signal?: AbortSignal,
423
572
  beforePublish?: NotesStorageOptions["beforePublish"],
424
573
  ): Promise<void> {
425
574
  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");
575
+ const resolved = await resolveExistingMarkdown(rootPath, relativePath, label, signal);
576
+ const current = await readBoundedMarkdown(resolved.absolutePath, label, signal);
577
+ if (revisionFor(current) !== expectedRevision) throw new Error(`${label} changed before publication; read it again`);
429
578
  const info = await stat(resolved.absolutePath);
430
579
  throwIfAborted(signal);
431
580
  const temporaryPath = temporaryName(targetPath);
@@ -434,12 +583,14 @@ async function atomicReplace(
434
583
  throwIfAborted(signal);
435
584
  await beforePublish?.(targetPath, temporaryPath);
436
585
  throwIfAborted(signal);
437
- const latestResolved = await resolveExistingMarkdown(rootPath, relativePath, signal);
586
+ const latestResolved = await resolveExistingMarkdown(rootPath, relativePath, label, signal);
438
587
  if (latestResolved.absolutePath !== resolved.absolutePath) {
439
- throw new Error("Note path changed before publication; read it again");
588
+ throw new Error(`${label} path changed before publication; read it again`);
589
+ }
590
+ const latest = await readBoundedMarkdown(latestResolved.absolutePath, label, signal);
591
+ if (revisionFor(latest) !== expectedRevision) {
592
+ throw new Error(`${label} changed before publication; read it again`);
440
593
  }
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
594
  throwIfAborted(signal);
444
595
  await rename(temporaryPath, latestResolved.absolutePath);
445
596
  } catch (error) {
@@ -481,9 +632,10 @@ function snapshot(relativePath: string, content: string): NoteSnapshot {
481
632
  };
482
633
  }
483
634
 
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");
635
+ function assertRevision(current: NoteSnapshot | TemplateSnapshot, expectedRevision: string, label = "Note"): void {
636
+ if (current.revision !== expectedRevision) {
637
+ throw new Error(`${label} revision is stale; read the current ${label.toLowerCase()} before editing`);
638
+ }
487
639
  }
488
640
 
489
641
  function assertContained(root: string, candidate: string): void {