From e2b0524f5ae694a0b6abab57a7fc45b70b1cfe03 Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Thu, 15 Oct 2026 02:39:15 -0500 Subject: [PATCH 1/8] Add NotesStore: Space pages as Markdown files under MODEX_HOME/notes The first slice of notes in folders. NotesStore keeps SpaceStore's page contract (ids, revisions, 30-second typing checkpoints, cascading trash and restore, revert, comments, the same error texts) over a folder laid out Workspace > Project > folders, with Personal > Notes as the default. Each note carries modex_id frontmatter, so moves, renames and crashes never lose which page a file is; a page with children is a folder that holds a folder note of the same name. Version history, comments, trash batches and a last-seen index live in .modex/. Writes go history, note, index, and reading finishes whatever a crash interrupted. Edits, moves, new files and deletions made outside Modex become versions of their own. Migration builds the folder beside notes/ from app/space.json and publishes it with one rename, never writes space.json, keeps a backup, and recovers pages an older build changes later. Modex does not use it yet; SpaceStore now exports its reader and validators and a SpacePagesStore interface for the switch. Coven-Harness: Claude Code / claude-opus-5-5 --- apps/desktop/src/main/engine/durable-file.ts | 49 ++ .../src/main/engine/notes-frontmatter.ts | 55 ++ .../src/main/engine/notes-migration.ts | 58 ++ apps/desktop/src/main/engine/notes-store.ts | 832 ++++++++++++++++++ apps/desktop/src/main/engine/space-store.ts | 65 +- apps/desktop/src/shared/notes-names.ts | 57 ++ apps/desktop/test/notes-files.test.ts | 68 ++ apps/desktop/test/notes-migration.test.ts | 154 ++++ apps/desktop/test/notes-store.test.ts | 265 ++++++ docs/notes.md | 86 ++ docs/status.md | 6 + 11 files changed, 1672 insertions(+), 23 deletions(-) create mode 100644 apps/desktop/src/main/engine/durable-file.ts create mode 100644 apps/desktop/src/main/engine/notes-frontmatter.ts create mode 100644 apps/desktop/src/main/engine/notes-migration.ts create mode 100644 apps/desktop/src/main/engine/notes-store.ts create mode 100644 apps/desktop/src/shared/notes-names.ts create mode 100644 apps/desktop/test/notes-files.test.ts create mode 100644 apps/desktop/test/notes-migration.test.ts create mode 100644 apps/desktop/test/notes-store.test.ts create mode 100644 docs/notes.md diff --git a/apps/desktop/src/main/engine/durable-file.ts b/apps/desktop/src/main/engine/durable-file.ts new file mode 100644 index 00000000..adb5538a --- /dev/null +++ b/apps/desktop/src/main/engine/durable-file.ts @@ -0,0 +1,49 @@ +import fs from "node:fs"; +import path from "node:path"; +import { randomUUID } from "node:crypto"; + +/** Flushes a directory's entries (a rename or a new file) to disk. A no-op on Windows, which cannot open directories. */ +export function fsyncDir(dir: string): void { + if (process.platform === "win32") return; + const fd = fs.openSync(dir, "r"); + try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); } +} + +/** + * Replaces `file` with `data` atomically: a hidden temporary file beside it (exclusive, never through + * a link, mode 0600) is flushed, renamed over the target, and the directory is flushed. A crash leaves + * either the old file or the new one, never a mix. + */ +export function writeFileDurably(file: string, data: string | Uint8Array): void { + const dir = path.dirname(file); + const temporary = path.join(dir, `.${path.basename(file)}.${randomUUID()}.tmp`); + let fd: number | undefined; + try { + fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600); + fs.writeFileSync(fd, data); + fs.fsyncSync(fd); + fs.closeSync(fd); + fd = undefined; + fs.renameSync(temporary, file); + fsyncDir(dir); + } finally { + if (fd !== undefined) fs.closeSync(fd); + fs.rmSync(temporary, { force: true }); + } +} + +/** Moves a file or folder to `target`, failing with EEXIST rather than replacing anything already there. */ +export function moveNoClobber(source: string, target: string): void { + fs.mkdirSync(path.dirname(target), { recursive: true }); + const stat = fs.lstatSync(source); + if (stat.isDirectory()) { + if (fs.existsSync(target)) throw Object.assign(new Error(`${target} already exists`), { code: "EEXIST" }); + fs.renameSync(source, target); + } else { + // A hard link refuses an existing target atomically; the source then goes. + fs.linkSync(source, target); + fs.unlinkSync(source); + } + fsyncDir(path.dirname(target)); + if (path.dirname(source) !== path.dirname(target)) fsyncDir(path.dirname(source)); +} diff --git a/apps/desktop/src/main/engine/notes-frontmatter.ts b/apps/desktop/src/main/engine/notes-frontmatter.ts new file mode 100644 index 00000000..a6ba2ee4 --- /dev/null +++ b/apps/desktop/src/main/engine/notes-frontmatter.ts @@ -0,0 +1,55 @@ +import { Document, isMap, parseDocument } from "yaml"; + +/** What Modex reads from a note file. `body` is exactly the text after the frontmatter. */ +export interface ParsedNote { + /** `modex_id` from the frontmatter, when it is a string. */ + id?: string; + /** `title` from the frontmatter, when it is a string; otherwise the title is the file name. */ + title?: string; + body: string; + /** Whether the file has frontmatter Modex can edit (a YAML mapping). */ + frontmatter: boolean; +} + +/** + * Splits `text` into frontmatter and body. Frontmatter opens only with a first line of exactly `---` + * and closes at the next line of exactly `---`; anything else is all body. + */ +export function splitFrontmatter(text: string): { yaml: string; body: string } | null { + const open = /^---\r?\n/.exec(text); + if (!open) return null; + const rest = text.slice(open[0].length); + const close = /^---\r?(?:\n|$)/m.exec(rest); + if (!close) return null; + return { yaml: rest.slice(0, close.index), body: rest.slice(close.index + close[0].length) }; +} + +function mapping(yaml: string): Document | null { + let doc: Document; + try { doc = parseDocument(yaml); } catch { return null; } + if (doc.errors.length) return null; + if (doc.contents === null) return new Document({}); + return isMap(doc.contents) ? doc : null; +} + +export function parseNote(text: string): ParsedNote { + const split = splitFrontmatter(text); + const doc = split && mapping(split.yaml); + if (!split || !doc) return { body: text, frontmatter: false }; + const id = doc.get("modex_id"); + const title = doc.get("title"); + return { ...(typeof id === "string" ? { id } : {}), ...(typeof title === "string" ? { title } : {}), body: split.body, frontmatter: true }; +} + +/** + * The file text for a note. Keeps every other key (and comment) of `previous`'s frontmatter, sets + * `modex_id`, and writes `title` only when the file name cannot carry it exactly. + */ +export function formatNote(note: { id: string; title: string; stem: string; body: string }, previous?: string): string { + const split = previous === undefined ? null : splitFrontmatter(previous); + const doc = (split && mapping(split.yaml)) ?? new Document({}); + doc.set("modex_id", note.id); + if (note.title !== note.stem) doc.set("title", note.title); + else doc.delete("title"); + return `---\n${doc.toString({ lineWidth: 0 })}---\n${note.body}`; +} diff --git a/apps/desktop/src/main/engine/notes-migration.ts b/apps/desktop/src/main/engine/notes-migration.ts new file mode 100644 index 00000000..1f11ff78 --- /dev/null +++ b/apps/desktop/src/main/engine/notes-migration.ts @@ -0,0 +1,58 @@ +import type { SpacePage } from "../../shared/space.js"; +import { noteStem, uniqueName } from "../../shared/notes-names.js"; + +/** Where one page of `space.json` goes. `rel` is the note file, relative to the notes root, with `/` separators. */ +export interface PlannedNote { id: string; rel: string; folder: boolean; trashed: boolean } +export interface MigrationPlan { notes: PlannedNote[]; warnings: string[] } + +/** + * Lays out `pages` under `projectRel`. A page with any child, live or trashed, becomes a folder that + * holds its own folder note (`Plan/Plan.md`); a leaf becomes `Name.md`. Names are made safe and unique + * per folder, next to what `taken` reports already on disk. Parents come before their children. + */ +export function planMigration(pages: SpacePage[], projectRel: string, taken: (dirRel: string) => string[] = () => []): MigrationPlan { + const byId = new Map(pages.map(page => [page.id, page])); + const children = new Map(); + const warnings: string[] = []; + for (const page of pages) { + let parent = page.parentId; + if (parent !== null && !byId.has(parent)) { + warnings.push(`"${page.title || "Untitled page"}" pointed to a missing parent page and was placed at the top level.`); + parent = null; + } + children.set(parent, [...(children.get(parent) ?? []), page]); + } + const used = new Map(); + const claim = (dirRel: string, stem: string, ext: string): string => { + const names = used.get(dirRel) ?? taken(dirRel); + const name = uniqueName(stem, ext, names); + used.set(dirRel, [...names, name]); + return name; + }; + const notes: PlannedNote[] = []; + const visited = new Set(); + const place = (parent: string | null, dirRel: string) => { + for (const page of children.get(parent) ?? []) { + if (visited.has(page.id)) continue; + visited.add(page.id); + const stem = noteStem(page.title); + const folder = (children.get(page.id)?.length ?? 0) > 0; + if (folder) { + const dir = claim(dirRel, stem, ""); + notes.push({ id: page.id, rel: `${dirRel}/${dir}/${dir}.md`, folder: true, trashed: page.trashedAt !== null }); + place(page.id, `${dirRel}/${dir}`); + } else { + notes.push({ id: page.id, rel: `${dirRel}/${claim(dirRel, stem, ".md")}`, folder: false, trashed: page.trashedAt !== null }); + } + } + }; + place(null, projectRel); + // A parent cycle cannot come from a valid document; place any remainder at the top level rather than lose it. + for (const page of pages) { + if (visited.has(page.id)) continue; + warnings.push(`"${page.title || "Untitled page"}" was part of a parent loop and was placed at the top level.`); + visited.add(page.id); + notes.push({ id: page.id, rel: `${projectRel}/${claim(projectRel, noteStem(page.title), ".md")}`, folder: false, trashed: page.trashedAt !== null }); + } + return { notes, warnings }; +} diff --git a/apps/desktop/src/main/engine/notes-store.ts b/apps/desktop/src/main/engine/notes-store.ts new file mode 100644 index 00000000..e32349db --- /dev/null +++ b/apps/desktop/src/main/engine/notes-store.ts @@ -0,0 +1,832 @@ +import fs from "node:fs"; +import path from "node:path"; +import { createHash, randomUUID } from "node:crypto"; +import type { CreateSpacePage, SpaceChangeContext, SpaceComment, SpacePage, SpacePageVersion } from "../../shared/space.js"; +import { nameKey, noteStem, uniqueName } from "../../shared/notes-names.js"; +import { formatNote, parseNote, type ParsedNote } from "./notes-frontmatter.js"; +import { fsyncDir, moveNoClobber, writeFileDurably } from "./durable-file.js"; +import { planMigration } from "./notes-migration.js"; +import { readSpaceDocument, validate, validateChange, validateComment, type SpaceDocument, type SpacePagesStore } from "./space-store.js"; + +const ID = /^[a-z0-9-]{1,64}$/i; +/** A note file larger than this is listed as a plain file, not a page. */ +const MAX_NOTE_BYTES = 2 * 1024 * 1024; +const MAX_DEPTH = 30; +const CHECKPOINT_MS = 30_000; +/** A file must be missing on two scans this far apart before it counts as deleted outside Modex. */ +const MISSING_MS = 1_000; +export const DEFAULT_WORKSPACE = "Personal"; +export const DEFAULT_PROJECT = "Notes"; +const utf8 = new TextDecoder("utf-8", { fatal: true }); + +interface IndexEntry { + /** Where the note file was last seen, or null when it is in the trash or gone. */ + rel: string | null; + /** sha256 of the file as Modex last wrote or confirmed it. */ + hash: string | null; + ino?: number; + trash?: { batch: string; rel: string; original: string }; + /** Where a note deleted outside Modex lived, so a restore writes it back there. */ + original?: string; +} +interface NotesIndex { version: 1; defaultProject: string; notes: Record } +interface HistoryFile { version: 1; versions: SpacePageVersion[] } +interface TrashManifest { version: 1; id: string; trashedAt: string; items: { id: string; original: string; rel: string }[] } +export interface MigrationReceipt { + version: 1; + /** `app/space.json` when pages were migrated from it; null for a fresh folder. */ + source: string | null; + sha256: string | null; + migratedAt: string; + revisions: Record; + mapping: Record; + warnings: string[]; +} +interface LiveNote { rel: string; ino: number; size: number; mtimeMs: number; hash: string; parsed: ParsedNote } +interface State { pages: Map; index: NotesIndex; live: Map } + +export interface NotesStoreOptions { + /** This home's `app/space.json`: migrated into the folder once, then left as it is. */ + legacySpaceFile?: string; + /** Milliseconds since the epoch; tests move it. */ + now?: () => number; +} + +const sha256 = (data: string | Uint8Array) => createHash("sha256").update(data).digest("hex"); +const preserved = (error: unknown) => new Error(`Space could not read saved pages. Your file has been preserved. ${(error as Error).message}`); +const byCreation = (a: SpacePage, b: SpacePage) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); +const stemOf = (rel: string) => path.posix.basename(rel).replace(/\.md$/i, ""); +const depth = (dirRel: string) => (dirRel ? dirRel.split("/").length : 0); + +/** + * Space pages as Markdown files under `MODEX_HOME/notes/`, laid out Workspace › Project › folders. + * + * Each note carries its id in `modex_id` frontmatter, so a move or a crash never loses which page a + * file is. A page with children is a folder holding a folder note of the same name. Modex keeps the + * rest in `.modex/` (hidden from Open Knowledge and Finder's listing): one version history per page + * (the newest version is the page, as in SpaceStore), comments, trash batches, and an index of where + * each file was last seen. Writes go history, then note, then index; reading reconciles whatever a + * crash left half-done, and records edits made outside Modex as versions of their own. + */ +export class NotesStore implements SpacePagesStore { + readonly root: string; + private readonly meta: string; + private readonly now: () => number; + private opened = false; + private readonly missing = new Map(); + private readonly fileCache = new Map(); + private readonly historyCache = new Map(); + + constructor(root: string, private readonly options: NotesStoreOptions = {}) { + this.root = path.resolve(root); + this.meta = path.join(this.root, ".modex"); + this.now = options.now ?? Date.now; + } + + list(): SpacePage[] { return [...this.load().pages.values()].sort(byCreation); } + + comments(pageId: string): SpaceComment[] { + this.find(this.load(), pageId); + return this.readComments(pageId); + } + + addComment(pageId: string, text: string, quote: string): SpaceComment { + const state = this.load(); + if (this.find(state, pageId).trashedAt) throw new Error("Restore this page before commenting on it."); + const comment: SpaceComment = { id: randomUUID(), pageId, text: typeof text === "string" ? text.trim() : text, quote, createdAt: this.iso() }; + validateComment(comment); + this.writeJson(this.commentsFile(pageId), [...this.readComments(pageId), comment]); + return comment; + } + + deleteComment(pageId: string, id: string): void { + this.find(this.load(), pageId); + this.writeJson(this.commentsFile(pageId), this.readComments(pageId).filter(comment => comment.id !== id)); + } + + /** Versions oldest first. */ + history(id: string): SpacePageVersion[] { + this.find(this.load(), id); + return [...(this.readHistory(id) ?? [])]; + } + + create(input: CreateSpacePage, change?: SpaceChangeContext): SpacePage { + const state = this.load(); + const now = this.iso(); + const page: SpacePage = { id: randomUUID(), parentId: input.parentId ?? null, title: input.title ?? "", markdown: input.markdown ?? "", favorite: false, createdAt: now, updatedAt: now, trashedAt: null, revision: 1 }; + validate(page); + this.validateParent(page, state.pages); + const version = this.version(page, change, "Created page"); + const dir = this.dirFor(state, page.parentId, state.index.defaultProject); + const rel = `${dir}/${uniqueName(noteStem(page.title), ".md", this.names(dir))}`; + this.writeHistory(page.id, [version]); + this.writeNoteAt(state, page, rel); + this.writeIndex(state.index); + return page; + } + + save(input: SpacePage, change?: SpaceChangeContext): SpacePage { + validate(input); + const state = this.load(); + const current = this.find(state, input.id); + this.checkRevision(current, input.revision); + if (current.trashedAt) throw new Error("Restore this page before editing it."); + this.validateParent(input, state.pages); + const page: SpacePage = { ...current, title: input.title, markdown: input.markdown, favorite: input.favorite, parentId: input.parentId, updatedAt: this.iso(), revision: current.revision + 1 }; + const version = this.version(page, change, "Updated page"); + this.writeHistory(page.id, this.appendVersion(this.readHistory(page.id) ?? [], version, change ? null : "human")); + state.pages.set(page.id, page); + let rel = this.liveRel(state, page.id); + if (page.parentId !== current.parentId) rel = this.move(state, page.id, page.parentId); + this.writeNoteAt(state, page, rel); + this.writeIndex(state.index); + return page; + } + + trash(id: string, trash: boolean, revision?: number, change?: SpaceChangeContext): SpacePage[] { + const state = this.load(); + const current = this.find(state, id); + if (revision !== undefined) this.checkRevision(current, revision); + if (typeof trash !== "boolean") throw new Error("Invalid trash action."); + const pages = [...state.pages.values()]; + const affected = new Set([id]); + let grew = true; + while (grew) { + grew = false; + for (const p of pages) if (p.parentId && affected.has(p.parentId) && !affected.has(p.id)) { affected.add(p.id); grew = true; } + } + // Reachable ancestors do not broaden a restore into unrelated sibling subtrees. + if (!trash) { + let parent = current.parentId; + const visited = new Set(); + while (parent && !visited.has(parent)) { visited.add(parent); affected.add(parent); parent = state.pages.get(parent)?.parentId ?? null; } + } + const now = this.iso(); + const next = pages.filter(p => affected.has(p.id)).map(p => ({ ...p, trashedAt: trash ? now : null, updatedAt: now, revision: p.revision + 1 })); + const versions = next.map(p => ({ page: p, ...this.attribution(change, trash ? "Moved page to Trash" : "Restored page") })); + if (trash) { + const batch = randomUUID(); + const items = next.filter(p => state.live.has(p.id)).map(p => ({ id: p.id, original: state.live.get(p.id)!.rel, rel: state.live.get(p.id)!.rel })); + if (items.length) this.writeJson(this.manifestFile(batch), { version: 1, id: batch, trashedAt: now, items } satisfies TrashManifest); + for (const v of versions) this.writeHistory(v.page.id, [...(this.readHistory(v.page.id) ?? []), v]); + // Deepest first, so a folder note leaves its folder after its children. + for (const item of [...items].sort((a, b) => b.original.split("/").length - a.original.split("/").length)) { + moveNoClobber(this.abs(item.original), this.trashAbs(batch, item.rel)); + state.index.notes[item.id] = { rel: null, hash: state.index.notes[item.id]?.hash ?? null, trash: { batch, rel: item.rel, original: item.original } }; + state.live.delete(item.id); + this.removeEmptyDirs(path.posix.dirname(item.original)); + } + } else { + for (const v of versions) this.writeHistory(v.page.id, [...(this.readHistory(v.page.id) ?? []), v]); + for (const p of next) state.pages.set(p.id, p); + // Parents first, so each folder exists before its notes return to it. + const order = next.map(p => ({ page: p, original: state.index.notes[p.id]?.trash?.original ?? state.index.notes[p.id]?.rel ?? "" })) + .sort((a, b) => a.original.split("/").length - b.original.split("/").length); + for (const { page } of order) if (!state.live.has(page.id)) this.restoreFile(state, page); + } + for (const p of next) state.pages.set(p.id, p); + this.writeIndex(state.index); + return [...state.pages.values()].sort(byCreation); + } + + revert(id: string, expectedRevision: number, versionRevision: number, change?: SpaceChangeContext): SpacePage { + const state = this.load(); + const current = this.find(state, id); + this.checkRevision(current, expectedRevision); + if (current.trashedAt) throw new Error("Restore this page before editing it."); + const version = (this.readHistory(id) ?? []).find(v => v.page.revision === versionRevision); + if (!version) throw new Error("This Space page version does not exist."); + return this.save({ ...version.page, revision: current.revision }, change ?? { actor: "human", summary: `Reverted to revision ${versionRevision}` }); + } + + /** + * Renames a page's file (and its folder, for a folder note) to match its title. Typing never renames + * a file, which would churn Open Knowledge's file tree; the renderer settles a page when its title + * loses focus or another page opens. + */ + settle(id: string): SpacePage { + const state = this.load(); + const page = this.find(state, id); + const live = state.live.get(id); + if (page.trashedAt || !live) return page; + const stem = noteStem(page.title); + if (stemOf(live.rel) === stem) return page; + const dir = path.posix.dirname(live.rel); + if (this.isFolderNote(live.rel)) { + const parent = path.posix.dirname(dir); + const name = nameKey(path.posix.basename(dir)) === nameKey(stem) ? stem : uniqueName(stem, "", this.names(parent).filter(n => nameKey(n) !== nameKey(path.posix.basename(dir)))); + const target = `${parent}/${name}`; + if (target !== dir) fs.renameSync(this.abs(dir), this.abs(target)); + this.rebase(state, dir, target); + const from = `${target}/${path.posix.basename(live.rel)}`; + this.renameNote(state, page, from, `${target}/${name}.md`); + } else { + const name = uniqueName(stem, ".md", this.names(dir).filter(n => nameKey(n) !== nameKey(path.posix.basename(live.rel)))); + this.renameNote(state, page, live.rel, `${dir}/${name}`); + } + this.writeIndex(state.index); + return page; + } + + // ── Reading and reconciling ────────────────────────────────────────────────────────────── + + private load(): State { + this.open(); + let state = this.refresh(); + // Completing a move a crash interrupted changes the tree; read it once more. + if (state === null) state = this.refresh(); + if (state === null) throw preserved(new Error("Notes kept changing while Modex read them.")); + return state; + } + + /** The current pages, after recording what changed on disk. Null when it moved files and must read again. */ + private refresh(): State | null { + const index = this.readIndex(); + const manifests = this.readManifests(); + const scanned = this.scan(); + const live = this.identify(scanned, index); + const ids = new Set([...live.keys(), ...Object.keys(index.notes)]); + const histories = new Map(); + for (const id of ids) histories.set(id, this.readHistory(id)); + + // Finish trash moves and restores a crash interrupted. + let moved = false; + for (const [id, file] of live) { + const latest = histories.get(id)?.at(-1)?.page; + const entry = index.notes[id]; + if (latest?.trashedAt && entry && !entry.trash && entry.hash === file.hash) { + const item = manifests.flatMap(m => m.items.map(i => ({ batch: m.id, ...i }))).find(i => i.id === id && i.original === file.rel); + const batch = item?.batch ?? randomUUID(); + if (!item) this.writeJson(this.manifestFile(batch), { version: 1, id: batch, trashedAt: latest.trashedAt, items: [{ id, original: file.rel, rel: file.rel }] } satisfies TrashManifest); + moveNoClobber(this.abs(file.rel), this.trashAbs(batch, file.rel)); + index.notes[id] = { rel: null, hash: file.hash, trash: { batch, rel: file.rel, original: file.rel } }; + moved = true; + } + } + for (const [id, entry] of Object.entries(index.notes)) { + const latest = histories.get(id)?.at(-1)?.page; + if (entry.trash?.batch && latest && latest.trashedAt === null && !live.has(id) && fs.existsSync(this.trashAbs(entry.trash.batch, entry.trash.rel))) { + const original = entry.trash.original; + const dir = path.posix.dirname(original); + const target = `${dir}/${uniqueName(stemOf(original), ".md", this.names(dir))}`; + moveNoClobber(this.trashAbs(entry.trash.batch, entry.trash.rel), this.abs(target)); + this.dropFromManifest(entry.trash.batch, id); + index.notes[id] = { rel: target, hash: entry.hash }; + moved = true; + } + } + if (moved) { this.writeIndex(index); return null; } + + const pages = new Map(); + let indexChanged = false; + const folderNotes = new Map(); + for (const [id, file] of live) if (this.isFolderNote(file.rel)) folderNotes.set(nameKey(path.posix.dirname(file.rel)), id); + const parentOf = (rel: string): string | null => { + let dir = path.posix.dirname(rel); + if (this.isFolderNote(rel)) dir = path.posix.dirname(dir); + return depth(dir) >= 3 ? folderNotes.get(nameKey(dir)) ?? null : null; + }; + const now = this.now(); + + for (const [id, file] of live) { + this.missing.delete(id); + const versions = histories.get(id) ?? null; + const title = file.parsed.title ?? stemOf(file.rel); + const body = file.parsed.body; + const parentId = parentOf(file.rel); + const entry = index.notes[id]; + const confirm = () => { + if (entry?.rel !== file.rel || entry.hash !== file.hash || entry.ino !== file.ino || entry.trash) { index.notes[id] = { rel: file.rel, hash: file.hash, ino: file.ino }; indexChanged = true; } + }; + if (!versions) { + const at = new Date(file.mtimeMs).toISOString(); + const page: SpacePage = { id, parentId, title, markdown: body, favorite: false, createdAt: at, updatedAt: at, trashedAt: null, revision: 1 }; + try { validate(page); } catch { continue; } + this.writeHistory(id, [{ page, actor: "external", summary: "Found in notes folder" }]); + pages.set(id, page); + confirm(); + continue; + } + const latest = versions.at(-1)!.page; + if (latest.title === title && latest.markdown === body && latest.parentId === parentId && latest.trashedAt === null) { + pages.set(id, latest); + confirm(); + continue; + } + if (latest.trashedAt === null && entry && !entry.trash && entry.hash === file.hash && entry.rel === file.rel) { + // The file is as Modex last confirmed it and the history is ahead: a crash fell between the two writes. + pages.set(id, latest); + if (latest.parentId === parentId) { + const text = formatNote({ id, title: latest.title, stem: stemOf(file.rel), body: latest.markdown }, this.readText(file.rel)); + writeFileDurably(this.abs(file.rel), text); + index.notes[id] = { rel: file.rel, hash: sha256(text), ino: fs.statSync(this.abs(file.rel)).ino }; + indexChanged = true; + continue; + } + } + const candidate: SpacePage = { ...latest, title, markdown: body, parentId, trashedAt: null, updatedAt: new Date(now).toISOString(), revision: latest.revision + 1 }; + try { validate(candidate); } catch { pages.set(id, latest); continue; } + const summary = latest.trashedAt !== null ? "Restored outside Modex" : latest.title !== title || latest.markdown !== body ? "Edited outside Modex" : "Moved outside Modex"; + this.writeHistory(id, this.appendVersion(versions, { page: candidate, actor: "external", summary }, "external")); + pages.set(id, candidate); + confirm(); + } + + for (const [id, entry] of Object.entries(index.notes)) { + if (live.has(id)) continue; + const versions = histories.get(id); + const latest = versions?.at(-1)?.page; + if (!versions || !latest) continue; + if (latest.trashedAt !== null) { + if (entry.rel && !entry.trash) { + const item = manifests.flatMap(m => m.items.map(i => ({ batch: m.id, ...i }))).find(i => i.id === id); + index.notes[id] = item ? { rel: null, hash: entry.hash, trash: { batch: item.batch, rel: item.rel, original: item.original } } : { rel: null, hash: null }; + indexChanged = true; + } + pages.set(id, latest); + continue; + } + // Live in history, absent on disk: wait one more look before calling it deleted (git checkout, a save that renames). + const first = this.missing.get(id); + if (first === undefined || now - first < MISSING_MS) { + if (first === undefined) this.missing.set(id, now); + pages.set(id, latest); + continue; + } + this.missing.delete(id); + const at = new Date(now).toISOString(); + const gone: SpacePage = { ...latest, trashedAt: at, updatedAt: at, revision: latest.revision + 1 }; + this.writeHistory(id, [...versions, { page: gone, actor: "external", summary: "Deleted outside Modex" }]); + index.notes[id] = { rel: null, hash: null, ...(entry.rel ? { original: entry.rel } : {}) }; + indexChanged = true; + pages.set(id, gone); + } + if (indexChanged) this.writeIndex(index); + return { pages, index, live }; + } + + /** Every Markdown note under the root, skipping dot entries (`.modex`, `.ok`, `.git`), links, and files too large or not UTF-8. */ + private scan(): LiveNote[] { + const out: LiveNote[] = []; + const seen = new Set(); + const walk = (dirRel: string, level: number) => { + let entries: fs.Dirent[]; + try { entries = fs.readdirSync(dirRel ? this.abs(dirRel) : this.root, { withFileTypes: true }); } catch { return; } + for (const entry of entries) { + if (entry.name.startsWith(".") || entry.isSymbolicLink()) continue; + const rel = dirRel ? `${dirRel}/${entry.name}` : entry.name; + if (entry.isDirectory()) { if (level < MAX_DEPTH) walk(rel, level + 1); continue; } + if (!entry.isFile() || !/\.md$/i.test(entry.name)) continue; + const note = this.readLive(rel); + if (note) { out.push(note); seen.add(rel); } + } + }; + walk("", 0); + for (const rel of this.fileCache.keys()) if (!seen.has(rel)) this.fileCache.delete(rel); + return out; + } + + private readLive(rel: string): LiveNote | null { + let stat: fs.Stats; + try { stat = fs.lstatSync(this.abs(rel)); } catch { return null; } + if (!stat.isFile() || stat.size > MAX_NOTE_BYTES) return null; + const cached = this.fileCache.get(rel); + if (cached && cached.ino === stat.ino && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) return cached; + let bytes: Buffer; + let text: string; + try { bytes = fs.readFileSync(this.abs(rel)); text = utf8.decode(bytes); } catch { return null; } + const note: LiveNote = { rel, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs, hash: sha256(bytes), parsed: parseNote(text) }; + this.fileCache.set(rel, note); + return note; + } + + /** + * Which page each file is: its `modex_id`, else the index entry for its path, else the entry for its + * inode (a file moved in Finder), else a new id. A copy that duplicates an id gets a new one; the file + * at the indexed path keeps it. + */ + private identify(files: LiveNote[], index: NotesIndex): Map { + const live = new Map(); + const later: LiveNote[] = []; + for (const file of files) { + const id = file.parsed.id; + if (!id || !ID.test(id)) { later.push(file); continue; } + const prior = live.get(id); + if (!prior) live.set(id, file); + else if (index.notes[id]?.rel === file.rel) { later.push(prior); live.set(id, file); } + else later.push(file); + } + const rels = new Set(files.map(file => file.rel)); + for (const file of later) { + const entries = Object.entries(index.notes).filter(([id]) => !live.has(id)); + const id = entries.find(([, e]) => e.rel === file.rel)?.[0] + ?? entries.find(([, e]) => e.ino === file.ino && e.rel !== null && !rels.has(e.rel))?.[0] + ?? randomUUID(); + live.set(id, file); + } + return live; + } + + // ── Opening, layout and migration ──────────────────────────────────────────────────────── + + private open(): void { + if (this.opened) return; + let stat: fs.Stats | null = null; + try { stat = fs.lstatSync(this.root); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw preserved(error); } + if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) throw preserved(new Error("The notes folder must be a real folder, not a link or a file.")); + const receipt = stat ? this.readReceipt() : null; + if (!receipt) this.migrate(stat !== null); + this.opened = true; + if (receipt) this.importChangesSince(receipt); + } + + private readReceipt(): MigrationReceipt | null { + try { return JSON.parse(fs.readFileSync(path.join(this.meta, "migration.json"), "utf8")) as MigrationReceipt; } catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; + throw preserved(error); + } + } + + /** + * Sets up the folder, with this home's `space.json` pages in Personal › Notes. A new folder is built + * beside the root and published with one rename, so a crash leaves either nothing or all of it. + * `space.json` is never written; a copy is kept beside it. + */ + private migrate(rootExists: boolean): void { + const legacy = this.options.legacySpaceFile; + let doc: SpaceDocument = { version: 2, pages: [], history: [] }; + let digest: string | null = null; + if (legacy && fs.existsSync(legacy)) { + doc = readSpaceDocument(legacy); + const bytes = fs.readFileSync(legacy); + digest = sha256(bytes); + try { fs.copyFileSync(legacy, `${legacy}.pre-notes-${digest.slice(0, 8)}.bak`, fs.constants.COPYFILE_EXCL); } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; + } + } + const parent = path.dirname(this.root); + for (const name of fs.existsSync(parent) ? fs.readdirSync(parent) : []) { + if (name.startsWith(`${path.basename(this.root)}.migrating-`)) fs.rmSync(path.join(parent, name), { recursive: true, force: true }); + } + if (!rootExists) { + const staging = `${this.root}.migrating-${randomUUID()}`; + this.build(staging, doc, digest, () => []); + fs.renameSync(staging, this.root); + fsyncDir(parent); + return; + } + // A folder that exists without a receipt (made by hand, or by a crashed setup): add the pages next to what is there. + const existing = new Set(this.scan().map(file => file.parsed.id).filter((id): id is string => Boolean(id))); + this.build(this.root, { ...doc, pages: doc.pages.filter(page => !existing.has(page.id)) }, digest, dir => this.names(dir)); + } + + private build(target: string, doc: SpaceDocument, digest: string | null, taken: (dirRel: string) => string[]): void { + const at = (rel: string) => path.join(target, ...rel.split("/")); + const meta = path.join(target, ".modex"); + for (const dir of ["history", "comments", "trash"]) fs.mkdirSync(path.join(meta, dir), { recursive: true, mode: 0o700 }); + const projectRel = `${DEFAULT_WORKSPACE}/${DEFAULT_PROJECT}`; + fs.mkdirSync(at(projectRel), { recursive: true }); + const workspaceMarker = at(`${DEFAULT_WORKSPACE}/.modex-workspace.json`); + if (!fs.existsSync(workspaceMarker)) writeFileDurably(workspaceMarker, JSON.stringify({ version: 1, id: randomUUID(), title: DEFAULT_WORKSPACE, order: 0, default: true })); + const projectMarker = at(`${projectRel}/.modex-project.json`); + if (!fs.existsSync(projectMarker)) writeFileDurably(projectMarker, JSON.stringify({ version: 1, id: randomUUID(), title: DEFAULT_PROJECT, order: 0, modexProjectId: null, default: true })); + const plan = planMigration(doc.pages, projectRel, taken); + const pages = new Map(doc.pages.map(page => [page.id, page])); + let index: NotesIndex = { version: 1, defaultProject: projectRel, notes: {} }; + try { index = { ...index, ...JSON.parse(fs.readFileSync(path.join(meta, "index.json"), "utf8")) as NotesIndex }; } catch { /* A new folder starts empty. */ } + const trashed = plan.notes.filter(note => note.trashed); + const batch = "migrated"; + for (const note of plan.notes) { + const page = pages.get(note.id)!; + writeFileDurably(path.join(meta, "history", `${note.id}.json`), JSON.stringify({ version: 1, versions: doc.history.filter(v => v.page.id === note.id) } satisfies HistoryFile)); + const comments = (doc.comments ?? []).filter(c => c.pageId === note.id); + if (comments.length) writeFileDurably(path.join(meta, "comments", `${note.id}.json`), JSON.stringify(comments)); + const file = note.trashed ? path.join(meta, "trash", batch, ...note.rel.split("/")) : at(note.rel); + fs.mkdirSync(path.dirname(file), { recursive: true }); + const text = formatNote({ id: note.id, title: page.title, stem: stemOf(note.rel), body: page.markdown }); + writeFileDurably(file, text); + const updated = new Date(page.updatedAt); + if (Number.isFinite(updated.getTime())) fs.utimesSync(file, updated, updated); + index.notes[note.id] = note.trashed + ? { rel: null, hash: sha256(text), trash: { batch, rel: note.rel, original: note.rel } } + : { rel: note.rel, hash: sha256(text), ino: fs.statSync(file).ino }; + } + if (trashed.length) { + writeFileDurably(path.join(meta, "trash", `${batch}.json`), JSON.stringify({ version: 1, id: batch, trashedAt: new Date(this.now()).toISOString(), items: trashed.map(note => ({ id: note.id, original: note.rel, rel: note.rel })) } satisfies TrashManifest)); + } + writeFileDurably(path.join(meta, "index.json"), JSON.stringify(index)); + const receipt: MigrationReceipt = { + version: 1, source: digest ? "app/space.json" : null, sha256: digest, migratedAt: new Date(this.now()).toISOString(), + revisions: Object.fromEntries(doc.pages.map(page => [page.id, page.revision])), mapping: Object.fromEntries(plan.notes.map(note => [note.id, note.rel])), warnings: plan.warnings, + }; + writeFileDurably(path.join(meta, "migration.json"), JSON.stringify(receipt)); + } + + /** + * An older Modex reads and writes `space.json`, which migration left as it was. Pages it created or + * changed since are brought in as new notes under "Recovered from earlier Modex", never over newer ones. + */ + private importChangesSince(receipt: MigrationReceipt): void { + const legacy = this.options.legacySpaceFile; + if (!legacy || !receipt.sha256 || !fs.existsSync(legacy)) return; + const digest = sha256(fs.readFileSync(legacy)); + if (digest === receipt.sha256) return; + const doc = readSpaceDocument(legacy); + const changed = doc.pages.filter(page => page.trashedAt === null && (receipt.revisions[page.id] === undefined || page.revision > receipt.revisions[page.id]!)); + if (changed.length) { + const day = new Date(this.now()).toISOString().slice(0, 10); + const folder = this.create({ title: `Recovered from earlier Modex ${day}` }, { actor: "unknown", summary: "Recovered from an earlier Modex" }); + for (const page of changed) this.create({ title: page.title, markdown: page.markdown, parentId: folder.id }, { actor: "unknown", summary: "Recovered from an earlier Modex" }); + } + writeFileDurably(path.join(this.meta, "migration.json"), JSON.stringify({ ...receipt, sha256: digest, revisions: { ...receipt.revisions, ...Object.fromEntries(doc.pages.map(page => [page.id, page.revision])) } } satisfies MigrationReceipt)); + } + + // ── Placement ──────────────────────────────────────────────────────────────────────────── + + /** The folder a child of `parentId` lives in, turning a leaf parent into a folder note first. */ + private dirFor(state: State, parentId: string | null, project: string): string { + if (parentId === null) return project; + const parent = state.live.get(parentId); + if (!parent) throw new Error("Choose an existing page as the parent."); + if (this.isFolderNote(parent.rel)) return path.posix.dirname(parent.rel); + const dir = path.posix.dirname(parent.rel); + const name = uniqueName(stemOf(parent.rel), "", this.names(dir).filter(n => n !== path.posix.basename(parent.rel))); + fs.mkdirSync(this.abs(`${dir}/${name}`)); + this.renameNote(state, state.pages.get(parentId)!, parent.rel, `${dir}/${name}/${name}.md`); + return `${dir}/${name}`; + } + + /** Moves a page under `parentId` (its whole folder, for a folder note) and returns the note file's new path. */ + private move(state: State, id: string, parentId: string | null): string { + const live = state.live.get(id); + if (!live) throw new Error("This Space page no longer exists."); + const project = live.rel.split("/").slice(0, 2).join("/"); + const target = this.dirFor(state, parentId, depth(project) === 2 ? project : state.index.defaultProject); + const current = state.live.get(id)!; + if (this.isFolderNote(current.rel)) { + const dir = path.posix.dirname(current.rel); + const name = uniqueName(path.posix.basename(dir), "", this.names(target)); + const moved = `${target}/${name}`; + moveNoClobber(this.abs(dir), this.abs(moved)); + this.rebase(state, dir, moved); + const rel = `${moved}/${path.posix.basename(current.rel)}`; + if (name !== path.posix.basename(dir)) { this.renameNote(state, state.pages.get(id)!, rel, `${moved}/${name}.md`); return `${moved}/${name}.md`; } + return rel; + } + const rel = `${target}/${uniqueName(stemOf(current.rel), ".md", this.names(target))}`; + this.renameNote(state, state.pages.get(id)!, current.rel, rel); + return rel; + } + + /** Puts a restored page's file back where it was, or rewrites it from history if it is gone. */ + private restoreFile(state: State, page: SpacePage): void { + const entry = state.index.notes[page.id]; + const original = entry?.trash?.original || entry?.original || entry?.rel || `${state.index.defaultProject}/${noteStem(page.title)}.md`; + let dir = path.posix.dirname(original); + // The parent folder may have been restored under another name, or not at all. + if (page.parentId !== null) { + const parent = state.live.get(page.parentId); + if (parent) dir = this.isFolderNote(parent.rel) ? path.posix.dirname(parent.rel) : this.dirFor(state, page.parentId, state.index.defaultProject); + if (this.isFolderNote(original) && parent) dir = `${dir}/${path.posix.basename(path.posix.dirname(original))}`; + } + fs.mkdirSync(this.abs(dir), { recursive: true }); + const target = `${dir}/${uniqueName(stemOf(original), ".md", this.names(dir))}`; + const source = entry?.trash?.batch ? this.trashAbs(entry.trash.batch, entry.trash.rel) : null; + if (source && fs.existsSync(source)) { + moveNoClobber(source, this.abs(target)); + this.dropFromManifest(entry!.trash!.batch, page.id); + const text = this.readText(target); + state.live.set(page.id, { rel: target, ino: fs.statSync(this.abs(target)).ino, size: 0, mtimeMs: 0, hash: sha256(text), parsed: parseNote(text) }); + state.index.notes[page.id] = { rel: target, hash: sha256(text), ino: fs.statSync(this.abs(target)).ino }; + } else { + this.writeNoteAt(state, page, target); + } + } + + /** Rewrites a page's file at `to` (frontmatter title follows the new name) and removes `from`. */ + private renameNote(state: State, page: SpacePage, from: string, to: string): void { + const previous = this.readText(from); + const text = formatNote({ id: page.id, title: page.title, stem: stemOf(to), body: page.markdown }, previous); + if (nameKey(from) === nameKey(to)) { + // A case-only rename: rename first, so a case-sensitive file system cannot keep both. + if (from !== to) fs.renameSync(this.abs(from), this.abs(to)); + writeFileDurably(this.abs(to), text); + } else { + this.createNote(to, text); + fs.unlinkSync(this.abs(from)); + fsyncDir(path.dirname(this.abs(from))); + } + const ino = fs.statSync(this.abs(to)).ino; + state.live.set(page.id, { rel: to, ino, size: 0, mtimeMs: 0, hash: sha256(text), parsed: parseNote(text) }); + state.index.notes[page.id] = { rel: to, hash: sha256(text), ino }; + } + + /** After a folder moved from `from` to `to`, every note inside it is at a new path. */ + private rebase(state: State, from: string, to: string): void { + for (const [id, file] of state.live) { + if (!file.rel.startsWith(`${from}/`)) continue; + const rel = `${to}${file.rel.slice(from.length)}`; + state.live.set(id, { ...file, rel }); + const entry = state.index.notes[id]; + if (entry) state.index.notes[id] = { ...entry, rel }; + } + } + + private writeNoteAt(state: State, page: SpacePage, rel: string): void { + const exists = fs.existsSync(this.abs(rel)); + const text = formatNote({ id: page.id, title: page.title, stem: stemOf(rel), body: page.markdown }, exists ? this.readText(rel) : undefined); + if (exists) writeFileDurably(this.abs(rel), text); + else this.createNote(rel, text); + const ino = fs.statSync(this.abs(rel)).ino; + state.live.set(page.id, { rel, ino, size: 0, mtimeMs: 0, hash: sha256(text), parsed: parseNote(text) }); + state.index.notes[page.id] = { rel, hash: sha256(text), ino }; + } + + /** A new note file, never replacing one: written beside its target, then linked into place. */ + private createNote(rel: string, text: string): void { + const file = this.abs(rel); + fs.mkdirSync(path.dirname(file), { recursive: true }); + const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomUUID()}.tmp`); + writeFileDurably(temporary, text); + try { moveNoClobber(temporary, file); } finally { fs.rmSync(temporary, { force: true }); } + } + + private isFolderNote(rel: string): boolean { + const dir = path.posix.dirname(rel); + return depth(dir) >= 3 && nameKey(path.posix.basename(dir)) === nameKey(stemOf(rel)); + } + + /** Names in a folder, dot entries excluded; empty when it does not exist. */ + private names(dirRel: string): string[] { + try { return fs.readdirSync(this.abs(dirRel)).filter(name => !name.startsWith(".")); } catch { return []; } + } + + private removeEmptyDirs(dirRel: string): void { + // Never the workspace or the project itself. + while (depth(dirRel) >= 3) { + try { fs.rmdirSync(this.abs(dirRel)); } catch { return; } + dirRel = path.posix.dirname(dirRel); + } + } + + // ── Metadata files ─────────────────────────────────────────────────────────────────────── + + private abs(rel: string): string { return path.join(this.root, ...rel.split("/")); } + private historyFile(id: string): string { return path.join(this.meta, "history", `${id}.json`); } + private commentsFile(id: string): string { return path.join(this.meta, "comments", `${id}.json`); } + private manifestFile(batch: string): string { return path.join(this.meta, "trash", `${batch}.json`); } + private trashAbs(batch: string, rel: string): string { return path.join(this.meta, "trash", batch, ...rel.split("/")); } + private readText(rel: string): string { return fs.readFileSync(this.abs(rel), "utf8"); } + + private readIndex(): NotesIndex { + try { + const data = JSON.parse(fs.readFileSync(path.join(this.meta, "index.json"), "utf8")) as NotesIndex; + if (data?.version !== 1 || typeof data.defaultProject !== "string" || !data.notes || typeof data.notes !== "object") throw new Error("Invalid notes index."); + for (const [id, entry] of Object.entries(data.notes)) { + if (!ID.test(id) || !entry || (entry.rel !== null && typeof entry.rel !== "string") || (entry.hash !== null && typeof entry.hash !== "string")) throw new Error("Invalid notes index entry."); + } + return data; + } catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1, defaultProject: `${DEFAULT_WORKSPACE}/${DEFAULT_PROJECT}`, notes: {} }; + throw preserved(error); + } + } + + private writeIndex(index: NotesIndex): void { this.writeJson(path.join(this.meta, "index.json"), index); } + + private readManifests(): TrashManifest[] { + const dir = path.join(this.meta, "trash"); + let names: string[]; + try { names = fs.readdirSync(dir).filter(name => name.endsWith(".json")); } catch { return []; } + return names.map(name => { + try { return JSON.parse(fs.readFileSync(path.join(dir, name), "utf8")) as TrashManifest; } catch (error) { throw preserved(error); } + }); + } + + private dropFromManifest(batch: string, id: string): void { + if (!batch) return; + const file = this.manifestFile(batch); + let manifest: TrashManifest; + try { manifest = JSON.parse(fs.readFileSync(file, "utf8")) as TrashManifest; } catch { return; } + const items = manifest.items.filter(item => item.id !== id); + if (items.length) { this.writeJson(file, { ...manifest, items }); return; } + fs.rmSync(file, { force: true }); + fs.rmSync(path.join(this.meta, "trash", batch), { recursive: true, force: true }); + } + + private readHistory(id: string): SpacePageVersion[] | null { + const file = this.historyFile(id); + let stat: fs.Stats; + try { stat = fs.statSync(file); } catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; + throw preserved(error); + } + const key = `${stat.ino}:${stat.size}:${stat.mtimeMs}`; + const cached = this.historyCache.get(id); + if (cached?.key === key) return cached.versions; + let data: HistoryFile; + try { data = JSON.parse(fs.readFileSync(file, "utf8")) as HistoryFile; validateHistory(id, data); } catch (error) { throw preserved(error); } + this.historyCache.set(id, { key, versions: data.versions }); + return data.versions; + } + + private writeHistory(id: string, versions: SpacePageVersion[]): void { + const data: HistoryFile = { version: 1, versions }; + validateHistory(id, data); + this.writeJson(this.historyFile(id), data); + this.historyCache.delete(id); + } + + private readComments(pageId: string): SpaceComment[] { + let data: unknown; + try { data = JSON.parse(fs.readFileSync(this.commentsFile(pageId), "utf8")); } catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; + throw preserved(error); + } + if (!Array.isArray(data)) throw preserved(new Error("Invalid saved comments.")); + for (const comment of data as SpaceComment[]) { + try { validateComment(comment); } catch (error) { throw preserved(error); } + if (comment.pageId !== pageId) throw preserved(new Error("Invalid saved comment reference.")); + } + return data as SpaceComment[]; + } + + private writeJson(file: string, value: unknown): void { + fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 }); + writeFileDurably(file, JSON.stringify(value)); + } + + // ── Rules shared with SpaceStore ───────────────────────────────────────────────────────── + + private iso(): string { return new Date(this.now()).toISOString(); } + + private liveRel(state: State, id: string): string { + const live = state.live.get(id); + if (live) return live.rel; + // Deleted outside Modex while open in Space: saving writes it back where it was. + const entry = state.index.notes[id]; + return entry?.trash?.original || entry?.original || `${state.index.defaultProject}/${noteStem(state.pages.get(id)?.title ?? "")}.md`; + } + + private find(state: State, id: string): SpacePage { + const page = state.pages.get(id); + if (!page) throw new Error("This Space page no longer exists."); + return page; + } + + private checkRevision(page: SpacePage, revision: number): void { + if (page.revision !== revision) throw new Error("This page changed in another window. Copy your edits, then reopen Space to load the saved version."); + } + + private attribution(change: SpaceChangeContext | undefined, summary: string): SpaceChangeContext { + const attribution = change ?? { actor: "human", summary }; + validateChange(attribution); + return { actor: attribution.actor, summary: attribution.summary }; + } + + private version(page: SpacePage, change: SpaceChangeContext | undefined, summary: string): SpacePageVersion { + return { page, ...this.attribution(change, summary) }; + } + + /** + * Adds `version`. Autosave runs on every keystroke, and Open Knowledge autosaves as it types: for + * those (`coalesce`), a version within 30 s of the same kind replaces the last instead of piling up, + * keeping the start of the burst. Explicit changes always stay. + */ + private appendVersion(versions: SpacePageVersion[], version: SpacePageVersion, coalesce: "human" | "external" | null): SpacePageVersion[] { + if (!coalesce) return [...versions, version]; + version.checkpointAt = version.page.updatedAt; + const latest = versions.at(-1); + const elapsed = Date.parse(version.page.updatedAt) - Date.parse(latest?.checkpointAt ?? ""); + if (latest?.actor === coalesce && latest.checkpointAt && elapsed >= 0 && elapsed < CHECKPOINT_MS && versions.length > 1) { + version.checkpointAt = latest.checkpointAt; + return [...versions.slice(0, -1), version]; + } + return [...versions, version]; + } + + private validateParent(page: SpacePage, pages: Map): void { + let id = page.parentId; + const visited = new Set([page.id]); + while (id) { + if (visited.has(id)) throw new Error("A page cannot be placed inside itself."); + visited.add(id); + const parent = pages.get(id); + if (!parent || parent.trashedAt) throw new Error("Choose an existing page as the parent."); + id = parent.parentId; + } + } +} + +function validateHistory(id: string, data: HistoryFile): void { + if (!data || data.version !== 1 || !Array.isArray(data.versions) || data.versions.length === 0) throw new Error("Invalid Space version history."); + let previous: SpacePage | undefined; + for (const version of data.versions) { + validateChange(version); + validate(version.page); + if (version.page.id !== id) throw new Error("Invalid Space version sequence."); + if (version.checkpointAt !== undefined && ((version.actor !== "human" && version.actor !== "external") || typeof version.checkpointAt !== "string" || !Number.isFinite(Date.parse(version.checkpointAt)))) throw new Error("Invalid Space typing checkpoint."); + if (previous && (version.page.revision <= previous.revision || version.page.createdAt !== previous.createdAt)) throw new Error("Invalid Space version sequence."); + previous = version.page; + } +} diff --git a/apps/desktop/src/main/engine/space-store.ts b/apps/desktop/src/main/engine/space-store.ts index 37658677..27e5fefe 100644 --- a/apps/desktop/src/main/engine/space-store.ts +++ b/apps/desktop/src/main/engine/space-store.ts @@ -4,10 +4,46 @@ import { randomUUID } from "node:crypto"; import { isDeepStrictEqual } from "node:util"; import type { CreateSpacePage, SpacePage, SpaceChangeContext, SpacePageVersion, SpaceComment } from "../../shared/space.js"; -interface SpaceDocument { version: 2; pages: SpacePage[]; history: SpacePageVersion[]; comments?: SpaceComment[]; } +export interface SpaceDocument { version: 2; pages: SpacePage[]; history: SpacePageVersion[]; comments?: SpaceComment[]; } + +/** What every Space store offers the `space:*` commands and the Pages tools; ids and revisions, never paths. */ +export interface SpacePagesStore { + list(): SpacePage[]; + comments(pageId: string): SpaceComment[]; + addComment(pageId: string, text: string, quote: string): SpaceComment; + deleteComment(pageId: string, id: string): void; + history(id: string): SpacePageVersion[]; + create(input: CreateSpacePage, change?: SpaceChangeContext): SpacePage; + save(input: SpacePage, change?: SpaceChangeContext): SpacePage; + trash(id: string, trash: boolean, revision?: number, change?: SpaceChangeContext): SpacePage[]; + revert(id: string, expectedRevision: number, versionRevision: number, change?: SpaceChangeContext): SpacePage; +} + +/** + * Reads and validates a `space.json` document; version 1 files gain a baseline version per page. + * Absent means empty. Anything unreadable throws, and the file is left as it is. + */ +export function readSpaceDocument(file: string): SpaceDocument { + try { + const data = JSON.parse(fs.readFileSync(file, "utf8")); + if (!data || (data.version !== 1 && data.version !== 2) || !Array.isArray(data.pages)) throw new Error("Unsupported document format"); + for (const page of data.pages) validate(page); + if (new Set(data.pages.map((page: SpacePage) => page.id)).size !== data.pages.length) throw new Error("Duplicate Space page id."); + if (data.version === 1) { + if ("history" in data) throw new Error("Unexpected version history in legacy document."); + return { version: 2, pages: data.pages, history: data.pages.map((page: SpacePage) => ({ page, actor: "unknown", summary: "Existing page before version history" })) }; + } + validateHistory(data); + validateComments(data); + return data; + } catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 2, pages: [], history: [] }; + throw new Error(`Space could not read saved pages. Your file has been preserved. ${(error as Error).message}`); + } +} /** Read before every mutation, validate before writing, and atomically replace the local document file. */ -export class SpaceStore { +export class SpaceStore implements SpacePagesStore { private readonly file: string; constructor(private readonly dir: string) { this.file = path.join(dir, "space.json"); } @@ -41,24 +77,7 @@ export class SpaceStore { return data.history.filter(version => version.page.id === id); } - private read(): SpaceDocument { - try { - const data = JSON.parse(fs.readFileSync(this.file, "utf8")); - if (!data || (data.version !== 1 && data.version !== 2) || !Array.isArray(data.pages)) throw new Error("Unsupported document format"); - for (const page of data.pages) validate(page); - if (new Set(data.pages.map((page: SpacePage) => page.id)).size !== data.pages.length) throw new Error("Duplicate Space page id."); - if (data.version === 1) { - if ("history" in data) throw new Error("Unexpected version history in legacy document."); - return { version: 2, pages: data.pages, history: data.pages.map((page: SpacePage) => ({ page, actor: "unknown", summary: "Existing page before version history" })) }; - } - validateHistory(data); - validateComments(data); - return data; - } catch (error) { - if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 2, pages: [], history: [] }; - throw new Error(`Space could not read saved pages. Your file has been preserved. ${(error as Error).message}`); - } - } + private read(): SpaceDocument { return readSpaceDocument(this.file); } create(input: CreateSpacePage, change?: SpaceChangeContext): SpacePage { const data = this.read(); @@ -175,7 +194,7 @@ export class SpaceStore { } } -function validateComment(comment: SpaceComment): void { +export function validateComment(comment: SpaceComment): void { if (!comment || typeof comment.id !== "string" || !/^[a-z0-9-]{1,64}$/i.test(comment.id) || typeof comment.pageId !== "string" || typeof comment.text !== "string" || !comment.text.trim() || comment.text.length > 10_000 || typeof comment.quote !== "string" || comment.quote.length > 2_000 || typeof comment.createdAt !== "string" || !Number.isFinite(Date.parse(comment.createdAt))) { @@ -194,7 +213,7 @@ function validateComments(data: SpaceDocument): void { } } -function validate(page: SpacePage): void { +export function validate(page: SpacePage): void { if (!page || typeof page !== "object" || typeof page.id !== "string" || !/^[a-z0-9-]{1,64}$/i.test(page.id)) throw new Error("Invalid Space page id."); if (typeof page.title !== "string" || page.title.length > 200) throw new Error("Page title must be at most 200 characters."); if (typeof page.markdown !== "string" || page.markdown.length > 1_000_000) throw new Error("A Space page can contain up to 1 MB of text."); @@ -203,7 +222,7 @@ function validate(page: SpacePage): void { typeof page.createdAt !== "string" || typeof page.updatedAt !== "string" || (page.trashedAt !== null && typeof page.trashedAt !== "string")) throw new Error("Invalid Space page metadata."); } -function validateChange(change: SpaceChangeContext): void { +export function validateChange(change: SpaceChangeContext): void { if (!change || typeof change.actor !== "string" || !change.actor.trim() || change.actor.length > 200) throw new Error("Invalid Space change actor."); if (typeof change.summary !== "string" || !change.summary.trim() || change.summary.length > 2_000) throw new Error("Invalid Space change summary."); } diff --git a/apps/desktop/src/shared/notes-names.ts b/apps/desktop/src/shared/notes-names.ts new file mode 100644 index 00000000..7da1c9a3 --- /dev/null +++ b/apps/desktop/src/shared/notes-names.ts @@ -0,0 +1,57 @@ +/** + * File and folder names for notes. A name is derived from a title once; the title itself lives in + * the note's frontmatter whenever the name cannot carry it exactly (sanitized, suffixed, or empty). + */ + +/** The longest stem in UTF-8 bytes, leaving room for " 999.md" under the common 255-byte limit. */ +export const MAX_STEM_BYTES = 200; +const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/i; +const encoder = new TextEncoder(); +const bytes = (text: string) => encoder.encode(text).length; + +/** A safe file stem for `title`: NFC, no separators or control characters, no leading dot, never empty. */ +export function noteStem(title: string): string { + let stem = title.normalize("NFC") + // Whitespace of any kind (tabs, line breaks) reads as one space. + .replace(/\s+/g, " ") + // Separators, characters Windows and Finder refuse, and the remaining control characters. + .replace(/[/\\:*?"<>|\u0000-\u001f\u007f]/g, "-") + .trim() + // No hidden files, and no trailing dots or spaces (Windows strips them). + .replace(/^[.\s]+/, "") + .replace(/[.\s]+$/, ""); + if (!stem) stem = "Untitled"; + // Open Knowledge reserves index.md at every level and serves `__x__` routes. + if (WINDOWS_RESERVED.test(stem) || /^index$/i.test(stem) || /^__.*__$/.test(stem)) stem = `${stem} note`; + return truncateBytes(stem, MAX_STEM_BYTES); +} + +/** Cuts `text` to at most `max` UTF-8 bytes without splitting a character. */ +export function truncateBytes(text: string, max: number): string { + if (bytes(text) <= max) return text; + let out = ""; + for (const ch of text) { + if (bytes(out + ch) > max) break; + out += ch; + } + return out.replace(/[.\s]+$/, "") || "Untitled"; +} + +/** Names compare the way APFS and NTFS do by default: Unicode-normalized and without case. */ +export function nameKey(name: string): string { + return name.normalize("NFC").toLowerCase(); +} + +/** A name without its `.md`: a note `Plan.md` and a folder `Plan` would be the same entry to a reader. */ +const stemKey = (name: string) => nameKey(name.replace(/\.md$/i, "")); + +/** + * `stem + ext`, or "stem 2.ext", "stem 3.ext"…, whichever is not taken. `taken` holds the names + * already in the folder; a note and a folder of the same name count as taken by each other. + */ +export function uniqueName(stem: string, ext: string, taken: Iterable): string { + const used = new Set([...taken].map(stemKey)); + const candidate = (n: number) => n === 1 ? stem : `${truncateBytes(stem, MAX_STEM_BYTES - 4)} ${n}`; + for (let n = 1; n < 10_000; n++) if (!used.has(stemKey(candidate(n)))) return `${candidate(n)}${ext}`; + throw new Error("This folder has too many notes with that name."); +} diff --git a/apps/desktop/test/notes-files.test.ts b/apps/desktop/test/notes-files.test.ts new file mode 100644 index 00000000..f876f162 --- /dev/null +++ b/apps/desktop/test/notes-files.test.ts @@ -0,0 +1,68 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import fs from "node:fs"; +import path from "node:path"; +import { MAX_STEM_BYTES, nameKey, noteStem, uniqueName } from "../src/shared/notes-names.js"; +import { formatNote, parseNote, splitFrontmatter } from "../src/main/engine/notes-frontmatter.js"; +import { moveNoClobber, writeFileDurably } from "../src/main/engine/durable-file.js"; +import { tmpdir } from "./helpers.js"; + +test("note names are safe on every platform and never hidden, reserved or empty", () => { + assert.equal(noteStem("A/B: plan?"), "A-B- plan-"); + assert.equal(noteStem(" .hidden "), "hidden"); + assert.equal(noteStem("trailing dots..."), "trailing dots"); + assert.equal(noteStem(""), "Untitled"); + assert.equal(noteStem("..."), "Untitled"); + assert.equal(noteStem("CON"), "CON note"); + assert.equal(noteStem("index"), "index note", "Open Knowledge reserves index.md"); + assert.equal(noteStem("__x__"), "__x__ note"); + assert.equal(noteStem("tab\there\nnew"), "tab here new"); + assert.equal(noteStem("été"), "été", "titles are NFC"); + const long = noteStem("é".repeat(300)); + assert.ok(new TextEncoder().encode(long).length <= MAX_STEM_BYTES); + assert.ok(!long.includes("�"), "a cut never splits a character"); +}); + +test("unique names compare without case and treat a note and a folder of one name as taken", () => { + assert.equal(uniqueName("Plan", ".md", []), "Plan.md"); + assert.equal(uniqueName("Plan", ".md", ["plan.MD"]), "Plan 2.md"); + assert.equal(uniqueName("Plan", ".md", ["Plan"]), "Plan 2.md", "a folder named Plan takes the note name"); + assert.equal(uniqueName("Plan", "", ["Plan.md", "Plan 2"]), "Plan 3"); + assert.equal(nameKey("É"), nameKey("É")); +}); + +test("frontmatter round-trips the body exactly and keeps other tools' keys", () => { + const body = "line one\r\n\r\n---\r\nnot frontmatter\n"; + const text = formatNote({ id: "abc", title: "Plan", stem: "Plan", body }); + assert.equal(text, `---\nmodex_id: abc\n---\n${body}`); + assert.deepEqual(parseNote(text), { id: "abc", body, frontmatter: true }); + const other = "---\n# a comment\ntags:\n - x\nmodex_id: old\n---\nbody"; + const rewritten = formatNote({ id: "new", title: "A: B", stem: "A- B", body: "body" }, other); + assert.match(rewritten, /# a comment/); + assert.match(rewritten, /tags:/); + assert.deepEqual(parseNote(rewritten), { id: "new", title: "A: B", body: "body", frontmatter: true }); + assert.doesNotMatch(formatNote({ id: "new", title: "Same", stem: "Same", body: "" }, rewritten), /title:/); + assert.deepEqual(parseNote("---\n- a list\n---\nbody"), { body: "---\n- a list\n---\nbody", frontmatter: false }, "a non-mapping header is body"); + assert.deepEqual(parseNote("no header"), { body: "no header", frontmatter: false }); + assert.equal(splitFrontmatter("---\nunclosed"), null); + assert.deepEqual(parseNote("---\n---\nempty header"), { body: "empty header", frontmatter: true }); +}); + +test("durable writes replace atomically, and moves never overwrite", () => { + const dir = tmpdir("modex-durable-"); + const file = path.join(dir, "note.md"); + writeFileDurably(file, "one"); + writeFileDurably(file, "two"); + assert.equal(fs.readFileSync(file, "utf8"), "two"); + assert.equal(fs.statSync(file).mode & 0o777, 0o600); + assert.deepEqual(fs.readdirSync(dir), ["note.md"], "no temporary file is left behind"); + fs.writeFileSync(path.join(dir, "taken.md"), "keep"); + assert.throws(() => moveNoClobber(file, path.join(dir, "taken.md")), { code: "EEXIST" }); + assert.equal(fs.readFileSync(path.join(dir, "taken.md"), "utf8"), "keep"); + fs.mkdirSync(path.join(dir, "folder")); + fs.mkdirSync(path.join(dir, "busy")); + assert.throws(() => moveNoClobber(path.join(dir, "folder"), path.join(dir, "busy")), { code: "EEXIST" }); + moveNoClobber(file, path.join(dir, "sub", "moved.md")); + assert.equal(fs.readFileSync(path.join(dir, "sub", "moved.md"), "utf8"), "two"); + assert.ok(!fs.existsSync(file)); +}); diff --git a/apps/desktop/test/notes-migration.test.ts b/apps/desktop/test/notes-migration.test.ts new file mode 100644 index 00000000..7cb657d7 --- /dev/null +++ b/apps/desktop/test/notes-migration.test.ts @@ -0,0 +1,154 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import fs from "node:fs"; +import path from "node:path"; +import { SpaceStore } from "../src/main/engine/space-store.js"; +import { NotesStore } from "../src/main/engine/notes-store.js"; +import { planMigration } from "../src/main/engine/notes-migration.js"; +import type { SpacePage } from "../src/shared/space.js"; +import { tmpdir } from "./helpers.js"; + +/** A home whose `app/space.json` was written by today's SpaceStore. */ +function legacyHome(seed: (space: SpaceStore) => void): { home: string; app: string; legacy: string; root: string } { + const home = tmpdir("modex-notes-migration-"); + const app = path.join(home, "app"); + fs.mkdirSync(app); + seed(new SpaceStore(app)); + return { home, app, legacy: path.join(app, "space.json"), root: path.join(home, "notes") }; +} +const open = (h: { legacy: string; root: string }) => new NotesStore(h.root, { legacySpaceFile: h.legacy }); +const project = (root: string) => path.join(root, "Personal", "Notes"); + +test("migration keeps every page's id, revision, history and comments, and lays nesting out as folders", () => { + let ids: Record = {}; + let comment = ""; + const h = legacyHome(space => { + const plan = space.create({ title: "Plan", markdown: "# Plan" }); + const child = space.create({ title: "Child", parentId: plan.id }); + const leaf = space.create({ title: "Leaf", parentId: child.id, markdown: "deep" }); + const odd = space.create({ title: "A/B: plan" }); + const twin = space.create({ title: "plan" }); + space.save({ ...plan, markdown: "# Plan v2", favorite: true }); + comment = space.addComment(child.id, "Check this", "Child").id; + ids = { plan: plan.id, child: child.id, leaf: leaf.id, odd: odd.id, twin: twin.id }; + }); + try { + const before = fs.readFileSync(h.legacy, "utf8"); + const legacyPages = new SpaceStore(h.app).list(); + const notes = open(h); + const pages = notes.list(); + assert.deepEqual(pages.map(p => p.id).sort(), legacyPages.map(p => p.id).sort()); + for (const legacy of legacyPages) { + assert.deepEqual(pages.find(p => p.id === legacy.id), legacy, "the page is exactly what it was"); + assert.deepEqual(notes.history(legacy.id), new SpaceStore(h.app).history(legacy.id), "and so is its history"); + } + assert.deepEqual(notes.comments(ids.child!).map(c => c.id), [comment]); + assert.ok(fs.existsSync(path.join(project(h.root), "Plan", "Plan.md"))); + assert.ok(fs.existsSync(path.join(project(h.root), "Plan", "Child", "Child.md"))); + assert.ok(fs.existsSync(path.join(project(h.root), "Plan", "Child", "Leaf.md"))); + assert.ok(fs.existsSync(path.join(project(h.root), "A-B- plan.md"))); + assert.ok(fs.existsSync(path.join(project(h.root), "plan 2.md")), "a title that differs only in case still gets its own file"); + assert.equal(fs.readFileSync(h.legacy, "utf8"), before, "space.json is never written"); + const backups = fs.readdirSync(h.app).filter(n => n.startsWith("space.json.pre-notes-")); + assert.equal(backups.length, 1); + assert.equal(fs.readFileSync(path.join(h.app, backups[0]!), "utf8"), before); + const receipt = JSON.parse(fs.readFileSync(path.join(h.root, ".modex", "migration.json"), "utf8")); + assert.equal(receipt.source, "app/space.json"); + assert.equal(receipt.revisions[ids.plan!], 2); + // A second launch neither migrates again nor duplicates anything. + assert.equal(open(h).list().length, legacyPages.length); + assert.equal(fs.readdirSync(path.dirname(h.root)).filter(n => n.startsWith("notes.migrating-")).length, 0); + } finally { fs.rmSync(h.home, { recursive: true, force: true }); } +}); + +test("migration keeps trashed pages in the trash, restorable to their place", () => { + let ids: Record = {}; + const h = legacyHome(space => { + const folder = space.create({ title: "Old" }); + const inside = space.create({ title: "Inside", parentId: folder.id }); + const kept = space.create({ title: "Kept" }); + space.trash(folder.id, true); + ids = { folder: folder.id, inside: inside.id, kept: kept.id }; + }); + try { + const notes = open(h); + assert.equal(notes.list().filter(p => p.trashedAt).length, 2); + assert.ok(!fs.existsSync(path.join(project(h.root), "Old")), "a trashed page is not in the folder"); + notes.trash(ids.inside!, false); + assert.ok(fs.existsSync(path.join(project(h.root), "Old", "Old.md")), "restoring a child restores its parent folder note"); + assert.ok(fs.existsSync(path.join(project(h.root), "Old", "Inside.md"))); + assert.equal(notes.list().find(p => p.id === ids.inside)?.parentId, ids.folder); + } finally { fs.rmSync(h.home, { recursive: true, force: true }); } +}); + +test("a version 1 space.json migrates with its baseline versions", () => { + const h = legacyHome(() => {}); + try { + const page: SpacePage = { id: "legacy-1", parentId: null, title: "Legacy", markdown: "never lose", favorite: false, createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z", trashedAt: null, revision: 7 }; + fs.writeFileSync(h.legacy, JSON.stringify({ version: 1, pages: [page] })); + const notes = open(h); + assert.deepEqual(notes.list(), [page]); + assert.deepEqual(notes.history(page.id).map(v => [v.page.revision, v.actor]), [[7, "unknown"]]); + const saved = notes.save({ ...page, markdown: "replacement" }); + assert.equal(saved.revision, 8); + } finally { fs.rmSync(h.home, { recursive: true, force: true }); } +}); + +test("an unreadable space.json stops the migration and is kept as it is", () => { + const h = legacyHome(space => { space.create({ title: "Keep" }); }); + try { + fs.writeFileSync(h.legacy, "broken data"); + assert.throws(() => open(h).list(), /preserved/); + assert.equal(fs.readFileSync(h.legacy, "utf8"), "broken data"); + assert.ok(!fs.existsSync(h.root), "nothing is published"); + } finally { fs.rmSync(h.home, { recursive: true, force: true }); } +}); + +test("a crashed migration's staging folder is discarded and the migration runs again", () => { + const h = legacyHome(space => { space.create({ title: "Once" }); }); + try { + const stale = `${h.root}.migrating-crashed`; + fs.mkdirSync(path.join(stale, "Personal"), { recursive: true }); + fs.writeFileSync(path.join(stale, "Personal", "half.md"), "half"); + const notes = open(h); + assert.deepEqual(notes.list().map(p => p.title), ["Once"]); + assert.ok(!fs.existsSync(stale)); + } finally { fs.rmSync(h.home, { recursive: true, force: true }); } +}); + +test("pages an older Modex changed in space.json come back under Recovered, never over newer notes", () => { + let id = ""; + const h = legacyHome(space => { id = space.create({ title: "Shared", markdown: "v1" }).id; }); + try { + const notes = open(h); + const current = notes.list()[0]!; + notes.save({ ...current, markdown: "newer in notes" }); + // Downgrade: the old build edits space.json, then the new build opens again. + const old = new SpaceStore(h.app); + old.save({ ...old.list()[0]!, markdown: "edited by an older build" }); + old.create({ title: "Made while downgraded" }); + const reopened = open(h); + const pages = reopened.list(); + assert.equal(pages.find(p => p.id === id)?.markdown, "newer in notes", "the newer note is untouched"); + const recovered = pages.find(p => p.title.startsWith("Recovered from earlier Modex"))!; + assert.deepEqual(pages.filter(p => p.parentId === recovered.id).map(p => p.markdown).sort(), ["", "edited by an older build"]); + assert.equal(open(h).list().length, pages.length, "the same changes are not recovered twice"); + } finally { fs.rmSync(h.home, { recursive: true, force: true }); } +}); + +test("a fresh home gets the default workspace and project, with no space.json", () => { + const home = tmpdir("modex-notes-fresh-"); + try { + const notes = new NotesStore(path.join(home, "notes"), { legacySpaceFile: path.join(home, "app", "space.json") }); + assert.deepEqual(notes.list(), []); + assert.ok(fs.existsSync(path.join(home, "notes", "Personal", "Notes", ".modex-project.json"))); + assert.equal(JSON.parse(fs.readFileSync(path.join(home, "notes", ".modex", "migration.json"), "utf8")).source, null); + } finally { fs.rmSync(home, { recursive: true, force: true }); } +}); + +test("the plan places a page whose parent is missing at the top level and warns", () => { + const page = (id: string, parentId: string | null, title: string): SpacePage => ({ id, parentId, title, markdown: "", favorite: false, createdAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-01-01T00:00:00.000Z", trashedAt: null, revision: 1 }); + const plan = planMigration([page("a", null, "Index"), page("b", "gone", "Orphan"), page("c", null, "")], "Personal/Notes", dir => dir === "Personal/Notes" ? ["Orphan.md"] : []); + assert.deepEqual(plan.notes.map(n => n.rel), ["Personal/Notes/Index note.md", "Personal/Notes/Orphan 2.md", "Personal/Notes/Untitled.md"]); + assert.equal(plan.warnings.length, 1); +}); diff --git a/apps/desktop/test/notes-store.test.ts b/apps/desktop/test/notes-store.test.ts new file mode 100644 index 00000000..403cb72f --- /dev/null +++ b/apps/desktop/test/notes-store.test.ts @@ -0,0 +1,265 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import fs from "node:fs"; +import path from "node:path"; +import { NotesStore } from "../src/main/engine/notes-store.js"; +import { tmpdir } from "./helpers.js"; + +/** A store over a fresh notes folder in a fresh home, with a clock the test can move. */ +function withStore(run: (store: NotesStore, root: string, clock: { now: number }) => void): void { + const home = tmpdir("modex-notes-"); + const clock = { now: Date.parse("2026-10-15T09:00:00.000Z") }; + const root = path.join(home, "notes"); + try { run(new NotesStore(root, { now: () => clock.now }), root, clock); } finally { fs.rmSync(home, { recursive: true, force: true }); } +} +const reopen = (root: string, clock?: { now: number }) => new NotesStore(root, clock ? { now: () => clock.now } : {}); +const project = (root: string) => path.join(root, "Personal", "Notes"); +/** Every file under the folder with its bytes, to prove an operation wrote nothing. */ +function snapshot(root: string): Record { + const out: Record = {}; + const walk = (dir: string) => { for (const e of fs.readdirSync(dir, { withFileTypes: true })) { const p = path.join(dir, e.name); if (e.isDirectory()) walk(p); else out[path.relative(root, p)] = fs.readFileSync(p, "utf8"); } }; + walk(root); + return out; +} + +// ── SpaceStore's contract, unchanged ────────────────────────────────────────────────────────── + +test("page comments persist independently of content revisions and reject invalid writes", () => withStore((store, root) => { + const page = store.create({ title: "Weekly update" }); + const added = store.addComment(page.id, "Confirm the dates", "Next week"); + store.save({ ...page, markdown: "Updated content" }); + assert.deepEqual(reopen(root).comments(page.id), [added]); + assert.equal(store.history(page.id).length, 2, "comments must not create or overwrite page revisions"); + assert.throws(() => store.addComment(page.id, " ", ""), /comment/i); + assert.throws(() => store.addComment(page.id, "x".repeat(10_001), ""), /comment/i); + assert.throws(() => store.addComment("missing", "Keep", ""), /page/i); + store.trash(page.id, true); + assert.throws(() => store.addComment(page.id, "Keep", ""), /Restore/); + store.trash(page.id, false); + store.deleteComment(page.id, added.id); + assert.deepEqual(store.comments(page.id), []); +})); + +test("notes persist edits, check revisions, and restore a trashed subtree", () => withStore((store, root) => { + const parent = store.create({ title: "Plan" }); + const child = store.create({ title: "Notes", parentId: parent.id }); + const saved = store.save({ ...store.list().find(p => p.id === parent.id)!, markdown: "# Idea\n\n- [x] Ship", favorite: true }); + assert.equal(reopen(root).list().find(p => p.id === parent.id)?.markdown, saved.markdown); + assert.throws(() => store.save({ ...parent, title: "Stale" }), /changed/); + assert.throws(() => store.save({ ...saved, parentId: child.id }), /inside itself/); + store.trash(parent.id, true); + assert.equal(store.list().filter(p => p.trashedAt).length, 2); + store.trash(child.id, false); + assert.equal(store.list().filter(p => p.trashedAt).length, 0); + assert.equal(store.list().find(p => p.id === child.id)?.parentId, parent.id); + const sibling = store.create({ title: "Unrelated", parentId: parent.id }); + store.trash(sibling.id, true); + store.trash(child.id, true); + store.trash(child.id, false); + assert.ok(store.list().find(p => p.id === sibling.id)?.trashedAt, "restoring a child must not restore its siblings"); +})); + +test("notes reject malformed writes and never overwrite unreadable data", () => withStore((store, root) => { + const page = store.create({ title: "Keep" }); + assert.throws(() => store.save({ ...page, title: 42 } as never), /title/); + assert.throws(() => store.create({ parentId: "missing" }), /parent/); + const history = path.join(root, ".modex", "history", `${page.id}.json`); + fs.writeFileSync(history, "broken data"); + const before = snapshot(root); + assert.throws(() => reopen(root).list(), /preserved/); + assert.throws(() => store.create({ title: "Must not replace" }), /preserved/); + assert.deepEqual(snapshot(root), before); +})); + +test("notes record attributed versions atomically and reload them", () => withStore((store, root) => { + const page = store.create({ title: "Draft", markdown: "original" }); + const saved = store.save({ ...page, markdown: "agent edit" }, { actor: "agent:thread-1", summary: "Added findings" }); + const history = reopen(root).history(page.id); + assert.deepEqual(history.map(v => [v.page.revision, v.page.markdown, v.actor]), [[1, "original", "human"], [2, "agent edit", "agent:thread-1"]]); + assert.equal(history[1]!.summary, "Added findings"); + assert.deepEqual(history[1]!.page, saved); + assert.throws(() => store.save({ ...page, markdown: "stale" }), /changed/); + assert.deepEqual(store.history(page.id), history); +})); + +test("notes reject stale trash and revert without changing saved data", () => withStore((store, root) => { + const page = store.create({ title: "Draft" }); + store.save({ ...page, markdown: "new" }); + const before = snapshot(root); + assert.throws(() => store.trash(page.id, true, page.revision), /changed/); + assert.throws(() => store.revert(page.id, page.revision, 1), /changed/); + assert.deepEqual(snapshot(root), before); +})); + +test("revert restores content and placement as a new version", () => withStore(store => { + const parent = store.create({ title: "Parent" }); + const page = store.create({ title: "Original", markdown: "original", parentId: parent.id }); + const saved = store.save({ ...page, title: "Changed", markdown: "changed", favorite: true, parentId: null }); + const reverted = store.revert(page.id, saved.revision, 1, { actor: "human", summary: "Undo agent edit" }); + assert.deepEqual({ ...reverted, revision: page.revision, updatedAt: page.updatedAt }, page); + assert.equal(reverted.revision, 3); + assert.equal(store.history(page.id).length, 3); + assert.equal(store.history(page.id)[2]!.summary, "Undo agent edit"); + store.trash(page.id, true, reverted.revision); + assert.throws(() => store.revert(page.id, 4, 1), /Restore/); + store.trash(page.id, false, 4); + assert.equal(store.revert(page.id, 5, 1).revision, 6); +})); + +test("invalid attribution and unsafe revert placement write nothing", () => withStore((store, root) => { + const parent = store.create({ title: "Parent" }); + const page = store.create({ title: "Child", parentId: parent.id }); + const moved = store.save({ ...page, parentId: null }); + store.trash(parent.id, true); + const before = snapshot(root); + assert.throws(() => store.revert(page.id, moved.revision, 1), /parent/); + assert.throws(() => store.revert(page.id, moved.revision, 99), /version/i); + assert.throws(() => store.save(moved, { actor: "", summary: "bad" }), /actor/i); + assert.deepEqual(snapshot(root), before); +})); + +test("human typing coalesces into checkpoints while explicit changes stay", () => withStore((store, root) => { + let page = store.create({ title: "Long note", markdown: "x".repeat(100_000) }); + for (let i = 0; i < 30; i++) page = store.save({ ...page, markdown: `${page.markdown}.` }); + assert.equal(store.history(page.id).length, 2, "a typing burst retains the original and latest checkpoint"); + assert.ok(fs.statSync(path.join(root, ".modex", "history", `${page.id}.json`)).size < 400_000); + const beforeAgent = page; + page = store.save({ ...page, markdown: "Agent change" }, { actor: "thread:agent", summary: "Agent edit" }); + page = store.save({ ...page, markdown: "Human after agent" }); + page = store.save({ ...page, markdown: "Human after agent, continued" }); + assert.deepEqual(store.history(page.id).map(v => v.page.revision), [1, 31, 32, 34]); + assert.equal(store.revert(page.id, page.revision, beforeAgent.revision).markdown, beforeAgent.markdown); + assert.equal(reopen(root).list()[0]?.revision, 35); +})); + +test("a typing interval starts a fresh checkpoint", () => withStore((store, _root, clock) => { + let page = store.create({ title: "Checkpoints", markdown: "Original" }); + page = store.save({ ...page, markdown: "First typing burst" }); + clock.now += 31_000; + page = store.save({ ...page, markdown: "Next typing burst" }); + assert.deepEqual(store.history(page.id).map(v => v.page.markdown), ["Original", "First typing burst", "Next typing burst"]); + page = store.save({ ...page, markdown: "Next typing burst continued" }); + assert.deepEqual(store.history(page.id).map(v => v.page.revision), [1, 2, 4]); +})); + +// ── The folder ──────────────────────────────────────────────────────────────────────────────── + +test("pages are Markdown files in Personal › Notes, and a page with children becomes a folder", () => withStore((store, root) => { + const plan = store.create({ title: "Plan", markdown: "# Plan\n" }); + assert.equal(fs.readFileSync(path.join(project(root), "Plan.md"), "utf8"), `---\nmodex_id: ${plan.id}\n---\n# Plan\n`); + const child = store.create({ title: "A/B: next?", parentId: plan.id, markdown: "child" }); + assert.ok(!fs.existsSync(path.join(project(root), "Plan.md")), "the parent moved into its own folder"); + assert.match(fs.readFileSync(path.join(project(root), "Plan", "Plan.md"), "utf8"), new RegExp(`modex_id: ${plan.id}`)); + const childFile = fs.readFileSync(path.join(project(root), "Plan", "A-B- next-.md"), "utf8"); + assert.match(childFile, /title: "A\/B: next\?"/, "a title the file name cannot carry is kept in frontmatter"); + assert.equal(store.list().find(p => p.id === child.id)?.title, "A/B: next?"); + for (const marker of ["Personal/.modex-workspace.json", "Personal/Notes/.modex-project.json"]) assert.ok(fs.existsSync(path.join(root, marker)), marker); + const second = store.create({ title: "Plan" }); + assert.ok(fs.existsSync(path.join(project(root), "Plan 2.md")), "a name a folder already uses gets a suffix: a note and a folder never share one"); + assert.equal(store.list().find(p => p.id === second.id)?.title, "Plan"); +})); + +test("moving a folder note moves its whole folder, and settle renames files to their titles", () => withStore((store, root) => { + const a = store.create({ title: "Area" }); + const b = store.create({ title: "Box", parentId: a.id }); + store.create({ title: "Inside", parentId: b.id }); + const target = store.create({ title: "Target" }); + const box = store.list().find(p => p.id === b.id)!; + store.save({ ...box, parentId: target.id }); + assert.ok(fs.existsSync(path.join(project(root), "Target", "Box", "Box.md"))); + assert.ok(fs.existsSync(path.join(project(root), "Target", "Box", "Inside.md"))); + assert.equal(reopen(root).list().find(p => p.title === "Inside")?.parentId, b.id); + const renamed = store.save({ ...store.list().find(p => p.id === b.id)!, title: "Crate" }); + assert.ok(fs.existsSync(path.join(project(root), "Target", "Box", "Box.md")), "typing a title never renames the file"); + store.settle(renamed.id); + assert.ok(fs.existsSync(path.join(project(root), "Target", "Crate", "Crate.md"))); + assert.ok(fs.existsSync(path.join(project(root), "Target", "Crate", "Inside.md"))); + assert.doesNotMatch(fs.readFileSync(path.join(project(root), "Target", "Crate", "Crate.md"), "utf8"), /title:/, "once the name carries the title, frontmatter drops it"); + const leaf = store.create({ title: "case" }); + store.settle(store.save({ ...leaf, title: "Case" }).id); + assert.deepEqual(fs.readdirSync(project(root)).filter(n => /^case\.md$/i.test(n)), ["Case.md"], "a case-only rename keeps one file"); +})); + +test("trash moves files out of the folder and restore puts them back", () => withStore((store, root) => { + const plan = store.create({ title: "Plan" }); + const kid = store.create({ title: "Kid", parentId: plan.id }); + fs.writeFileSync(path.join(project(root), "Plan", "sketch.png"), "png"); + store.trash(plan.id, true); + assert.ok(!fs.existsSync(path.join(project(root), "Plan", "Plan.md"))); + assert.ok(fs.existsSync(path.join(project(root), "Plan", "sketch.png")), "files that are not notes stay"); + assert.equal(reopen(root).list().filter(p => p.trashedAt).length, 2); + store.trash(kid.id, false); + assert.ok(fs.existsSync(path.join(project(root), "Plan", "Plan.md"))); + assert.ok(fs.existsSync(path.join(project(root), "Plan", "Kid.md"))); + assert.equal(fs.readdirSync(path.join(root, ".modex", "trash")).length, 0, "an emptied trash batch goes"); +})); + +test("edits outside Modex become versions, and frontmatter-only edits do not", () => withStore((store, root, clock) => { + const page = store.create({ title: "Outside", markdown: "one" }); + const file = path.join(project(root), "Outside.md"); + fs.writeFileSync(file, `---\nmodex_id: ${page.id}\ntags: [a]\n---\none`); + assert.equal(store.list()[0]!.revision, 1, "an unrelated frontmatter key is not a page change"); + fs.writeFileSync(file, `---\nmodex_id: ${page.id}\ntags: [a]\n---\ntwo`); + clock.now += 1_000; + const edited = store.list()[0]!; + assert.deepEqual([edited.markdown, edited.revision], ["two", 2]); + assert.deepEqual(store.history(page.id).map(v => [v.actor, v.summary]).at(-1), ["external", "Edited outside Modex"]); + assert.throws(() => store.save({ ...page, markdown: "stale" }), /changed/, "a stale window hits the conflict flow"); + const saved = store.save({ ...edited, markdown: "three" }); + assert.match(fs.readFileSync(file, "utf8"), /tags: \[ a \]|tags:\n - a|tags: \[a\]/, "Modex keeps other tools' keys"); + assert.equal(saved.revision, 3); +})); + +test("a file moved or renamed outside Modex keeps its page, and a new file becomes one", () => withStore((store, root) => { + const page = store.create({ title: "Mover" }); + fs.mkdirSync(path.join(project(root), "Shelf")); + fs.renameSync(path.join(project(root), "Mover.md"), path.join(project(root), "Shelf", "Renamed.md")); + const moved = store.list().find(p => p.id === page.id)!; + assert.equal(moved.title, "Renamed", "without a frontmatter title the file name is the title"); + assert.equal(moved.revision, 2); + fs.writeFileSync(path.join(project(root), "From Finder.md"), "dropped in"); + const found = store.list().find(p => p.title === "From Finder")!; + assert.equal(found.markdown, "dropped in"); + assert.equal(store.history(found.id)[0]!.summary, "Found in notes folder"); + assert.equal(fs.readFileSync(path.join(project(root), "From Finder.md"), "utf8"), "dropped in", "listing never writes into a file"); + assert.equal(reopen(root).list().find(p => p.title === "From Finder")?.id, found.id, "its id survives a restart"); +})); + +test("a file deleted outside Modex is trashed after a second look and can be restored", () => withStore((store, root, clock) => { + const page = store.create({ title: "Gone", markdown: "keep me" }); + fs.rmSync(path.join(project(root), "Gone.md")); + assert.equal(store.list()[0]!.trashedAt, null, "one missing look is not a deletion"); + clock.now += 1_500; + const gone = store.list()[0]!; + assert.ok(gone.trashedAt); + assert.equal(store.history(page.id).at(-1)!.summary, "Deleted outside Modex"); + store.trash(page.id, false); + assert.match(fs.readFileSync(path.join(project(root), "Gone.md"), "utf8"), /keep me$/); +})); + +test("the folder refuses a link and a copied id gets a new one", () => withStore((store, root) => { + const page = store.create({ title: "Original" }); + fs.copyFileSync(path.join(project(root), "Original.md"), path.join(project(root), "Copy.md")); + const pages = store.list(); + assert.equal(pages.length, 2); + assert.equal(pages.find(p => p.title === "Original")!.id, page.id, "the file at the indexed path keeps the id"); + assert.notEqual(pages.find(p => p.title === "Copy")!.id, page.id); + const home = path.dirname(root); + const real = path.join(home, "elsewhere"); + fs.mkdirSync(real); + const linked = path.join(home, "linked-notes"); + fs.symlinkSync(real, linked); + assert.throws(() => new NotesStore(linked).list(), /real folder/); +})); + +test("a crash between the history and the note write is finished on the next read", () => withStore((store, root) => { + const page = store.create({ title: "Crash", markdown: "before" }); + const history = path.join(root, ".modex", "history", `${page.id}.json`); + const data = JSON.parse(fs.readFileSync(history, "utf8")); + // The history already holds revision 2; the note file and the index still describe revision 1. + data.versions.push({ page: { ...page, markdown: "after", revision: 2, updatedAt: "2026-10-15T09:00:01.000Z" }, actor: "thread:x", summary: "Agent edit" }); + fs.writeFileSync(history, JSON.stringify(data)); + const fresh = reopen(root); + assert.deepEqual([fresh.list()[0]!.markdown, fresh.list()[0]!.revision], ["after", 2]); + assert.match(fs.readFileSync(path.join(project(root), "Crash.md"), "utf8"), /after$/, "the note file is rewritten to match"); +})); diff --git a/docs/notes.md b/docs/notes.md new file mode 100644 index 00000000..53f54eed --- /dev/null +++ b/docs/notes.md @@ -0,0 +1,86 @@ +# Notes folder + +Space notes are moving from one `MODEX_HOME/app/space.json` into a folder of Markdown files, +`MODEX_HOME/notes/`, laid out **Workspace › Project › Folder › notes and files**. This page +describes the format `NotesStore` (`apps/desktop/src/main/engine/notes-store.ts`) reads and +writes. Until Modex switches to it, Space still uses `space.json`. + +## Layout + +``` +notes/ + .modex/ Modex's own records (hidden from Finder's listing and Open Knowledge) + index.json where each note file was last seen, and its hash as Modex confirmed it + history/.json every version of one page, oldest first + comments/.json that page's comments + trash//… trashed note files, by original path; .json lists them + migration.json receipt: what was migrated from space.json, and when + Personal/ a workspace (.modex-workspace.json) + Notes/ a project (.modex-project.json) + Weekly update.md a note + Plan/ a folder: a page with child pages + Plan.md its folder note, named like the folder + Child.md +``` + +- **A depth sets the role.** Folders at the top are workspaces, inside them projects, and any + folder deeper is a folder of notes. Personal › Notes is the default workspace and project. +- **A page with children is a folder** that holds its own folder note. Adding a child to a plain + note turns it into one. A note and a folder never share a name in one place. +- **Every note Modex writes carries its id** in frontmatter, so a move, a rename or a crash never + loses which page a file is: + + ```markdown + --- + modex_id: 3f2c9a1e-… + title: "A/B plan" + --- + The page's Markdown, exactly as written. + ``` + + `title` appears only when the file name cannot carry the title (characters a file name + refuses, a suffix such as `Plan 2`, or an empty title). Other keys, from Open Knowledge or + anything else, are kept as they are. +- **Names** are Unicode-normalized, compared without case, never hidden (no leading dot), free of + path separators and characters Windows refuses, at most 200 bytes, and never `index` (Open + Knowledge reserves `index.md`). Typing a title does not rename the file; Space renames it when + the title loses focus. + +## History and revisions + +The newest version in a page's history file is the page: its revision, favorite, place and trash +state. Revision checks, the 30-second typing checkpoints, trash and restore, revert and comments +behave exactly as they did with `space.json`. + +Writes go history first, then the note file, then the index. Reading reconciles what a crash left +between them: a history that is ahead is written to the file, and a trash or restore that stopped +partway is finished. + +## Edits outside Modex + +The folder is yours: Finder, an editor or Open Knowledge can change it. + +- **An edit** to a note's title or text becomes a version by "Outside Modex". Edits within 30 + seconds share one version, as typing does. A Space window holding the old revision gets the + usual "changed in another window" conflict. +- **A move or rename** keeps the page; a page moved into another folder takes that folder's note + as its parent. +- **A new Markdown file** becomes a page ("Found in notes folder"). Modex never writes into a file + just because it listed it. +- **A deleted file** goes to Trash after two looks at least a second apart, so a save that renames + or a `git checkout` is not a deletion. Restoring it writes it back from its history. +- **A copy** made in Finder gets its own id the next time Modex saves it; the original keeps its. + +Notes larger than 2 MB, files that are not UTF-8, links, and anything inside a dot folder (`.git`, +`.ok`, `.modex`) are not pages. + +## Migration + +On first use, the pages of `app/space.json` move into Personal › Notes, with their ids, +revisions, histories and comments; trashed pages go to the trash. The folder is built beside +`notes/` and appears with one rename, so a crash leaves either nothing or everything. +`space.json` is never written again, and a copy is kept as `space.json.pre-notes-.bak`. + +An older Modex still reads `space.json`. If it changes pages there and the newer Modex opens +again, those pages come back as new notes under **Recovered from earlier Modex** rather than +over anything newer. diff --git a/docs/status.md b/docs/status.md index a0053a26..30e46d53 100644 --- a/docs/status.md +++ b/docs/status.md @@ -591,6 +591,12 @@ v0.0.11 artifacts, including the original CI failures and remaining acceptance l ## In flight +- **Notes in folders** (Workspace › Project › Folder). Space notes move from `app/space.json` to + Markdown files under `MODEX_HOME/notes/`, with each Modex project getting its own notes, a + workspace level grouping projects in the sidebar, folders and files, and Open Knowledge able to + open the same folder. First slice: `NotesStore`, which keeps Space's page contract (ids, + revisions, history, trash, comments) over the files, records edits made outside Modex, and + migrates `space.json` once without writing it. Modex does not use it yet. [Notes folder](notes.md). - **Thread/project deletion during active turns.** A dedicated runner admission hold lets deletion stop and drain its own turns while unrelated turns continue, without weakening restart checks or the native draft preparation/adoption transaction. From f95ae57e8c48a697fbf417aab6522a6031f9e830 Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Thu, 15 Oct 2026 03:00:46 -0500 Subject: [PATCH 2/8] Keep Space pages as Markdown files in the notes folder Store now holds a NotesStore over MODEX_HOME/notes instead of SpaceStore over app/space.json; the space:* commands and the Pages tools keep their contract. On first use, the pages of app/space.json move into Personal > Notes and that file is never written again. A page's file takes its title's name when the title loses focus or another page opens (notes:settle); typing never renames files. Version history labels edits made outside Modex "Outside Modex". The e2e specs that read space.json now read the note files, and the forced save failures refuse the history folder instead of replacing space.json with a directory. New notes.spec covers the migration and an edit made outside Modex. Coven-Harness: Claude Code / claude-opus-5-5 --- .../e2e/chats-spaces-reference.spec.ts | 3 +- apps/desktop/e2e/notes-support.ts | 44 +++++++++++++ apps/desktop/e2e/notes.spec.ts | 64 +++++++++++++++++++ apps/desktop/e2e/pages-agents.spec.ts | 8 +-- apps/desktop/e2e/space.spec.ts | 17 +++-- apps/desktop/e2e/update-main.spec.ts | 8 +-- apps/desktop/e2e/update-preflight.spec.ts | 14 ++-- apps/desktop/src/main/commands.ts | 1 + apps/desktop/src/main/engine/pages-agents.ts | 4 +- apps/desktop/src/main/engine/store.ts | 7 +- apps/desktop/src/main/index.ts | 1 + .../src/renderer/space/PageHistory.tsx | 2 +- apps/desktop/src/renderer/space/SpaceView.tsx | 4 +- apps/desktop/src/renderer/space/useSpace.ts | 8 ++- apps/desktop/src/shared/types.ts | 2 + apps/desktop/test/pages-agents.test.ts | 5 +- apps/store-desktop/src/main/demo.ts | 1 + docs/notes.md | 2 +- docs/pages-maintenance.md | 2 +- docs/status.md | 14 ++-- 20 files changed, 167 insertions(+), 44 deletions(-) create mode 100644 apps/desktop/e2e/notes-support.ts create mode 100644 apps/desktop/e2e/notes.spec.ts diff --git a/apps/desktop/e2e/chats-spaces-reference.spec.ts b/apps/desktop/e2e/chats-spaces-reference.spec.ts index 6675b4ac..cdd94b90 100644 --- a/apps/desktop/e2e/chats-spaces-reference.spec.ts +++ b/apps/desktop/e2e/chats-spaces-reference.spec.ts @@ -2,6 +2,7 @@ import { test, expect } from "@playwright/test"; import fs from "node:fs"; import path from "node:path"; import { appDir, seedHome, launch, tid, resizeWindow } from "./support.js"; +import { savedComments } from "./notes-support"; test("reference chat rows stay still while their details open", async () => { const { home, repo } = seedHome({ theme: "graphite" }); @@ -147,7 +148,7 @@ test("chat page links clear the previous selection without losing that page's co await page.getByRole("button", { name: "Add comment", exact: true }).click(); await page.getByRole("textbox", { name: "Comment", exact: true }).fill("Comment only on B"); await page.getByRole("button", { name: "Post comment", exact: true }).click(); - await expect.poll(() => JSON.parse(fs.readFileSync(path.join(home, "app/space.json"), "utf8")).comments?.find((comment: { pageId: string }) => comment.pageId === next.id)?.quote).toBe(""); + await expect.poll(() => savedComments(home, next.id)[0]?.quote).toBe(""); await page.getByRole("button", { name: "Open Page A", exact: true }).click(); await expect(page.getByRole("textbox", { name: "Comment", exact: true })).toHaveValue("Keep the draft for A"); await expect(page.getByRole("complementary", { name: "Comments" }).locator("blockquote")).toHaveText("Quote only from page A"); diff --git a/apps/desktop/e2e/notes-support.ts b/apps/desktop/e2e/notes-support.ts new file mode 100644 index 00000000..af4e8ff5 --- /dev/null +++ b/apps/desktop/e2e/notes-support.ts @@ -0,0 +1,44 @@ +import fs from "node:fs"; +import path from "node:path"; +import type { SpaceComment } from "../src/shared/space"; + +export interface SavedNote { rel: string; id?: string; title: string; markdown: string } + +/** + * The notes Space saved under `home/notes` (docs/notes.md), read from disk without the app: each + * Markdown file outside dot folders, with its frontmatter's `modex_id` and `title` and the body as + * written. A note without a `title` key is titled by its file name. + */ +export function savedNotes(home: string): SavedNote[] { + const root = path.join(home, "notes"); + const out: SavedNote[] = []; + const walk = (dir: string) => { + let entries: fs.Dirent[]; + try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; } + for (const entry of entries) { + if (entry.name.startsWith(".")) continue; + const file = path.join(dir, entry.name); + if (entry.isDirectory()) { walk(file); continue; } + if (!entry.name.endsWith(".md")) continue; + const text = fs.readFileSync(file, "utf8"); + const match = /^---\n([\s\S]*?)\n?---\n/.exec(text); + const header = match?.[1] ?? ""; + const id = /^modex_id: (.+)$/m.exec(header)?.[1]; + const quoted = /^title: (.+)$/m.exec(header)?.[1]; + const title = quoted === undefined ? entry.name.replace(/\.md$/, "") : quoted.startsWith('"') ? JSON.parse(quoted) as string : quoted; + out.push({ rel: path.relative(root, file).split(path.sep).join("/"), ...(id ? { id } : {}), title, markdown: match ? text.slice(match[0].length) : text }); + } + }; + walk(root); + return out.sort((a, b) => a.rel.localeCompare(b.rel)); +} + +/** A page's saved comments. */ +export function savedComments(home: string, pageId: string): SpaceComment[] { + try { return JSON.parse(fs.readFileSync(path.join(home, "notes", ".modex", "comments", `${pageId}.json`), "utf8")) as SpaceComment[]; } catch { return []; } +} + +const history = (home: string) => path.join(home, "notes", ".modex", "history"); +/** Makes the next save fail for real: its first step, writing the page's version history, is refused. Nothing changes on disk. */ +export function blockNoteWrites(home: string): void { fs.chmodSync(history(home), 0o500); } +export function unblockNoteWrites(home: string): void { fs.chmodSync(history(home), 0o700); } diff --git a/apps/desktop/e2e/notes.spec.ts b/apps/desktop/e2e/notes.spec.ts new file mode 100644 index 00000000..12704e7e --- /dev/null +++ b/apps/desktop/e2e/notes.spec.ts @@ -0,0 +1,64 @@ +import { test, expect } from "@playwright/test"; +import fs from "node:fs"; +import path from "node:path"; +import { launch, seedHome, tid } from "./support"; +import { savedNotes } from "./notes-support"; + +const at = "2026-10-01T09:00:00.000Z"; +const legacyPage = (id: string, parentId: string | null, title: string, markdown: string) => + ({ id, parentId, title, markdown, favorite: false, createdAt: at, updatedAt: at, trashedAt: null, revision: 1 }); + +test("existing Space pages move into the notes folder once, with their history, and space.json stays as it was", async () => { + const { home, repo } = seedHome(); + const pages = [legacyPage("plan-1", null, "Plan", "# Plan"), legacyPage("child-1", "plan-1", "Child", "Inside the plan")]; + const legacy = path.join(home, "app", "space.json"); + fs.writeFileSync(legacy, JSON.stringify({ version: 2, pages, history: pages.map(page => ({ page, actor: "human", summary: "Created page" })), comments: [] })); + const before = fs.readFileSync(legacy, "utf8"); + let session = await launch(home); + try { + await tid(session.page, "rail-space").click(); + await session.page.getByRole("button", { name: "Open Child", exact: true }).click(); + await expect(session.page.getByRole("textbox", { name: "Page title" })).toHaveValue("Child"); + await expect(session.page.getByText("Inside the plan", { exact: true })).toBeVisible(); + await session.page.getByRole("button", { name: "Page actions" }).click(); + await session.page.getByRole("menuitem", { name: "Version history" }).click(); + await expect(session.page.getByText("Revision 1 · You · Created page", { exact: true })).toBeVisible(); + expect(savedNotes(home).map(note => [note.rel, note.id])).toEqual([["Personal/Notes/Plan/Child.md", "child-1"], ["Personal/Notes/Plan/Plan.md", "plan-1"]]); + } finally { await session.app.close(); } + session = await launch(home); + try { + const listed = await session.page.evaluate(() => window.modex!.invoke("space:list", undefined)); + expect(listed.map(page => [page.id, page.parentId]).sort()).toEqual([["child-1", "plan-1"], ["plan-1", null]]); + expect(fs.readFileSync(legacy, "utf8")).toBe(before); + expect(fs.readdirSync(path.join(home, "app")).filter(name => name.startsWith("space.json.pre-notes-"))).toHaveLength(1); + } finally { + await session.app.close(); + fs.rmSync(home, { recursive: true, force: true }); + fs.rmSync(repo, { recursive: true, force: true }); + } +}); + +test("an edit made outside Modex shows in Space and in the page's history", async () => { + const { home, repo } = seedHome(); + const { app, page } = await launch(home); + try { + await tid(page, "rail-space").click(); + await page.getByRole("button", { name: "New page", exact: true }).click(); + await page.getByRole("textbox", { name: "Page title" }).fill("Outside"); + await page.getByRole("textbox", { name: "Block 1" }).fill("Written in Modex"); + await expect(page.getByRole("status", { name: "Save status" })).toHaveText("Saved locally"); + await page.getByRole("textbox", { name: "Page title" }).click(); + await page.getByRole("textbox", { name: "Page title" }).blur(); + await expect.poll(() => savedNotes(home).find(note => note.title === "Outside")?.rel).toBe("Personal/Notes/Outside.md"); + const file = path.join(home, "notes", "Personal", "Notes", "Outside.md"); + fs.writeFileSync(file, fs.readFileSync(file, "utf8").replace("Written in Modex", "Edited in another editor")); + await expect(page.getByText("Edited in another editor", { exact: true })).toBeVisible({ timeout: 15_000 }); + await page.getByRole("button", { name: "Page actions" }).click(); + await page.getByRole("menuitem", { name: "Version history" }).click(); + await expect(page.getByText(/Revision \d+ · Outside Modex · Edited outside Modex/)).toBeVisible(); + } finally { + await app.close(); + fs.rmSync(home, { recursive: true, force: true }); + fs.rmSync(repo, { recursive: true, force: true }); + } +}); diff --git a/apps/desktop/e2e/pages-agents.spec.ts b/apps/desktop/e2e/pages-agents.spec.ts index 6ec66cb1..839e9171 100644 --- a/apps/desktop/e2e/pages-agents.spec.ts +++ b/apps/desktop/e2e/pages-agents.spec.ts @@ -2,6 +2,7 @@ import { test, expect } from "@playwright/test"; import fs from "node:fs"; import path from "node:path"; import { launch, seedHome, tid } from "./support"; +import { savedNotes } from "./notes-support"; test("Pages notes access persists; open notes refresh and recover historical revisions", async () => { const { home, repo } = seedHome(); @@ -30,7 +31,7 @@ test("Pages notes access persists; open notes refresh and recover historical rev await first.page.getByText("Revision 1 · You · Created page", { exact: true }).click(); await first.page.getByRole("button", { name: "Restore revision 1", exact: true }).click(); await expect(first.page.getByText("Original human text", { exact: true }).first()).toBeVisible(); - await expect.poll(() => JSON.parse(fs.readFileSync(path.join(home, "app/space.json"), "utf8")).pages[0].revision).toBe(3); + await expect.poll(() => first.page.evaluate(() => window.modex!.invoke("space:list", undefined)).then(pages => pages[0]?.revision)).toBe(3); } finally { await first.app.close(); } const second = await launch(home); try { @@ -84,7 +85,7 @@ try { await expect(link).toBeVisible(); await link.click(); await expect(page.getByRole("textbox", { name: "Page title" })).toHaveValue("CLI note"); await expect(page.getByText("Human content. Verified decision.", { exact: true })).toBeVisible(); - expect(fs.existsSync(path.join(repo, "space.json"))).toBe(false); + expect(fs.existsSync(path.join(repo, "space.json")) || fs.existsSync(path.join(repo, "notes"))).toBe(false); const url = fs.readFileSync(path.join(home, "pages-url"), "utf8"); await expect.poll(async () => { const r = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream" }, body: JSON.stringify({ jsonrpc: "2.0", id: 99, method: "tools/call", params: { name: "search", arguments: { query: "" } } }) }); @@ -125,8 +126,7 @@ test("draft recovery locks editing and saves a copy without overwriting a concur await app.evaluate(() => (globalThis as any).__recover()); await expect(tid(page, "space")).not.toHaveAttribute("inert", ""); await expect(page.getByText("Agent version", { exact: true })).toBeVisible(); - const pages = JSON.parse(fs.readFileSync(path.join(home, "app/space.json"), "utf8")).pages; - expect(pages.map((p: any) => p.markdown).sort()).toEqual(["Agent version", "Keep my draft"]); + expect(savedNotes(home).map(note => note.markdown).sort()).toEqual(["Agent version", "Keep my draft"]); } finally { await app.evaluate(({ BrowserWindow }) => BrowserWindow.getAllWindows().forEach(w => w.destroy())); await app.close(); diff --git a/apps/desktop/e2e/space.spec.ts b/apps/desktop/e2e/space.spec.ts index d7e23f1d..111a9930 100644 --- a/apps/desktop/e2e/space.spec.ts +++ b/apps/desktop/e2e/space.spec.ts @@ -2,6 +2,7 @@ import { test, expect, type Page } from "@playwright/test"; import fs from "node:fs"; import path from "node:path"; import { appDir, launch, seedHome, tid } from "./support"; +import { blockNoteWrites, savedNotes, unblockNoteWrites } from "./notes-support"; async function holdAppFrames(page: Page) { await page.evaluate(() => { @@ -116,7 +117,7 @@ test("Space preserves dedented imported tasks and checks only the selected task" await page.getByRole("checkbox", { name: "Later task" }).check(); await expect(page.getByRole("checkbox", { name: "Later task" })).toBeChecked(); await expect(page.getByRole("checkbox", { name: "Earlier task" })).not.toBeChecked(); - await expect.poll(() => JSON.parse(fs.readFileSync(path.join(home, "app", "space.json"), "utf8")).pages[0].markdown).toBe(source.replace("[ ] Later", "[x] Later")); + await expect.poll(() => savedNotes(home)[0]?.markdown).toBe(source.replace("[ ] Later", "[x] Later")); } finally { await app.close(); } }); @@ -217,10 +218,8 @@ test("Space reports save failures and retains text for retry; imported links sta try { await tid(page, "rail-space").click(); await page.getByRole("button", { name: "New page", exact: true }).click(); - // Replace the storage target with a directory to provoke a real filesystem write failure. - const file = path.join(home, "app", "space.json"); - fs.renameSync(file, `${file}.backup`); - fs.mkdirSync(file); + // Refuse the page's version history to provoke a real filesystem write failure. + blockNoteWrites(home); await page.getByRole("textbox", { name: "Block 1" }).fill("Never lose this draft."); await expect(page.getByRole("status", { name: "Save status" })).toHaveText("Not saved"); await expect(page.getByRole("textbox", { name: "Block 1" })).toHaveValue("Never lose this draft."); @@ -231,10 +230,10 @@ test("Space reports save failures and retains text for retry; imported links sta })); await expect(page.getByRole("textbox", { name: "Block 1" })).toHaveValue("Never lose this draft."); await expect.poll(() => page.evaluate(() => window.modex.invoke("space:list", undefined).then(() => "ready", error => error.message))).not.toContain("shutting down"); - fs.rmdirSync(file); fs.renameSync(`${file}.backup`, file); + unblockNoteWrites(home); await page.getByRole("button", { name: "Retry", exact: true }).click(); await expect(page.getByRole("status", { name: "Save status" })).toHaveText("Saved locally"); - expect(fs.readFileSync(file, "utf8")).toContain("Never lose this draft."); + expect(savedNotes(home).map(note => note.markdown).join("\n")).toContain("Never lose this draft."); await page.getByLabel("Import Markdown file").setInputFiles({ name: "unsafe.md", mimeType: "text/markdown", buffer: Buffer.from("[Local file](file:///etc/passwd)\n\n[Run](javascript:alert)\n\n") }); await expect(page.getByRole("textbox", { name: "Page title" })).toHaveValue("unsafe"); await expect(tid(page, "space").locator('a[href^="file:"], a[href^="javascript:"], script')).toHaveCount(0); @@ -262,7 +261,7 @@ test("editing imported Markdown preserves nested content and Enter keeps text af await expect(page.getByText("Keep this text", { exact: true })).toBeVisible(); await expect(page.getByRole("link", { name: "Docs", exact: true })).toHaveAttribute("target", "_blank"); await expect(page.getByRole("status", { name: "Save status" })).toHaveText("Saved locally"); - const saved = JSON.parse(fs.readFileSync(path.join(home, "app", "space.json"), "utf8")).pages[0].markdown; + const saved = savedNotes(home)[0]!.markdown; expect(saved).toContain(" - child\n - child two"); expect(saved).toContain("![logo](https://example.com/logo.png)"); expect(saved).toContain("Keep this text"); @@ -292,7 +291,7 @@ test("new-page autofocus preserves typing that has already started", async () => await page.keyboard.insertText("the content"); await expect(input).toHaveValue("Already editing the content"); await expect(page.getByRole("textbox", { name: "Page title" })).toHaveValue(""); - await expect.poll(() => JSON.parse(fs.readFileSync(path.join(home, "app", "space.json"), "utf8")).pages[0].markdown).toBe("Already editing the content"); + await expect.poll(() => savedNotes(home)[0]?.markdown).toBe("Already editing the content"); } finally { await app.close(); } }); diff --git a/apps/desktop/e2e/update-main.spec.ts b/apps/desktop/e2e/update-main.spec.ts index 34934f2c..bc68ffa0 100644 --- a/apps/desktop/e2e/update-main.spec.ts +++ b/apps/desktop/e2e/update-main.spec.ts @@ -2,6 +2,7 @@ import { test, expect, _electron as electron } from "@playwright/test"; import fs from "node:fs"; import path from "node:path"; import { appDir, seedHome, tid } from "./support"; +import { blockNoteWrites, savedNotes, unblockNoteWrites } from "./notes-support"; test("renderer reload after an updater partial drain opens read-only and ordinary Quit preserves saved bytes", async () => { test.skip(process.platform !== "darwin", "macOS updater main assembly"); @@ -57,7 +58,6 @@ test("actual main restart retains drafts after partial drain and retries fresh r let closed = false; app.on("close", () => { closed = true; }); console.log(JSON.stringify({ fixtureHome: home, fixtureRepo: repo, electronPid: app.process().pid })); const receipt = path.join(home, "app/update-recovery.json"); - const space = path.join(home, "app/space.json"); try { const page = await app.firstWindow(); await page.waitForLoadState("domcontentloaded"); // Electron owns beforeunload. Playwright's default dismissal races that @@ -68,12 +68,12 @@ test("actual main restart retains drafts after partial drain and retries fresh r await page.getByRole("button", { name: "Space", exact: true }).click(); await page.getByRole("button", { name: "New page", exact: true }).click(); await expect(page.getByRole("textbox", { name: "Page title" })).toBeVisible(); - fs.renameSync(space, `${space}.backup`); fs.mkdirSync(space); + blockNoteWrites(home); await page.getByRole("textbox", { name: "Page title" }).fill("Dirty page saved through main restart admission"); await expect(page.getByLabel("Save status")).toHaveText("Not saved"); await page.getByRole("button", { name: "Chat", exact: true }).click(); await page.getByRole("button", { name: "Download update", exact: true }).click(); - fs.rmdirSync(space); fs.renameSync(`${space}.backup`, space); + unblockNoteWrites(home); await page.getByRole("button", { name: "Restart to update", exact: true }).click(); const panel = tid(page, "update-restart-status"); await expect(panel).toContainText("could not finish preparing to restart"); @@ -94,7 +94,7 @@ test("actual main restart retains drafts after partial drain and retries fresh r const proof = await app.evaluate(() => (globalThis as any).__updateMainFixture); expect(proof.nativeCalls).toBe(0); expect(proof.pageDisposals).toBe(1); expect(proof.pageSaves).toContainEqual({ held: true, title: "Dirty page saved through main restart admission" }); - expect(JSON.parse(fs.readFileSync(space, "utf8")).pages[0].title).toBe("Dirty page saved through main restart admission"); + expect(savedNotes(home)[0]?.title).toBe("Dirty page saved through main restart admission"); expect(proof.prepared.some((reply: any) => reply.revision === saved.revision)).toBe(true); expect(proof.quitPrepared.filter((reply: any) => reply.revision === saved.revision)).toHaveLength(1); // Record the second fresh acknowledgment before the actual process exits. diff --git a/apps/desktop/e2e/update-preflight.spec.ts b/apps/desktop/e2e/update-preflight.spec.ts index 459cb291..a9f93b34 100644 --- a/apps/desktop/e2e/update-preflight.spec.ts +++ b/apps/desktop/e2e/update-preflight.spec.ts @@ -2,6 +2,7 @@ import { test, expect, type ElectronApplication } from "@playwright/test"; import fs from "node:fs"; import path from "node:path"; import { launch, seedHome, tid } from "./support"; +import { blockNoteWrites, savedNotes, unblockNoteWrites } from "./notes-support"; // Exercise the production preload and renderer barrier. No native update is staged. function prepare(app: ElectronApplication, id: string) { @@ -49,7 +50,6 @@ test("open Settings and failed Space saves refuse preparation without discarding const seeded = seedHome(); const home = fs.realpathSync(seeded.home), repo = seeded.repo; const { app, page } = await launch(home); console.log(JSON.stringify({ fixtureHome: home, fixtureRepo: repo, electronPid: app.process().pid })); - const file = path.join(home, "app", "space.json"); try { await tid(page, "open-settings").click(); expect((await prepare(app, "settings")).error).toMatch(/dialog/i); @@ -60,20 +60,20 @@ test("open Settings and failed Space saves refuse preparation without discarding await page.getByRole("button", { name: "Space", exact: true }).click(); await page.getByRole("button", { name: "New page", exact: true }).click(); await expect(page.getByRole("textbox", { name: "Page title" })).toBeVisible(); - fs.renameSync(file, `${file}.backup`); fs.mkdirSync(file); + blockNoteWrites(home); await page.getByRole("textbox", { name: "Page title" }).fill("Unsaved Space title"); await expect(page.getByLabel("Save status")).toHaveText("Not saved"); expect((await prepare(app, "space")).error).toBeTruthy(); await release(app, "space"); await expect(page.getByRole("textbox", { name: "Page title" })).toHaveValue("Unsaved Space title"); - fs.rmdirSync(file); fs.renameSync(`${file}.backup`, file); + unblockNoteWrites(home); const ready = await prepare(app, "space-retry"); expect(ready.error).toBeUndefined(); - expect(JSON.parse(fs.readFileSync(file, "utf8")).pages[0].title).toBe("Unsaved Space title"); + expect(savedNotes(home)[0]?.title).toBe("Unsaved Space title"); await release(app, "space-retry"); } finally { for (const id of ["settings", "space", "space-retry"]) await release(app, id); - if (fs.existsSync(`${file}.backup`)) { fs.rmSync(file, { recursive: true, force: true }); fs.renameSync(`${file}.backup`, file); } + try { unblockNoteWrites(home); } catch { /* Not blocked. */ } await app.close(); fs.rmSync(home, { recursive: true, force: true }); fs.rmSync(repo, { recursive: true, force: true }); } }); @@ -98,9 +98,9 @@ test("a Markdown import finishes after a refused restart releases editing", asyn await expect.poll(() => page.evaluate(() => typeof (window as unknown as { finishImport?: unknown }).finishImport)).toBe("function"); expect((await prepare(app, "import")).error).toMatch(/Space action/); await page.evaluate(() => (window as unknown as { finishImport: () => void }).finishImport()); - expect(fs.existsSync(path.join(home, "app", "space.json"))).toBe(false); + expect(savedNotes(home)).toEqual([]); await release(app, "import"); await expect(page.getByRole("textbox", { name: "Page title" })).toHaveValue("Preserved import"); - expect(JSON.parse(fs.readFileSync(path.join(home, "app", "space.json"), "utf8")).pages[0].markdown).toContain("Keep this text."); + expect(savedNotes(home)[0]?.markdown).toContain("Keep this text."); } finally { await release(app, "import"); await app.close(); fs.rmSync(home, { recursive: true, force: true }); fs.rmSync(repo, { recursive: true, force: true }); } }); diff --git a/apps/desktop/src/main/commands.ts b/apps/desktop/src/main/commands.ts index d6e23a1d..fb5d1846 100644 --- a/apps/desktop/src/main/commands.ts +++ b/apps/desktop/src/main/commands.ts @@ -55,6 +55,7 @@ export function registerCommands(handle: RegisterCommand, { handle("space:create", (input) => store.space.create(input)); handle("space:save", (page) => store.space.save(page)); handle("space:trash", ({ id, trash }) => store.space.trash(id, trash)); + handle("notes:settle", ({ id }) => store.space.settle(id)); handle("state:get", () => { const state = store.snapshot(); return { ...state, threads: state.threads.map((t) => ({ ...t, status: runner.status(t.id) })) }; diff --git a/apps/desktop/src/main/engine/pages-agents.ts b/apps/desktop/src/main/engine/pages-agents.ts index 89cb8c2e..79de986b 100644 --- a/apps/desktop/src/main/engine/pages-agents.ts +++ b/apps/desktop/src/main/engine/pages-agents.ts @@ -6,7 +6,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, type Tool } from "@model import type { Thread } from "../../shared/types.js"; import type { PagesChange, PagesConnection } from "../../shared/pages.js"; import { pageTitle } from "../../shared/space.js"; -import type { SpaceStore } from "./space-store.js"; +import type { SpacePagesStore } from "./space-store.js"; type Turn = Pick; type Active = { turn: Turn; projectId: string; readOnly: boolean; available: boolean; changed(change: PagesChange): void }; @@ -44,7 +44,7 @@ export class PagesAgents { private readonly server: http.Server; private listening?: Promise; private disposed = false; - constructor(private readonly options: { space: SpaceStore; enabled(projectId: string): boolean; updated?(): void }) { + constructor(private readonly options: { space: SpacePagesStore; enabled(projectId: string): boolean; updated?(): void }) { this.server = http.createServer((req, res) => { void this.handle(req, res).catch(() => { if (!res.headersSent) res.writeHead(500); res.end(); }); }); } private listen(): Promise { diff --git a/apps/desktop/src/main/engine/store.ts b/apps/desktop/src/main/engine/store.ts index 3c574442..89636216 100644 --- a/apps/desktop/src/main/engine/store.ts +++ b/apps/desktop/src/main/engine/store.ts @@ -1,5 +1,5 @@ import { normalizeTheme } from "../../shared/theme.js"; -import { SpaceStore } from "./space-store.js"; +import { NotesStore } from "./notes-store.js"; import fs from "node:fs"; import path from "node:path"; import crypto from "node:crypto"; @@ -102,14 +102,15 @@ export function newId(): string { /** JSON-file persistence for the app shell: projects, threads, settings, and per-thread UI items. */ export class Store { readonly dir: string; - readonly space: SpaceStore; + /** Space pages, as Markdown files under `home/notes/` (docs/notes.md); `app/space.json` is migrated once. */ + readonly space: NotesStore; private state: AppState; private storageUncertain = false; private readonly directories = new Map(); constructor(readonly home: string) { this.dir = path.join(home, "app"); - this.space = new SpaceStore(this.dir); + this.space = new NotesStore(path.join(home, "notes"), { legacySpaceFile: path.join(this.dir, "space.json") }); fs.mkdirSync(path.join(this.dir, "threads"), { recursive: true }); for (const directory of [this.dir, path.join(this.dir, "threads")]) { const stat = fs.lstatSync(directory); diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts index 117b8fd3..9e3e0d11 100644 --- a/apps/desktop/src/main/index.ts +++ b/apps/desktop/src/main/index.ts @@ -633,6 +633,7 @@ handle("space:comment:delete", ({ pageId, id }) => store.space.deleteComment(pag handle("space:create", (input) => store.space.create(input)); handle("space:save", (page) => store.space.save(page)); handle("space:trash", ({ id, trash }) => store.space.trash(id, trash)); +handle("notes:settle", ({ id }) => store.space.settle(id)); handle("state:get", () => { const state = store.snapshot(); diff --git a/apps/desktop/src/renderer/space/PageHistory.tsx b/apps/desktop/src/renderer/space/PageHistory.tsx index e64aa64c..82321b5c 100644 --- a/apps/desktop/src/renderer/space/PageHistory.tsx +++ b/apps/desktop/src/renderer/space/PageHistory.tsx @@ -16,7 +16,7 @@ export function PageHistory({ page, flush, refresh, onClose }: { page: SpacePage return
Version history
{error &&

{error}

} - {versions.map(v =>
Revision {v.page.revision} · {v.actor.startsWith("thread:") ? "Agent" : v.actor === "human" ? "You" : "Imported"} · {v.summary} + {versions.map(v =>
Revision {v.page.revision} · {v.actor.startsWith("thread:") ? "Agent" : v.actor === "human" ? "You" : v.actor === "external" ? "Outside Modex" : "Imported"} · {v.summary}

{new Date(v.page.updatedAt).toLocaleString()} · {v.page.title || "Untitled page"}

{v.page.markdown}
{v.page.revision !== page.revision && }
)} diff --git a/apps/desktop/src/renderer/space/SpaceView.tsx b/apps/desktop/src/renderer/space/SpaceView.tsx index b59b3d34..f6c9c6ec 100644 --- a/apps/desktop/src/renderer/space/SpaceView.tsx +++ b/apps/desktop/src/renderer/space/SpaceView.tsx @@ -106,7 +106,7 @@ export function SpaceView({ sidebarOpen, active, openPage, onOpenChat, chatOpen const run = async (operation: () => Promise) => { try { restartDrafts.assertOpen(); setActionError(null); await operation(); } catch (err) { setActionError((err as Error).message); } }; - const open = (id: string) => { if (view === "knowledge") setView("pages"); setSelected(id); setMenu(false); setNotice(null); setQuote(""); setHistory(false); }; + const open = (id: string) => { if (selected && selected !== id) void space.settle(selected); if (view === "knowledge") setView("pages"); setSelected(id); setMenu(false); setNotice(null); setQuote(""); setHistory(false); }; useEffect(() => { if (openPage) { setView("pages"); setQuery(""); open(openPage.id); void space.refresh(); } }, [openPage]); const create = async (title = "", markdown = "", parentId: string | null = null) => { if (creating) return; @@ -228,7 +228,7 @@ export function SpaceView({ sidebarOpen, active, openPage, onOpenChat, chatOpen
{!space.loaded ?
{space.error ? "Could not load Space." : "Opening Space…"}
: page ?
{ const selection = window.getSelection(); if (selection?.toString().trim()) setQuote(selection.toString().slice(0, 2000)); }} onSelect={event => { if (event.target instanceof HTMLTextAreaElement) setQuote(event.target.value.slice(event.target.selectionStart, event.target.selectionEnd).slice(0, 2000)); }}> - space.edit(page.id, { title: e.target.value })} /> + space.edit(page.id, { title: e.target.value })} onBlur={() => void space.settle(page.id)} /> {history && setHistory(false)} />} clearGeneration()} /> diff --git a/apps/desktop/src/renderer/space/useSpace.ts b/apps/desktop/src/renderer/space/useSpace.ts index 31391329..1374b11f 100644 --- a/apps/desktop/src/renderer/space/useSpace.ts +++ b/apps/desktop/src/renderer/space/useSpace.ts @@ -56,6 +56,12 @@ export function useSpace(active = true) { return inFlight.current; }, []); + /** Once a title is done (it lost focus, or another page opened), the note's file takes its name. */ + const settle = useCallback(async (id: string) => { + // Best effort: the title is already saved in the note, so a rename that fails loses nothing. + try { await flush(); await bridge.invoke("notes:settle", { id }); } catch { /* The file keeps its name until the next settle. */ } + }, [flush]); + useEffect(() => { if (!loaded) return; return restartDrafts.register("pages", async () => { @@ -116,5 +122,5 @@ export function useSpace(active = true) { await load(); } finally { mutating.current = false; setBusy(false); } }; - return { pages, loaded, error, saving, busy, edit, create, trash, flush, refresh: load, preserveDrafts, retry: () => loaded ? flush() : load() }; + return { pages, loaded, error, saving, busy, edit, create, trash, flush, settle, refresh: load, preserveDrafts, retry: () => loaded ? flush() : load() }; } diff --git a/apps/desktop/src/shared/types.ts b/apps/desktop/src/shared/types.ts index 23bcae10..86c229aa 100644 --- a/apps/desktop/src/shared/types.ts +++ b/apps/desktop/src/shared/types.ts @@ -488,6 +488,8 @@ export interface BridgeCommands extends NativeDraftCommands { "space:create": { req: import("./space.js").CreateSpacePage; res: import("./space.js").SpacePage }; "space:save": { req: import("./space.js").SpacePage; res: import("./space.js").SpacePage }; "space:trash": { req: { id: string; trash: boolean }; res: import("./space.js").SpacePage[] }; + /** Renames a page's file to match its title once editing the title is done; typing never renames files. */ + "notes:settle": { req: { id: string }; res: import("./space.js").SpacePage }; "updates:check": { req: undefined; res: ReleaseUpdate | null }; "updates:state": { req: undefined; res: import("./updates.js").UpdateInstallState }; "updates:download": { req: undefined; res: import("./updates.js").UpdateInstallState }; diff --git a/apps/desktop/test/pages-agents.test.ts b/apps/desktop/test/pages-agents.test.ts index c621ee26..928188e1 100644 --- a/apps/desktop/test/pages-agents.test.ts +++ b/apps/desktop/test/pages-agents.test.ts @@ -7,11 +7,12 @@ import http from "node:http"; import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; import { PagesAgents } from "../src/main/engine/pages-agents.js"; -import { SpaceStore } from "../src/main/engine/space-store.js"; +import { NotesStore } from "../src/main/engine/notes-store.js"; async function fixture() { const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pages-agent-")); - const space = new SpaceStore(dir); let enabled = true; const receipts: unknown[] = []; + // The store Modex runs the Pages tools over: notes in a folder. + const space = new NotesStore(path.join(dir, "notes")); let enabled = true; const receipts: unknown[] = []; const agents = new PagesAgents({ space, enabled: () => enabled }); const turn = { id: "thread", projectId: "project", mode: "agent" as "agent" | "chat", plan: false }; const begin = async () => { diff --git a/apps/store-desktop/src/main/demo.ts b/apps/store-desktop/src/main/demo.ts index 1629fa41..fecab3dd 100644 --- a/apps/store-desktop/src/main/demo.ts +++ b/apps/store-desktop/src/main/demo.ts @@ -90,6 +90,7 @@ export class StoreDemo { "space:create": () => { throw new Error("Space is unavailable in the review demo."); }, "space:save": () => { throw new Error("Space is unavailable in the review demo."); }, "space:trash": () => { throw new Error("Space is unavailable in the review demo."); }, + "notes:settle": () => { throw new Error("Space is unavailable in the review demo."); }, "project:add": () => { const project = { id: this.nextId(), name: "Another demo project", path: "/Demo/Sample", addedAt: stamp() }; this.state.projects.push(project); return project; diff --git a/docs/notes.md b/docs/notes.md index 53f54eed..54d6c44e 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -3,7 +3,7 @@ Space notes are moving from one `MODEX_HOME/app/space.json` into a folder of Markdown files, `MODEX_HOME/notes/`, laid out **Workspace › Project › Folder › notes and files**. This page describes the format `NotesStore` (`apps/desktop/src/main/engine/notes-store.ts`) reads and -writes. Until Modex switches to it, Space still uses `space.json`. +writes. Space and the Pages tools (`modex_pages`) use it. ## Layout diff --git a/docs/pages-maintenance.md b/docs/pages-maintenance.md index 176ba899..cb09c764 100644 --- a/docs/pages-maintenance.md +++ b/docs/pages-maintenance.md @@ -26,7 +26,7 @@ Use **Page actions → Version history** to inspect previous content and restore If your unsaved draft conflicts with an agent edit, the editor keeps your text and reports the conflict. **Save drafts as copies and reload** preserves those drafts as new top-level notes and loads the saved versions. The editor is locked while those copies are saved. -Notes and their journal are stored atomically in `MODEX_HOME/app/space.json`. The first change upgrades an older version-1 file to version 2 and preserves existing notes as baseline versions. Older Modex builds cannot read version 2; keep a backup if you need to downgrade. Notes can still be exported as Markdown. +Notes are Markdown files under `MODEX_HOME/notes/`, with their version history kept beside them in `notes/.modex/` ([Notes folder](notes.md)). Agents still work only through `modex_pages`, by page id and revision; an agent never edits the files directly. The first launch moves the pages of `MODEX_HOME/app/space.json` into the folder and leaves that file as it was, so an older Modex still opens it; pages an older build changes there come back under "Recovered from earlier Modex". Notes can still be exported as Markdown. ## Access boundary diff --git a/docs/status.md b/docs/status.md index 30e46d53..aa73b7c6 100644 --- a/docs/status.md +++ b/docs/status.md @@ -588,15 +588,17 @@ v0.0.11 artifacts, including the original CI failures and remaining acceptance l adds `POST /v1/threads/:id/archive` and an `archived` flag on snapshot threads; an older Mac answers the phone with 501. Companion build 6 does not include the phone side; it ships with the next iPhone build. +- **Notes are Markdown files** (first slice of notes in folders). Space pages now live under + `MODEX_HOME/notes/` as one Markdown file per page, in Personal › Notes; a page with child pages + is a folder holding a note of the same name. Ids, revisions, history, trash, comments and the + Pages tools behave as before. Edits, moves and new files made outside Modex (Finder, an editor, + Open Knowledge) show in Space and in the page's history as "Outside Modex". The first launch + moves `app/space.json` into the folder and never writes it again. A file is renamed to match its + title when the title loses focus. Workspaces, per-project notes and files come next. + [Notes folder](notes.md). ## In flight -- **Notes in folders** (Workspace › Project › Folder). Space notes move from `app/space.json` to - Markdown files under `MODEX_HOME/notes/`, with each Modex project getting its own notes, a - workspace level grouping projects in the sidebar, folders and files, and Open Knowledge able to - open the same folder. First slice: `NotesStore`, which keeps Space's page contract (ids, - revisions, history, trash, comments) over the files, records edits made outside Modex, and - migrates `space.json` once without writing it. Modex does not use it yet. [Notes folder](notes.md). - **Thread/project deletion during active turns.** A dedicated runner admission hold lets deletion stop and drain its own turns while unrelated turns continue, without weakening restart checks or the native draft preparation/adoption transaction. From e872cf1b3ed33a86de583b5a7c4497dfee40ab68 Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Thu, 15 Oct 2026 03:10:19 -0500 Subject: [PATCH 3/8] List the notes folder as a tree and manage its workspaces and folders NotesStore now lists the folder as workspaces, projects, folders, notes and files (notes:tree, with a version for cheap polling). It can create workspaces, projects and folders, create a page in a project or folder, rename any container or file, move notes, folders and files into a project or folder (projects into a workspace), and delete an empty container. Workspace and project ids live in their marker files; other folders and files keep theirs in the index, found again by path or by inode after a Finder move. A moving page gets a version before its file moves. Reveal in Finder and Open are local-only commands. Coven-Harness: Claude Code / claude-opus-5-5 --- apps/desktop/src/main/commands.ts | 9 + apps/desktop/src/main/engine/notes-store.ts | 276 +++++++++++++++++++- apps/desktop/src/main/index.ts | 9 + apps/desktop/src/shared/notes.ts | 38 +++ apps/desktop/src/shared/space.ts | 6 +- apps/desktop/src/shared/types.ts | 13 + apps/desktop/test/notes-tree.test.ts | 122 +++++++++ apps/store-desktop/src/main/demo.ts | 9 + docs/notes.md | 17 ++ 9 files changed, 495 insertions(+), 4 deletions(-) create mode 100644 apps/desktop/src/shared/notes.ts create mode 100644 apps/desktop/test/notes-tree.test.ts diff --git a/apps/desktop/src/main/commands.ts b/apps/desktop/src/main/commands.ts index fb5d1846..97793719 100644 --- a/apps/desktop/src/main/commands.ts +++ b/apps/desktop/src/main/commands.ts @@ -56,6 +56,15 @@ export function registerCommands(handle: RegisterCommand, { handle("space:save", (page) => store.space.save(page)); handle("space:trash", ({ id, trash }) => store.space.trash(id, trash)); handle("notes:settle", ({ id }) => store.space.settle(id)); + handle("notes:tree", (req) => { const tree = store.space.tree(); return req?.since === tree.version ? { unchanged: true as const, version: tree.version } : tree; }); + handle("notes:workspace:create", ({ name }) => store.space.createWorkspace(name)); + handle("notes:project:create", ({ workspaceId, name }) => store.space.createProject(workspaceId, name)); + handle("notes:folder:create", ({ parentId, name }) => store.space.createFolder(parentId, name)); + handle("notes:rename", ({ id, name }) => store.space.rename(id, name)); + handle("notes:move", ({ ids, targetId }) => { store.space.moveNodes(ids, targetId); return store.space.tree(); }); + handle("notes:delete", ({ id }) => { store.space.deleteEmpty(id); return store.space.tree(); }); + handle("notes:reveal", () => { throw new Error("Reveal in Finder is available in the desktop app."); }); + handle("notes:open", () => { throw new Error("Opening files is available in the desktop app."); }); handle("state:get", () => { const state = store.snapshot(); return { ...state, threads: state.threads.map((t) => ({ ...t, status: runner.status(t.id) })) }; diff --git a/apps/desktop/src/main/engine/notes-store.ts b/apps/desktop/src/main/engine/notes-store.ts index e32349db..76f3aae9 100644 --- a/apps/desktop/src/main/engine/notes-store.ts +++ b/apps/desktop/src/main/engine/notes-store.ts @@ -2,6 +2,7 @@ import fs from "node:fs"; import path from "node:path"; import { createHash, randomUUID } from "node:crypto"; import type { CreateSpacePage, SpaceChangeContext, SpaceComment, SpacePage, SpacePageVersion } from "../../shared/space.js"; +import { canContain, type NotesFile, type NotesFolder, type NotesNode, type NotesNodeKind, type NotesProject, type NotesTree, type NotesWorkspace } from "../../shared/notes.js"; import { nameKey, noteStem, uniqueName } from "../../shared/notes-names.js"; import { formatNote, parseNote, type ParsedNote } from "./notes-frontmatter.js"; import { fsyncDir, moveNoClobber, writeFileDurably } from "./durable-file.js"; @@ -29,7 +30,13 @@ interface IndexEntry { /** Where a note deleted outside Modex lived, so a restore writes it back there. */ original?: string; } -interface NotesIndex { version: 1; defaultProject: string; notes: Record } +interface Placed { rel: string; ino?: number; /** A folder's name as typed, when its folder name could not carry it. */ title?: string } +interface NotesIndex { + version: 1; defaultProject: string; notes: Record; + /** Folders without a marker of their own, and plain files: where each id was last seen. */ + containers?: Record; files?: Record; +} +interface Marker { version: 1; id: string; title: string; order: number; default?: boolean; modexProjectId?: string | null } interface HistoryFile { version: 1; versions: SpacePageVersion[] } interface TrashManifest { version: 1; id: string; trashedAt: string; items: { id: string; original: string; rel: string }[] } export interface MigrationReceipt { @@ -113,11 +120,19 @@ export class NotesStore implements SpacePagesStore { create(input: CreateSpacePage, change?: SpaceChangeContext): SpacePage { const state = this.load(); const now = this.iso(); - const page: SpacePage = { id: randomUUID(), parentId: input.parentId ?? null, title: input.title ?? "", markdown: input.markdown ?? "", favorite: false, createdAt: now, updatedAt: now, trashedAt: null, revision: 1 }; + let dir: string | null = null; + let parentId = input.parentId ?? null; + if (input.containerId !== undefined) { + const container = this.layout(state).byId.get(input.containerId); + if (!container || (container.kind !== "project" && container.kind !== "folder")) throw new Error("Choose a project or folder for the new page."); + dir = container.rel; + parentId = container.kind === "folder" ? container.noteId : null; + } + const page: SpacePage = { id: randomUUID(), parentId, title: input.title ?? "", markdown: input.markdown ?? "", favorite: false, createdAt: now, updatedAt: now, trashedAt: null, revision: 1 }; validate(page); this.validateParent(page, state.pages); const version = this.version(page, change, "Created page"); - const dir = this.dirFor(state, page.parentId, state.index.defaultProject); + dir ??= this.dirFor(state, page.parentId, state.index.defaultProject); const rel = `${dir}/${uniqueName(noteStem(page.title), ".md", this.names(dir))}`; this.writeHistory(page.id, [version]); this.writeNoteAt(state, page, rel); @@ -228,6 +243,261 @@ export class NotesStore implements SpacePagesStore { return page; } + // ── The tree: workspaces, projects, folders and files ──────────────────────────────────── + + /** Everything in the folder, for the sidebar. */ + tree(): NotesTree { + const state = this.load(); + const { nodes, truncated } = this.layout(state); + const version = sha256(JSON.stringify([nodes.map(n => [n.id, n.rel, n.name]), [...state.pages.values()].map(p => [p.id, p.revision, p.trashedAt])])).slice(0, 16); + return { version, nodes, truncated }; + } + + createWorkspace(name: string): NotesWorkspace { + const state = this.load(); + const stem = this.containerName(name); + const dir = uniqueName(stem, "", this.names("")); + const order = Math.max(-1, ...this.layout(state).nodes.filter(n => n.kind === "workspace").map(n => (n as NotesWorkspace).order)) + 1; + fs.mkdirSync(this.abs(dir)); + this.writeMarker(dir, "workspace", { version: 1, id: randomUUID(), title: name.trim(), order }); + return this.layout(this.load()).byId.get(this.readMarker(dir, "workspace")!.id) as NotesWorkspace; + } + + createProject(workspaceId: string, name: string, modexProjectId: string | null = null): NotesProject { + const state = this.load(); + const workspace = this.layout(state).byId.get(workspaceId); + if (!workspace || workspace.kind !== "workspace") throw new Error("Choose a workspace for the project."); + const dir = `${workspace.rel}/${uniqueName(this.containerName(name), "", this.names(workspace.rel))}`; + const order = Math.max(-1, ...this.layout(state).nodes.filter(n => n.kind === "project" && n.parentId === workspaceId).map(n => (n as NotesProject).order)) + 1; + fs.mkdirSync(this.abs(dir)); + this.writeMarker(dir, "project", { version: 1, id: randomUUID(), title: name.trim(), order, modexProjectId }); + return this.layout(this.load()).byId.get(this.readMarker(dir, "project")!.id) as NotesProject; + } + + createFolder(parentId: string, name: string): NotesFolder { + const state = this.load(); + const layout = this.layout(state); + const parent = layout.byId.get(parentId); + if (!parent || !canContain(parent.kind, "folder")) throw new Error("Choose a project or folder for the new folder."); + const dir = `${parent.rel}/${uniqueName(this.containerName(name), "", this.names(parent.rel))}`; + fs.mkdirSync(this.abs(dir)); + const id = randomUUID(); + state.index.containers = { ...state.index.containers, [id]: { rel: dir, ino: fs.statSync(this.abs(dir)).ino, title: name.trim() } }; + this.writeIndex(state.index); + return this.layout(this.load()).byId.get(id) as NotesFolder; + } + + /** + * Renames a workspace, project, folder or file. A folder with a folder note is renamed through its + * page, so the two stay one name; a page itself is renamed by its title. + */ + rename(id: string, name: string): NotesNode { + const state = this.load(); + const node = this.layout(state).byId.get(id); + if (state.pages.has(id) || node?.kind === "note") throw new Error("Rename a page by editing its title."); + if (!node) throw new Error("This item is no longer in your notes."); + if (typeof name !== "string" || !name.trim() || name.length > 200) throw new Error("A name needs 1 to 200 characters."); + if (node.kind === "folder" && node.noteId) { + const page = this.find(state, node.noteId); + this.settle(this.save({ ...page, title: name.trim() }, { actor: "human", summary: "Renamed folder" }).id); + return this.layout(this.load()).byId.get(id)!; + } + const parent = path.posix.dirname(node.rel) === "." ? "" : path.posix.dirname(node.rel); + const ext = node.kind === "file" ? path.posix.extname(node.rel) : ""; + const stem = node.kind === "file" ? noteStem(name.trim().replace(new RegExp(`${ext.replace(".", "\\.")}$`, "i"), "")) : this.containerName(name); + const own = path.posix.basename(node.rel); + const next = `${parent ? `${parent}/` : ""}${uniqueName(stem, ext, this.names(parent).filter(n => nameKey(n) !== nameKey(own)))}`; + if (next !== node.rel) { + if (nameKey(next) === nameKey(node.rel)) fs.renameSync(this.abs(node.rel), this.abs(next)); + else moveNoClobber(this.abs(node.rel), this.abs(next)); + } + if (node.kind === "workspace" || node.kind === "project") { + const marker = this.readMarker(next, node.kind); + if (marker) this.writeMarker(next, node.kind, { ...marker, title: name.trim() }); + } + this.place(state.index, node, next); + if (node.kind === "folder") state.index.containers = { ...state.index.containers, [id]: { ...state.index.containers![id]!, title: name.trim() } }; + this.writeIndex(state.index); + return this.layout(this.load()).byId.get(id)!; + } + + /** + * Moves notes, folders and files into a project or folder, or projects into a workspace. A page + * that moves gets a version first, so the next read never mistakes it for a move made outside Modex. + */ + moveNodes(ids: string[], targetId: string): void { + const state = this.load(); + const layout = this.layout(state); + const target = layout.byId.get(targetId); + if (!target) throw new Error("Choose where to move these."); + for (const id of ids) { + const node = layout.byId.get(id); + if (!node) throw new Error("This item is no longer in your notes."); + if (!canContain(target.kind, node.kind)) throw new Error(`A ${node.kind} cannot go into a ${target.kind}.`); + if (target.rel === node.rel || target.rel.startsWith(`${node.rel}/`)) throw new Error("A folder cannot be moved inside itself."); + } + for (const id of ids) { + const now = this.layout(this.load()); + const node = now.byId.get(id)!; + const into = now.byId.get(targetId)!; + const fresh = this.load(); + if (node.kind === "note") { + const page = this.find(fresh, node.id); + if (page.trashedAt) throw new Error("Restore this page before moving it."); + const parentId = into.kind === "folder" ? into.noteId : null; + const rel = `${into.rel}/${uniqueName(stemOf(node.rel), ".md", this.names(into.rel))}`; + const moved: SpacePage = { ...page, parentId, updatedAt: this.iso(), revision: page.revision + 1 }; + this.writeHistory(page.id, [...(this.readHistory(page.id) ?? []), { page: moved, actor: "human", summary: "Moved page" }]); + this.renameNote(fresh, moved, node.rel, rel); + this.writeIndex(fresh.index); + continue; + } + const ext = node.kind === "file" ? path.posix.extname(node.rel) : ""; + const base = path.posix.basename(node.rel); + const name = node.kind === "file" ? uniqueName(base.slice(0, base.length - ext.length), ext, this.names(into.rel)) : uniqueName(base, "", this.names(into.rel)); + const rel = `${into.rel}/${name}`; + if (node.kind === "folder" && node.noteId) { + // The folder note goes with its folder; its parent becomes whatever the new place's folder note is. + const page = this.find(fresh, node.noteId); + const moved: SpacePage = { ...page, parentId: into.kind === "folder" ? into.noteId : null, updatedAt: this.iso(), revision: page.revision + 1 }; + this.writeHistory(page.id, [...(this.readHistory(page.id) ?? []), { page: moved, actor: "human", summary: "Moved folder" }]); + moveNoClobber(this.abs(node.rel), this.abs(rel)); + this.rebase(fresh, node.rel, rel); + if (name !== base) this.renameNote(fresh, moved, `${rel}/${base}.md`, `${rel}/${name}.md`); + else fresh.index.notes[page.id] = { ...fresh.index.notes[page.id]!, rel: `${rel}/${base}.md` }; + } else { + moveNoClobber(this.abs(node.rel), this.abs(rel)); + this.rebase(fresh, node.rel, rel); + } + this.place(fresh.index, node, rel); + this.writeIndex(fresh.index); + } + } + + /** Where a node is on disk, for Reveal in Finder and Open. */ + pathOf(id: string): string { + const state = this.load(); + const node = this.layout(state).byId.get(id); + const live = state.live.get(id); + if (node) return this.abs(node.rel); + if (live) return this.abs(live.rel); + throw new Error("This item is no longer in your notes."); + } + + /** A workspace's or project's own folder, never anything above it. */ + deleteEmpty(id: string): void { + const node = this.layout(this.load()).byId.get(id); + if (!node || (node.kind !== "workspace" && node.kind !== "project" && node.kind !== "folder")) throw new Error("Only an empty workspace, project or folder can be deleted."); + if (node.kind === "workspace" && (node as NotesWorkspace).isDefault) throw new Error("The default workspace stays; rename it instead."); + const entries = fs.readdirSync(this.abs(node.rel)).filter(n => !n.startsWith(".modex-") && n !== ".DS_Store"); + if (entries.length) throw new Error("Move or trash what is inside first."); + fs.rmSync(this.abs(node.rel), { recursive: true }); + } + + /** The nodes in the folder, and each by id. Ids for folders and files without one are recorded as they are found. */ + private layout(state: State): { nodes: NotesNode[]; byId: Map; truncated: boolean } { + const index = state.index; + const containers = { ...index.containers }; + const files = { ...index.files }; + let changed = false; + const nodes: NotesNode[] = []; + const dirIds = new Map(); + const noteRels = new Map(); + for (const [id, file] of state.live) noteRels.set(file.rel, id); + const folderNotes = new Map(); + for (const [id, file] of state.live) if (this.isFolderNote(file.rel)) folderNotes.set(path.posix.dirname(file.rel), id); + const seen = new Set(); + let truncated = false; + const claim = (map: Record, rel: string, ino: number): string => { + const known = Object.entries(map).find(([, p]) => p.rel === rel)?.[0] + ?? Object.entries(map).find(([oid, p]) => p.ino === ino && !seen.has(oid) && !fs.existsSync(this.abs(p.rel)))?.[0]; + const id = known ?? randomUUID(); + if (!known || map[id]!.rel !== rel || map[id]!.ino !== ino) { map[id] = { ...map[id], rel, ino }; changed = true; } + seen.add(id); + return id; + }; + const walk = (dirRel: string, level: number, parentId: string | null) => { + let entries: fs.Dirent[]; + try { entries = fs.readdirSync(dirRel ? this.abs(dirRel) : this.root, { withFileTypes: true }); } catch { return; } + entries.sort((a, b) => a.name.localeCompare(b.name)); + for (const entry of entries) { + if (nodes.length >= 10_000) { truncated = true; return; } + if (entry.name.startsWith(".") || entry.isSymbolicLink()) continue; + const rel = dirRel ? `${dirRel}/${entry.name}` : entry.name; + if (entry.isDirectory()) { + const ino = fs.statSync(this.abs(rel)).ino; + const kind: NotesNodeKind = level === 0 ? "workspace" : level === 1 ? "project" : "folder"; + if (kind === "workspace" || kind === "project") { + const marker = this.readMarker(rel, kind); + const id = marker?.id ?? claim(containers, rel, ino); + const order = marker?.order ?? Number.MAX_SAFE_INTEGER; + const name = marker?.title || entry.name; + nodes.push(kind === "workspace" + ? { id, kind, parentId: null, name, rel, order, isDefault: Boolean(marker?.default) } + : { id, kind, parentId: parentId!, name, rel, order, isDefault: Boolean(marker?.default), modexProjectId: marker?.modexProjectId ?? null }); + dirIds.set(rel, id); + walk(rel, level + 1, id); + } else { + const id = claim(containers, rel, ino); + const noteId = folderNotes.get(rel) ?? null; + const page = noteId ? state.pages.get(noteId) : undefined; + const typed = containers[id]?.title; + // A typed name stands while the folder still has the name made from it; a rename in Finder wins. + const name = page?.title.trim() || (typed && noteStem(typed) === entry.name ? typed : entry.name); + nodes.push({ id, kind: "folder", parentId: parentId!, name, rel, noteId }); + dirIds.set(rel, id); + walk(rel, level + 1, id); + } + continue; + } + if (!entry.isFile()) continue; + const noteId = noteRels.get(rel); + if (noteId) { + if (folderNotes.get(dirRel) === noteId) continue; + nodes.push({ id: noteId, kind: "note", parentId, name: state.pages.get(noteId)?.title.trim() || stemOf(rel), rel }); + continue; + } + const stat = fs.statSync(this.abs(rel)); + const id = claim(files, rel, stat.ino); + const ext = path.posix.extname(entry.name).toLowerCase(); + const preview = /^\.(png|jpe?g|gif|webp|svg|avif)$/.test(ext) ? "image" : /^\.(txt|md|json|csv|ya?ml|log|ts|js|tsx|jsx|css|html)$/.test(ext) && stat.size <= 1_048_576 ? "text" : null; + nodes.push({ id, kind: "file", parentId, name: entry.name, rel, size: stat.size, preview } satisfies NotesFile); + } + }; + walk("", 0, null); + // Ids for folders and files that are gone stay out of the index. + for (const id of Object.keys(containers)) if (!seen.has(id)) { delete containers[id]; changed = true; } + for (const id of Object.keys(files)) if (!seen.has(id)) { delete files[id]; changed = true; } + if (changed) { index.containers = containers; index.files = files; this.writeIndex(index); } + nodes.sort((a, b) => (a.kind === "workspace" && b.kind === "workspace") || (a.kind === "project" && b.kind === "project") ? ((a as NotesWorkspace).order - (b as NotesWorkspace).order) || a.name.localeCompare(b.name) : 0); + return { nodes, byId: new Map(nodes.map(n => [n.id, n])), truncated }; + } + + /** A folder name for a workspace, project or folder title. */ + private containerName(name: string): string { + if (typeof name !== "string" || !name.trim() || name.length > 200) throw new Error("A name needs 1 to 200 characters."); + return noteStem(name); + } + + private readMarker(dirRel: string, kind: "workspace" | "project"): Marker | null { + try { + const marker = JSON.parse(fs.readFileSync(this.abs(`${dirRel}/.modex-${kind}.json`), "utf8")) as Marker; + return marker?.version === 1 && typeof marker.id === "string" && ID.test(marker.id) ? marker : null; + } catch { return null; } + } + + private writeMarker(dirRel: string, kind: "workspace" | "project", marker: Marker): void { + writeFileDurably(this.abs(`${dirRel}/.modex-${kind}.json`), JSON.stringify(marker)); + } + + /** Records where a moved or renamed folder or file now is. */ + private place(index: NotesIndex, node: NotesNode, rel: string): void { + if (node.kind === "file") index.files = { ...index.files, [node.id]: { rel, ino: fs.statSync(this.abs(rel)).ino } }; + else if (node.kind === "folder" || !this.readMarker(rel, node.kind as "workspace" | "project")) index.containers = { ...index.containers, [node.id]: { ...index.containers?.[node.id], rel, ino: fs.statSync(this.abs(rel)).ino } }; + // Notes inside a moved folder are found by their ids on the next read. + for (const [id, entry] of Object.entries(index.notes)) if (entry.rel?.startsWith(`${node.rel}/`)) index.notes[id] = { ...entry, rel: `${rel}${entry.rel.slice(node.rel.length)}` }; + } + // ── Reading and reconciling ────────────────────────────────────────────────────────────── private load(): State { diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts index 9e3e0d11..74110d2a 100644 --- a/apps/desktop/src/main/index.ts +++ b/apps/desktop/src/main/index.ts @@ -634,6 +634,15 @@ handle("space:create", (input) => store.space.create(input)); handle("space:save", (page) => store.space.save(page)); handle("space:trash", ({ id, trash }) => store.space.trash(id, trash)); handle("notes:settle", ({ id }) => store.space.settle(id)); +handle("notes:tree", (req) => { const tree = store.space.tree(); return req?.since === tree.version ? { unchanged: true as const, version: tree.version } : tree; }); +handle("notes:workspace:create", ({ name }) => store.space.createWorkspace(name)); +handle("notes:project:create", ({ workspaceId, name }) => store.space.createProject(workspaceId, name)); +handle("notes:folder:create", ({ parentId, name }) => store.space.createFolder(parentId, name)); +handle("notes:rename", ({ id, name }) => store.space.rename(id, name)); +handle("notes:move", ({ ids, targetId }) => { store.space.moveNodes(ids, targetId); return store.space.tree(); }); +handle("notes:delete", ({ id }) => { store.space.deleteEmpty(id); return store.space.tree(); }); +handle("notes:reveal", ({ id }) => shell.showItemInFolder(store.space.pathOf(id)), { localOnly: true }); +handle("notes:open", async ({ id }) => { const error = await shell.openPath(store.space.pathOf(id)); if (error) throw new Error(error); }, { localOnly: true }); handle("state:get", () => { const state = store.snapshot(); diff --git a/apps/desktop/src/shared/notes.ts b/apps/desktop/src/shared/notes.ts new file mode 100644 index 00000000..751a3a1c --- /dev/null +++ b/apps/desktop/src/shared/notes.ts @@ -0,0 +1,38 @@ +/** + * The notes folder as a tree: Workspace › Project › Folder › notes and files (docs/notes.md). + * Pages stay `SpacePage`s, addressed by id and revision; this describes where they and everything + * else in the folder sit. Paths (`rel`) use `/` and are relative to the notes folder. + */ +export type NotesNodeKind = "workspace" | "project" | "folder" | "note" | "file"; + +interface NotesNodeBase { + id: string; + kind: NotesNodeKind; + /** The workspace, project or folder this sits in; null for a workspace. */ + parentId: string | null; + name: string; + rel: string; +} +export interface NotesWorkspace extends NotesNodeBase { kind: "workspace"; parentId: null; order: number; isDefault: boolean } +export interface NotesProject extends NotesNodeBase { kind: "project"; order: number; isDefault: boolean; /** The Modex project whose notes these are, if any. */ modexProjectId: string | null } +/** A folder; `noteId` is its folder note (the page named like the folder), when it has one. */ +export interface NotesFolder extends NotesNodeBase { kind: "folder"; noteId: string | null } +/** A page. Its title, text and revision come from `space:list`. */ +export interface NotesNote extends NotesNodeBase { kind: "note" } +export interface NotesFile extends NotesNodeBase { kind: "file"; size: number; /** A preview the renderer can show without opening another app. */ preview: "image" | "text" | null } +export type NotesNode = NotesWorkspace | NotesProject | NotesFolder | NotesNote | NotesFile; + +export interface NotesTree { + /** Changes whenever anything in the folder does; `notes:tree { since }` answers `unchanged` while it holds. */ + version: string; + nodes: NotesNode[]; + /** More than the listing limit: the folder holds more than is shown. */ + truncated: boolean; +} + +/** Where things may go: workspaces at the top, projects in workspaces, everything else in a project or folder. */ +export function canContain(container: NotesNodeKind | null, kind: NotesNodeKind): boolean { + if (kind === "workspace") return container === null; + if (kind === "project") return container === "workspace"; + return container === "project" || container === "folder"; +} diff --git a/apps/desktop/src/shared/space.ts b/apps/desktop/src/shared/space.ts index 518c40b6..13d7703d 100644 --- a/apps/desktop/src/shared/space.ts +++ b/apps/desktop/src/shared/space.ts @@ -15,6 +15,10 @@ export interface SpaceChangeContext { actor: string; summary: string; } export interface SpaceComment { id: string; pageId: string; text: string; quote: string; createdAt: string; } export interface SpacePageVersion extends SpaceChangeContext { page: SpacePage; /** Start of a coalesced human typing checkpoint. */ checkpointAt?: string; } -export type CreateSpacePage = { title?: string; parentId?: string | null; markdown?: string }; +export type CreateSpacePage = { + title?: string; parentId?: string | null; markdown?: string; + /** A project or folder of the notes tree to create the page in; its folder note, if any, becomes the parent. */ + containerId?: string; +}; export function pageTitle(page: Pick): string { return page.title.trim() || "Untitled page"; } diff --git a/apps/desktop/src/shared/types.ts b/apps/desktop/src/shared/types.ts index 86c229aa..20a9c70d 100644 --- a/apps/desktop/src/shared/types.ts +++ b/apps/desktop/src/shared/types.ts @@ -490,6 +490,19 @@ export interface BridgeCommands extends NativeDraftCommands { "space:trash": { req: { id: string; trash: boolean }; res: import("./space.js").SpacePage[] }; /** Renames a page's file to match its title once editing the title is done; typing never renames files. */ "notes:settle": { req: { id: string }; res: import("./space.js").SpacePage }; + /** The notes folder as a tree; `since` a version that still holds answers `unchanged`. */ + "notes:tree": { req: { since?: string } | undefined; res: import("./notes.js").NotesTree | { unchanged: true; version: string } }; + "notes:workspace:create": { req: { name: string }; res: import("./notes.js").NotesWorkspace }; + "notes:project:create": { req: { workspaceId: string; name: string }; res: import("./notes.js").NotesProject }; + "notes:folder:create": { req: { parentId: string; name: string }; res: import("./notes.js").NotesFolder }; + /** Renames a workspace, project, folder or file; a page is renamed by its title. */ + "notes:rename": { req: { id: string; name: string }; res: import("./notes.js").NotesNode }; + /** Moves notes, folders and files into a project or folder, or projects into a workspace. */ + "notes:move": { req: { ids: string[]; targetId: string }; res: import("./notes.js").NotesTree }; + /** Deletes an empty workspace, project or folder. */ + "notes:delete": { req: { id: string }; res: import("./notes.js").NotesTree }; + "notes:reveal": { req: { id: string }; res: void }; + "notes:open": { req: { id: string }; res: void }; "updates:check": { req: undefined; res: ReleaseUpdate | null }; "updates:state": { req: undefined; res: import("./updates.js").UpdateInstallState }; "updates:download": { req: undefined; res: import("./updates.js").UpdateInstallState }; diff --git a/apps/desktop/test/notes-tree.test.ts b/apps/desktop/test/notes-tree.test.ts new file mode 100644 index 00000000..72054549 --- /dev/null +++ b/apps/desktop/test/notes-tree.test.ts @@ -0,0 +1,122 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import fs from "node:fs"; +import path from "node:path"; +import { NotesStore } from "../src/main/engine/notes-store.js"; +import type { NotesFolder, NotesNode, NotesProject, NotesWorkspace } from "../src/shared/notes.js"; +import { tmpdir } from "./helpers.js"; + +function withStore(run: (store: NotesStore, root: string) => void): void { + const home = tmpdir("modex-notes-tree-"); + const root = path.join(home, "notes"); + try { run(new NotesStore(root), root); } finally { fs.rmSync(home, { recursive: true, force: true }); } +} +const named = (nodes: NotesNode[], name: string) => nodes.find(n => n.name === name)!; +const shape = (nodes: NotesNode[]) => nodes.map(n => `${n.kind}:${n.rel}`).sort(); + +test("the tree lists workspaces, projects, folders, notes and files, with the default workspace first", () => withStore((store, root) => { + const note = store.create({ title: "Hello" }); + fs.writeFileSync(path.join(root, "Personal", "Notes", "sketch.png"), "png"); + const tree = store.tree(); + assert.deepEqual(shape(tree.nodes), ["file:Personal/Notes/sketch.png", "note:Personal/Notes/Hello.md", "project:Personal/Notes", "workspace:Personal"]); + const workspace = named(tree.nodes, "Personal") as NotesWorkspace; + const project = named(tree.nodes, "Notes") as NotesProject; + assert.equal(workspace.isDefault, true); + assert.equal(project.parentId, workspace.id); + assert.equal(named(tree.nodes, "Hello").id, note.id, "a note node is its page"); + assert.equal(named(tree.nodes, "Hello").parentId, project.id); + assert.equal((named(tree.nodes, "sketch.png") as { preview: string }).preview, "image"); + assert.equal(store.tree().version, tree.version, "nothing changed, same version"); + store.save({ ...store.list()[0]!, markdown: "changed" }); + assert.notEqual(store.tree().version, tree.version); +})); + +test("workspaces, projects and folders are created, and pages can be made in a project or folder", () => withStore((store, root) => { + const work = store.createWorkspace("TypeSafeAI"); + const modex = store.createProject(work.id, "modex", "proj-1"); + const folder = store.createFolder(modex.id, "Design: v2"); + assert.ok(fs.existsSync(path.join(root, "TypeSafeAI", "modex", "Design- v2"))); + assert.equal(modex.modexProjectId, "proj-1"); + const page = store.create({ title: "Spec", containerId: folder.id }); + assert.ok(fs.existsSync(path.join(root, "TypeSafeAI", "modex", "Design- v2", "Spec.md"))); + assert.equal(page.parentId, null, "a folder without a folder note gives no parent page"); + const tree = store.tree(); + assert.equal(named(tree.nodes, "Spec").parentId, folder.id); + assert.equal(named(tree.nodes, "Design: v2").id, folder.id, "a folder keeps the name as typed, though its folder cannot carry the colon"); + assert.equal((named(tree.nodes, "TypeSafeAI") as NotesWorkspace).order, 1, "a new workspace goes after the default one"); + assert.throws(() => store.createFolder(work.id, "Loose"), /project or folder/); + assert.throws(() => store.createProject(modex.id, "Nested"), /workspace/); + assert.throws(() => store.create({ title: "x", containerId: work.id }), /project or folder/); + assert.throws(() => store.createWorkspace(" "), /name/); + // Ids survive a restart. + const again = new NotesStore(root).tree(); + assert.deepEqual(shape(again.nodes), shape(tree.nodes)); + assert.equal(named(again.nodes, "Spec").parentId, folder.id); +})); + +test("rename keeps ids; a folder with a folder note is renamed through its page", () => withStore((store, root) => { + const work = store.createWorkspace("Clients"); + const project = store.createProject(work.id, "Acme"); + const plan = store.create({ title: "Plan", containerId: project.id }); + store.create({ title: "Step", parentId: plan.id }); + const planFolder = store.tree().nodes.find(n => n.kind === "folder" && (n as NotesFolder).noteId === plan.id)!; + store.rename(planFolder.id, "Roadmap"); + assert.ok(fs.existsSync(path.join(root, "Clients", "Acme", "Roadmap", "Roadmap.md"))); + assert.ok(fs.existsSync(path.join(root, "Clients", "Acme", "Roadmap", "Step.md"))); + assert.equal(store.list().find(p => p.id === plan.id)?.title, "Roadmap"); + assert.equal(store.history(plan.id).at(-1)!.summary, "Renamed folder"); + store.rename(work.id, "Customers"); + assert.ok(fs.existsSync(path.join(root, "Customers", "Acme"))); + assert.equal(store.tree().nodes.find(n => n.id === work.id)?.name, "Customers"); + assert.equal(store.tree().nodes.find(n => n.id === project.id)?.rel, "Customers/Acme", "the project moved with its workspace"); + fs.writeFileSync(path.join(root, "Customers", "Acme", "brief.pdf"), "pdf"); + const brief = named(store.tree().nodes, "brief.pdf"); + store.rename(brief.id, "Final brief"); + assert.ok(fs.existsSync(path.join(root, "Customers", "Acme", "Final brief.pdf")), "a file keeps its extension"); + assert.equal(named(store.tree().nodes, "Final brief.pdf").id, brief.id); + assert.throws(() => store.rename(plan.id, "x"), /title/); +})); + +test("moving notes, folders and files records page versions and keeps the tree consistent", () => withStore((store, root) => { + const project = store.tree().nodes.find(n => n.kind === "project")!; + const box = store.createFolder(project.id, "Box"); + const loose = store.create({ title: "Loose" }); + const parent = store.create({ title: "Parent" }); + const child = store.create({ title: "Child", parentId: parent.id }); + store.moveNodes([loose.id], box.id); + assert.ok(fs.existsSync(path.join(root, "Personal", "Notes", "Box", "Loose.md"))); + assert.deepEqual(store.history(loose.id).map(v => v.summary).at(-1), "Moved page"); + assert.equal(store.list().find(p => p.id === loose.id)?.revision, 2, "no extra 'outside Modex' version on the next read"); + const parentFolder = store.tree().nodes.find(n => n.kind === "folder" && (n as NotesFolder).noteId === parent.id)!; + store.moveNodes([parentFolder.id], box.id); + assert.ok(fs.existsSync(path.join(root, "Personal", "Notes", "Box", "Parent", "Child.md"))); + assert.equal(store.list().find(p => p.id === child.id)?.parentId, parent.id, "children stay under their folder note"); + assert.equal(store.list().find(p => p.id === child.id)?.revision, 1, "a child that moved with its folder is unchanged"); + fs.writeFileSync(path.join(root, "Personal", "Notes", "data.csv"), "a,b"); + store.moveNodes([named(store.tree().nodes, "data.csv").id], box.id); + assert.ok(fs.existsSync(path.join(root, "Personal", "Notes", "Box", "data.csv"))); + assert.throws(() => store.moveNodes([box.id], parentFolder.id), /inside itself/); + const work = store.tree().nodes.find(n => n.kind === "workspace")!; + assert.throws(() => store.moveNodes([loose.id], work.id), /cannot go into/); + const other = store.createWorkspace("Other"); + store.moveNodes([project.id], other.id); + assert.ok(fs.existsSync(path.join(root, "Other", "Notes", "Box", "Loose.md"))); + assert.equal(new NotesStore(root).list().find(p => p.id === loose.id)?.revision, 2); +})); + +test("folders and files moved or renamed in Finder keep their ids; only empty containers can be deleted", () => withStore((store, root) => { + const project = store.tree().nodes.find(n => n.kind === "project")!; + const folder = store.createFolder(project.id, "Drafts"); + fs.writeFileSync(path.join(root, "Personal", "Notes", "Drafts", "a.txt"), "a"); + const file = named(store.tree().nodes, "a.txt"); + fs.renameSync(path.join(root, "Personal", "Notes", "Drafts"), path.join(root, "Personal", "Notes", "Drafts 2026")); + const tree = store.tree(); + assert.equal(tree.nodes.find(n => n.id === folder.id)?.rel, "Personal/Notes/Drafts 2026"); + assert.equal(tree.nodes.find(n => n.id === file.id)?.rel, "Personal/Notes/Drafts 2026/a.txt"); + assert.throws(() => store.deleteEmpty(folder.id), /inside/); + fs.rmSync(path.join(root, "Personal", "Notes", "Drafts 2026", "a.txt")); + store.deleteEmpty(folder.id); + assert.ok(!fs.existsSync(path.join(root, "Personal", "Notes", "Drafts 2026"))); + const work = store.tree().nodes.find(n => n.kind === "workspace")!; + assert.throws(() => store.deleteEmpty(work.id), /default/); +})); diff --git a/apps/store-desktop/src/main/demo.ts b/apps/store-desktop/src/main/demo.ts index fecab3dd..d27f14a3 100644 --- a/apps/store-desktop/src/main/demo.ts +++ b/apps/store-desktop/src/main/demo.ts @@ -91,6 +91,15 @@ export class StoreDemo { "space:save": () => { throw new Error("Space is unavailable in the review demo."); }, "space:trash": () => { throw new Error("Space is unavailable in the review demo."); }, "notes:settle": () => { throw new Error("Space is unavailable in the review demo."); }, + "notes:tree": () => { throw new Error("Space is unavailable in the review demo."); }, + "notes:workspace:create": () => { throw new Error("Space is unavailable in the review demo."); }, + "notes:project:create": () => { throw new Error("Space is unavailable in the review demo."); }, + "notes:folder:create": () => { throw new Error("Space is unavailable in the review demo."); }, + "notes:rename": () => { throw new Error("Space is unavailable in the review demo."); }, + "notes:move": () => { throw new Error("Space is unavailable in the review demo."); }, + "notes:delete": () => { throw new Error("Space is unavailable in the review demo."); }, + "notes:reveal": unavailable, + "notes:open": unavailable, "project:add": () => { const project = { id: this.nextId(), name: "Another demo project", path: "/Demo/Sample", addedAt: stamp() }; this.state.projects.push(project); return project; diff --git a/docs/notes.md b/docs/notes.md index 54d6c44e..32db0a9a 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -46,6 +46,23 @@ notes/ Knowledge reserves `index.md`). Typing a title does not rename the file; Space renames it when the title loses focus. +## The tree + +`notes:tree` lists the folder as workspaces, projects, folders, notes and files. A note node is +its page. A folder with a folder note is shown once, as the folder, named by its page. + +- **Ids hold across renames and moves.** Workspaces and projects keep theirs in their marker + files. Other folders and plain files keep theirs in `.modex/index.json`, found again by path, + or by inode after a move in Finder. +- **A typed folder name** that a folder cannot carry (a colon, say) is kept in the index. It is + shown while the folder keeps the name made from it; a rename in Finder wins. +- **Placement rules:** workspaces sit at the top, projects in a workspace, and folders, notes and + files in a project or folder. Moving a folder into itself is refused, and so is deleting a + container that still holds anything. +- **A page that moves** gets a version ("Moved page" or "Moved folder") before its file moves, so + the next read does not mistake the move for one made outside Modex. Notes inside a moved + folder keep their revisions. + ## History and revisions The newest version in a page's history file is the page: its revision, favorite, place and trash From 485eb4a4d218558d05b7f02ff7cb04d021b6d2e4 Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Thu, 15 Oct 2026 03:17:46 -0500 Subject: [PATCH 4/8] Show the notes folder as a workspace tree in Space Space's sidebar now lists Workspace > Project > Folder > pages and files from notes:tree, polled like pages. Space options can create a workspace; a row's menu creates a project, folder or page in place, renames (edited inline), moves (Move to... lists only valid places), reveals in Finder, and deletes what is empty. A page opens as before, a folder with a folder note opens that page, and a file opens in its default app. Container rows are named by their name alone so they never collide with a page of the same title. If the tree cannot load, the previous page tree remains. Coven-Harness: Claude Code / claude-opus-5-5 --- apps/desktop/e2e/notes-tree.spec.ts | 58 ++++++++ apps/desktop/src/renderer/space/NotesTree.tsx | 129 ++++++++++++++++++ apps/desktop/src/renderer/space/SpaceView.tsx | 28 +++- apps/desktop/src/renderer/space/space.css | 6 + .../src/renderer/space/useNotesTree.ts | 33 +++++ docs/status.md | 8 +- 6 files changed, 255 insertions(+), 7 deletions(-) create mode 100644 apps/desktop/e2e/notes-tree.spec.ts create mode 100644 apps/desktop/src/renderer/space/NotesTree.tsx create mode 100644 apps/desktop/src/renderer/space/useNotesTree.ts diff --git a/apps/desktop/e2e/notes-tree.spec.ts b/apps/desktop/e2e/notes-tree.spec.ts new file mode 100644 index 00000000..5700b053 --- /dev/null +++ b/apps/desktop/e2e/notes-tree.spec.ts @@ -0,0 +1,58 @@ +import { test, expect } from "@playwright/test"; +import fs from "node:fs"; +import path from "node:path"; +import { launch, seedHome, tid } from "./support"; + +test("workspaces, projects and folders made in Space are folders on disk, and persist", async () => { + const { home, repo } = seedHome(); + const notes = (...parts: string[]) => path.join(home, "notes", ...parts); + let session = await launch(home); + try { + const { page } = session; + await tid(page, "rail-space").click(); + await page.getByRole("button", { name: "Space options" }).click(); + await page.getByRole("menuitem", { name: "New workspace" }).click(); + await page.getByRole("textbox", { name: "New workspace name" }).fill("TypeSafeAI"); + await page.keyboard.press("Enter"); + await expect(page.getByRole("button", { name: "TypeSafeAI", exact: true })).toBeVisible(); + expect(fs.existsSync(notes("TypeSafeAI", ".modex-workspace.json"))).toBe(true); + + await page.getByRole("button", { name: "TypeSafeAI actions" }).click(); + await page.getByRole("menuitem", { name: "New project" }).click(); + await page.getByRole("textbox", { name: "New project name" }).fill("modex"); + await page.keyboard.press("Enter"); + await page.getByRole("button", { name: "modex actions" }).click(); + await page.getByRole("menuitem", { name: "New folder" }).click(); + await page.getByRole("textbox", { name: "New folder name" }).fill("Design"); + await page.keyboard.press("Enter"); + await expect(page.getByRole("button", { name: "Design", exact: true })).toBeVisible(); + + await page.getByRole("button", { name: "Design actions" }).click(); + await page.getByRole("menuitem", { name: "New page" }).click(); + await page.getByRole("textbox", { name: "Page title" }).fill("Spec"); + await page.getByRole("textbox", { name: "Page title" }).blur(); + await expect.poll(() => fs.existsSync(notes("TypeSafeAI", "modex", "Design", "Spec.md"))).toBe(true); + + await page.getByRole("button", { name: "Design actions" }).click(); + await page.getByRole("menuitem", { name: "Rename" }).click(); + await page.getByRole("textbox", { name: "Rename Design" }).fill("Designs"); + await page.keyboard.press("Enter"); + await expect.poll(() => fs.existsSync(notes("TypeSafeAI", "modex", "Designs", "Spec.md"))).toBe(true); + + await page.getByRole("button", { name: "Spec actions" }).click(); + await page.getByRole("menuitem", { name: "Personal › Notes" }).click(); + await expect.poll(() => fs.existsSync(notes("Personal", "Notes", "Spec.md"))).toBe(true); + await expect(page.getByRole("textbox", { name: "Page title" })).toHaveValue("Spec"); + } finally { await session.app.close(); } + session = await launch(home); + try { + await tid(session.page, "rail-space").click(); + await expect(session.page.getByRole("button", { name: "TypeSafeAI", exact: true })).toBeVisible(); + await expect(session.page.getByRole("button", { name: "Designs", exact: true })).toBeVisible(); + await expect(session.page.getByRole("button", { name: "Open Spec", exact: true })).toBeVisible(); + } finally { + await session.app.close(); + fs.rmSync(home, { recursive: true, force: true }); + fs.rmSync(repo, { recursive: true, force: true }); + } +}); diff --git a/apps/desktop/src/renderer/space/NotesTree.tsx b/apps/desktop/src/renderer/space/NotesTree.tsx new file mode 100644 index 00000000..8b318a7d --- /dev/null +++ b/apps/desktop/src/renderer/space/NotesTree.tsx @@ -0,0 +1,129 @@ +import { useEffect, useRef, useState, type ReactNode } from "react"; +import { canContain, type NotesNode, type NotesTree } from "../../shared/notes"; +import { pageTitle, type SpacePage } from "../../shared/space"; +import { SecretInput } from "../streamer"; +import { Icon } from "../components/ui/Icon"; +import { IconButton } from "../components/ui/IconButton"; +import { Menu, MenuItem, MenuLabel, MenuSeparator } from "../components/ui/Menu"; + +/** What the tree is asking its owner to do. Each returns when done; a thrown error is shown by the owner. */ +export interface NotesTreeActions { + openPage(id: string): void; + createPage(containerId: string): Promise; + createFolder(parentId: string, name: string): Promise; + createProject(workspaceId: string, name: string): Promise; + createWorkspace(name: string): Promise; + rename(id: string, name: string): Promise; + move(id: string, targetId: string): Promise; + remove(id: string): Promise; + reveal(id: string): Promise; + openFile(id: string): Promise; +} + +type Editing = { kind: "rename" | "folder" | "project"; id: string; value: string } | { kind: "workspace"; id: null; value: string }; + +/** + * The notes folder as Workspace › Project › Folder › notes and files. A note opens its page; a folder + * with a folder note opens that page; a file opens in its default app. Names are edited in place. + */ +export function NotesTreeView({ tree, pages, selected, actions, newWorkspace }: { tree: NotesTree; pages: SpacePage[]; selected: string | null; actions: NotesTreeActions; newWorkspace: number }) { + const [collapsed, setCollapsed] = useState>(new Set()); + const [editing, setEditing] = useState(null); + useEffect(() => { if (newWorkspace) setEditing({ kind: "workspace", id: null, value: "" }); }, [newWorkspace]); + const byPage = new Map(pages.map(page => [page.id, page])); + const children = (id: string | null) => tree.nodes.filter(node => node.parentId === id); + const nameOf = (node: NotesNode) => node.kind === "note" ? pageTitle(byPage.get(node.id) ?? { title: node.name }) : node.name; + const descendants = (node: NotesNode) => tree.nodes.filter(other => other.rel === node.rel || other.rel.startsWith(`${node.rel}/`)); + const targetsFor = (node: NotesNode) => { + const inside = new Set(descendants(node).map(other => other.id)); + return tree.nodes.filter(target => canContain(target.kind, node.kind) && target.id !== node.parentId && !inside.has(target.id)); + }; + const commit = async () => { + if (!editing) return; + const value = editing.value.trim(); + const current = editing; + setEditing(null); + if (!value) return; + if (current.kind === "workspace") await actions.createWorkspace(value); + else if (current.kind === "project") await actions.createProject(current.id, value); + else if (current.kind === "folder") await actions.createFolder(current.id, value); + else await actions.rename(current.id, value); + }; + const field = (label: string) => editing && setEditing({ ...editing, value: event.target.value })} + onKeyDown={event => { if (event.key === "Enter") { event.preventDefault(); void commit(); } else if (event.key === "Escape") setEditing(null); }} + onBlur={() => void commit()} />; + const toggle = (id: string) => setCollapsed(current => { const next = new Set(current); if (next.has(id)) next.delete(id); else next.add(id); return next; }); + + const row = (node: NotesNode): ReactNode => { + const name = nameOf(node); + const kids = children(node.id); + const open = !collapsed.has(node.id); + const folderNote = node.kind === "folder" ? node.noteId : null; + const current = (node.kind === "note" && selected === node.id) || (folderNote !== null && selected === folderNote); + const icon = node.kind === "workspace" ? "grid" : node.kind === "project" ? "folder" : node.kind === "folder" ? (open ? "folder-open" : "folder") : node.kind === "file" ? "file" : "page"; + const activate = () => { + if (node.kind === "note") actions.openPage(node.id); + else if (folderNote) actions.openPage(folderNote); + else if (node.kind === "file") void actions.openFile(node.id); + else toggle(node.id); + }; + const renaming = editing?.kind === "rename" && editing.id === node.id; + return
  • +
    + {kids.length > 0 && } + {renaming ? field(`Rename ${name}`) : } + + {(node.kind === "project" || node.kind === "folder") && <> + void actions.createPage(node.id)}>New page + setEditing({ kind: "folder", id: node.id, value: "" })}>New folder + } + {node.kind === "workspace" && setEditing({ kind: "project", id: node.id, value: "" })}>New project} + {node.kind === "file" && void actions.openFile(node.id)}>Open} + {node.kind !== "note" && setEditing({ kind: "rename", id: node.id, value: name })}>Rename} + {node.kind !== "workspace" && targetsFor(node).length > 0 && <> + + Move to + {targetsFor(node).map(target => void actions.move(node.id, target.id)}>{pathName(tree, target, nameOf)})} + } + + void actions.reveal(node.id)}>Reveal in Finder + {(node.kind === "workspace" || node.kind === "project" || node.kind === "folder") && kids.length === 0 && !(node.kind === "workspace" && node.isDefault) && + void actions.remove(node.id)}>Delete {node.kind}} + +
    + {(kids.length > 0 || (editing && editing.kind !== "rename" && editing.kind !== "workspace" && editing.id === node.id)) && open &&
      + {editing && editing.kind !== "rename" && editing.kind !== "workspace" && editing.id === node.id &&
    • {field(editing.kind === "project" ? "New project name" : "New folder name")}
    • } + {kids.map(row)} +
    } +
  • ; + }; + + return
      + {children(null).map(row)} + {editing?.kind === "workspace" &&
    • {field("New workspace name")}
    • } + {tree.truncated &&
    • Showing the first 10,000 items.
    • } +
    ; +} + +/** "Workspace › Project › Folder" for a move target. */ +function pathName(tree: NotesTree, node: NotesNode, nameOf: (node: NotesNode) => string): string { + const parts: string[] = []; + let current: NotesNode | undefined = node; + const seen = new Set(); + while (current && !seen.has(current.id)) { seen.add(current.id); parts.unshift(nameOf(current)); current = tree.nodes.find(other => other.id === current!.parentId); } + return parts.join(" › "); +} + +function NodeMenu({ label, children }: { label: string; children: ReactNode }) { + const [open, setOpen] = useState(false); + const trigger = useRef(null); + return event.stopPropagation()}> + setOpen(value => !value)} /> + setOpen(false)} anchorRef={trigger} label={label} placement="bottom-end" fitViewport> + setOpen(false)}>{children} + + ; +} diff --git a/apps/desktop/src/renderer/space/SpaceView.tsx b/apps/desktop/src/renderer/space/SpaceView.tsx index f6c9c6ec..02eb040b 100644 --- a/apps/desktop/src/renderer/space/SpaceView.tsx +++ b/apps/desktop/src/renderer/space/SpaceView.tsx @@ -14,6 +14,8 @@ import { BlockEditor } from "./BlockEditor"; import { PageComments, type CommentDraft } from "./PageComments"; import { BLOCK_COMMANDS } from "./markdown"; import { useSpace } from "./useSpace"; +import { useNotesTree } from "./useNotesTree"; +import { NotesTreeView, type NotesTreeActions } from "./NotesTree"; import { restartDrafts } from "../restart-drafts"; import "./space.css"; @@ -30,6 +32,8 @@ const TEMPLATES = [ export function SpaceView({ sidebarOpen, active, openPage, onOpenChat, chatOpen = false, onKnowledgeReadyChange }: { onKnowledgeReadyChange?: (ready: boolean) => void; sidebarOpen: boolean; active: boolean; openPage?: { id: string }; onOpenChat?: (prompt?: string) => void; chatOpen?: boolean }) { const space = useSpace(active); + const notes = useNotesTree(active); + const [newWorkspace, setNewWorkspace] = useState(0); const [history, setHistory] = useState(false); const [selected, setSelected] = useState(null); const [view, setView] = useState("pages"); @@ -108,11 +112,12 @@ export function SpaceView({ sidebarOpen, active, openPage, onOpenChat, chatOpen }; const open = (id: string) => { if (selected && selected !== id) void space.settle(selected); if (view === "knowledge") setView("pages"); setSelected(id); setMenu(false); setNotice(null); setQuote(""); setHistory(false); }; useEffect(() => { if (openPage) { setView("pages"); setQuery(""); open(openPage.id); void space.refresh(); } }, [openPage]); - const create = async (title = "", markdown = "", parentId: string | null = null) => { + const create = async (title = "", markdown = "", parentId: string | null = null, containerId?: string) => { if (creating) return; setCreating(true); await run(async () => { - const result = await space.create({ title, markdown, parentId }); + const result = await space.create({ title, markdown, parentId, ...(containerId ? { containerId } : {}) }); + void notes.refresh(); focusCreatedTitle.current = result.id; setView("pages"); setQuery(""); open(result.id); }); @@ -130,6 +135,19 @@ export function SpaceView({ sidebarOpen, active, openPage, onOpenChat, chatOpen useEffect(() => { if (!notice) return; const timer = setTimeout(() => setNotice(null), 3500); return () => clearTimeout(timer); }, [notice]); const selectView = (value: View) => { setView(value); setQuery(""); setSelected(null); }; + const tree = (action: () => Promise) => run(() => notes.act(action)); + const treeActions: NotesTreeActions = { + openPage: id => { setView("pages"); setQuery(""); open(id); }, + createPage: containerId => create("", "", null, containerId), + createFolder: (parentId, name) => tree(() => bridge.invoke("notes:folder:create", { parentId, name })), + createProject: (workspaceId, name) => tree(() => bridge.invoke("notes:project:create", { workspaceId, name })), + createWorkspace: name => tree(() => bridge.invoke("notes:workspace:create", { name })), + rename: (id, name) => tree(async () => { await space.flush(); await bridge.invoke("notes:rename", { id, name }); await space.refresh(); }), + move: (id, targetId) => tree(async () => { await space.flush(); await bridge.invoke("notes:move", { ids: [id], targetId }); await space.refresh(); }), + remove: id => tree(() => bridge.invoke("notes:delete", { id })), + reveal: id => run(() => bridge.invoke("notes:reveal", { id })), + openFile: id => run(() => bridge.invoke("notes:open", { id })), + }; const exportText = (p: SpacePage) => `# ${pageTitle(p)}\n\n${p.markdown}\n`; const download = (p: SpacePage) => void run(async () => { await space.flush(); @@ -155,7 +173,7 @@ export function SpaceView({ sidebarOpen, active, openPage, onOpenChat, chatOpen return
    } {section === "clis" &&
    diff --git a/apps/desktop/src/renderer/components/ui/Icon.tsx b/apps/desktop/src/renderer/components/ui/Icon.tsx index a55b2930..8e54e2b7 100644 --- a/apps/desktop/src/renderer/components/ui/Icon.tsx +++ b/apps/desktop/src/renderer/components/ui/Icon.tsx @@ -20,6 +20,7 @@ const PATHS = { bell: "M3 11h10l-1.5-2V6a3.5 3.5 0 0 0-7 0v3zM6.5 13h3", minus: "M4 8h8", space: "M5 2h7a1 1 0 0 1 1 1v8M3 4h6a1 1 0 0 1 1 1v8a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1zM4.5 7h3M4.5 9.5h2", + analytics: "M2.5 13.5h11M4.5 11V8M8 11V4.5M11.5 11V6.5", star: "M8 1.8l1.85 3.75 4.15.6-3 2.93.71 4.13L8 11.26l-3.71 1.95L5 9.08 2 6.15l4.15-.6z", trash: "M2.5 4h11M6 4V2.5h4V4M4 4l.5 9.5h7L12 4M6.5 6.5v4.5M9.5 6.5v4.5", archive: "M2.5 3h11v3h-11zM3.5 6v7h9V6M6.5 8.5h3", diff --git a/apps/desktop/src/renderer/space/NotesTree.tsx b/apps/desktop/src/renderer/space/NotesTree.tsx index 8b318a7d..d221022d 100644 --- a/apps/desktop/src/renderer/space/NotesTree.tsx +++ b/apps/desktop/src/renderer/space/NotesTree.tsx @@ -55,6 +55,11 @@ export function NotesTreeView({ tree, pages, selected, actions, newWorkspace }: onBlur={() => void commit()} />; const toggle = (id: string) => setCollapsed(current => { const next = new Set(current); if (next.has(id)) next.delete(id); else next.add(id); return next; }); + const startCreate = (kind: "folder" | "project", id: string) => { + setCollapsed(current => { const next = new Set(current); next.delete(id); return next; }); + setEditing({ kind, id, value: "" }); + }; + const row = (node: NotesNode): ReactNode => { const name = nameOf(node); const kids = children(node.id); @@ -78,9 +83,9 @@ export function NotesTreeView({ tree, pages, selected, actions, newWorkspace }: {(node.kind === "project" || node.kind === "folder") && <> void actions.createPage(node.id)}>New page - setEditing({ kind: "folder", id: node.id, value: "" })}>New folder + startCreate("folder", node.id)}>New folder } - {node.kind === "workspace" && setEditing({ kind: "project", id: node.id, value: "" })}>New project} + {node.kind === "workspace" && startCreate("project", node.id)}>New project} {node.kind === "file" && void actions.openFile(node.id)}>Open} {node.kind !== "note" && setEditing({ kind: "rename", id: node.id, value: name })}>Rename} {node.kind !== "workspace" && targetsFor(node).length > 0 && <> diff --git a/apps/desktop/src/renderer/styles.css b/apps/desktop/src/renderer/styles.css index 6ee833d5..ef77042d 100644 --- a/apps/desktop/src/renderer/styles.css +++ b/apps/desktop/src/renderer/styles.css @@ -364,6 +364,12 @@ body[data-streamer-mode="true"] ::search-text { color: transparent; background-c .sheet > .main { grid-area: 1 / 2; } /* Keep Home mounted, with direct children for panel layout and workspace full view. */ .sheet[data-surface="space"] > :is(.sidebar, .main, .workspace, .toast) { display: none; } +.sheet[data-surface="analytics"] > :is(.sidebar, .main, .workspace, .toast, .panel-resizer) { display: none; } +/* The dashboard is a native view over the canvas (workspace-analytics.ts); this only reserves its place. */ +.analytics-surface { grid-column: 1 / -1; grid-row: 1; display: flex; flex-direction: column; min-width: 0; min-height: 0; } +.analytics-surface[hidden] { display: none; } +.analytics-canvas { flex: 1; min-height: 0; } +.analytics-note { margin: 0; padding: 10px 16px; color: var(--text-2); font-size: 13px; border-bottom: 1px solid var(--border-pane); } .main { position: relative; display: flex; flex-direction: column; min-width: 0; min-height: 0; overflow: hidden; background: var(--bg-main); background-image: radial-gradient(ellipse 75% 40% at 50% -10%, var(--canvas-sheen), transparent); } .sidebar + .main { border-left: 1px solid var(--border-pane); } diff --git a/apps/desktop/src/renderer/usage/UsageDashboard.tsx b/apps/desktop/src/renderer/usage/UsageDashboard.tsx index 7463719f..3bbd2b20 100644 --- a/apps/desktop/src/renderer/usage/UsageDashboard.tsx +++ b/apps/desktop/src/renderer/usage/UsageDashboard.tsx @@ -1,5 +1,7 @@ import { SecretOption, SecretInput } from "../streamer"; import { + createContext, + useContext, useEffect, useLayoutEffect, useMemo, @@ -32,6 +34,8 @@ const routes = [ { id: "sources", label: "Sources", icon: "database", section: "Manage" }, ] as const; type View = (typeof routes)[number]["id"]; +/** True for the fixture preview; false when Modex shows the usage it recorded on this Mac. */ +const DemoContext = createContext(true); type NavSection = (typeof routes)[number]["section"]; const paths: Record = { chevron: , @@ -162,13 +166,14 @@ function Panel({ ); } function Empty({ clear }: { clear?: () => void }) { + const demo = useContext(DemoContext); return (

    No activity in this view

    -

    Try another tool or date range to explore the sample ledger.

    +

    {demo ? "Try another tool or date range to explore the sample ledger." : "Try another tool or date range."}

    {clear && (
    - Sample workspaceM + {demo ? "Sample workspace" : "This Mac"}M {error && {error}}
    } - + } {!connected &&
    diff --git a/docs/usage-preview.md b/docs/analytics.md similarity index 58% rename from docs/usage-preview.md rename to docs/analytics.md index 064d8cbe..a5e9adb7 100644 --- a/docs/usage-preview.md +++ b/docs/analytics.md @@ -1,6 +1,40 @@ -# Usage dashboard preview +# Analytics -Run from the repository root in your session worktree: +Analytics shows how much model usage your Modex threads spend: tokens, cache reads and writes, and output, by +model, project, thread and account. Open it from the **Analytics** icon in the rail, next to Chat and Space. +**Settings → General → Show Analytics in the rail** hides the icon; the change applies right away. + +## What is recorded + +Each turn that called a model adds one row to `MODEX_HOME/app/usage.jsonl` (file mode 0600, one JSON object per +line). A row holds the time, the tool (`claude-code` or `codex`), the model the thread asked for (`default` when the +CLI chose), the thread id, the project name, the Codex account binding when there is one, and the turn's token +counts. Prompts, files and replies are never recorded. + +- **Counts come from the CLIs' own usage reports**, through the same per-turn meter Auto routing uses + (`backends/usage.ts`). A Claude call is counted once per message id; Codex reports are taken only for the + thread's own turn. Input, cache reads and cache writes are summed over every call in the turn. Output includes + reasoning, as both CLIs report it. +- **Every turn is recorded**, Auto or not, including a stopped turn that already called a model. A turn that never + reached a model adds nothing. +- **Costs are unpriced.** Modex has no price table, so `cost` stays null and the dashboard shows calls as + unpriced rather than free. +- **Recording is best-effort.** A failed write is logged and never changes the turn. Reading skips lines that + don't parse, so a torn last line after a crash costs one row. +- Usage from before this release, from other tools, and from outside Modex is not imported. + +## How it is shown + +The dashboard is its own document in a native view over the Analytics surface, so its styles and the app's never +meet. Main serves it from the built page (`dist/usage-preview`, packaged with the app) on `modex-analytics://app/` +in an in-memory session, with the rows at `usage.json`; every other request from that session is refused, and the +page has no access to the desktop bridge. It refreshes every 15 seconds while visible. Like the knowledge base, the +view hides under dialogs and menus and while Streamer Mode is on. + +## The standalone preview + +The same dashboard runs on its fictional fixture data outside the app, with a **Demo Data** stamp. Run from the +repository root in your session worktree: ```sh pnpm --filter @modex/desktop dev:usage @@ -14,9 +48,8 @@ pnpm --filter @modex/desktop build:usage ``` The output is `apps/desktop/dist/usage-preview/`. The normal desktop build also -builds this entry point, so CI checks the preview bundle. It uses the existing +builds this entry point, so CI checks the bundle. It uses the existing React and Vite dependencies, without the desktop bridge or Electron processes. -It is not included in the packaged desktop app or its navigation yet. ## What works @@ -61,9 +94,8 @@ Dialogs support Escape; focus moves to the heading after a navigation change. assets. Their SIL Open Font License is retained in `usage/public/licenses/OFL.txt`. - The brand mark reuses Modex's existing `BrandMark` component. -Live log collection, account connections, subscription billing, and provider -quotas are not implemented. Before adding collection, validate duplicate Claude -message updates and Codex fork-replay handling against real sanitized records. +Importing other tools' logs, account connections, subscription billing, and provider +quotas are not implemented. ## Validation @@ -71,9 +103,15 @@ message updates and Codex fork-replay handling against real sanitized records. pnpm --filter @modex/desktop typecheck pnpm --filter @modex/desktop build:usage pnpm --filter @modex/desktop build:main -node --test apps/desktop/dist/test/usage-ledger.test.js +node --test apps/desktop/dist/test/usage-ledger.test.js apps/desktop/dist/test/analytics.test.js +pnpm --filter @modex/desktop exec playwright test e2e/analytics.spec.ts e2e/usage.spec.ts ``` +`analytics.test.ts` covers the recorded row's shape, tool mapping and summed input, torn-line and date +filtering, recording for every turn without failing one, and that the analytics origin serves only the built page +and `usage.json` (no traversal, symlinks or other types). `e2e/analytics.spec.ts` opens Analytics from the rail on a +seeded row, checks the live banner without a Demo stamp and no bridge in the page, and hides it from Settings. + The focused tests cover inclusive UTC filtering, token/cost aggregation, missing prices, partial cost labels, CSV escaping, and demo session/account consistency. `e2e/usage.spec.ts` checks keyboard disclosure activation, automatic group reopening, diff --git a/docs/event-journal.md b/docs/event-journal.md index f570886b..571efce2 100644 --- a/docs/event-journal.md +++ b/docs/event-journal.md @@ -53,3 +53,21 @@ These are needed before Phase 0's exit tests are complete: cursor instead of reloading state. - The paired desktop-and-phone sleep test with no gaps or duplicates. - A retention policy. The journal grows without bound while the flag is on. + +## Notes for the resume endpoint + +The journal's current behavior already settles four points: + +- **The cursor excludes what the client has.** A row is written once and never changed: merging + happens only in the pending batch, and `since()` flushes that batch before it reads. So a client + that keeps the highest `seq` it applied and asks for `since(seq)` misses nothing and gets + nothing twice. +- **A snapshot needs a matching cursor.** A client that starts from a full state load takes + `latest()` and the snapshot in one synchronous step, with no `await` between them. An event + emitted after that step has a higher `seq`. An event whose change the snapshot already shows + may still arrive once more, and the next point makes that harmless. +- **Applying an event twice must change nothing.** An `item_update` patch carries whole field + values, so applying it again leaves the item unchanged. An `item` event must be applied as an + upsert by item id. `replayItems` appends because it always starts from an empty transcript. +- **Retention needs a reload answer.** Once old rows are pruned, a cursor below the oldest kept + row must get "reload state" rather than a partial page. diff --git a/docs/status.md b/docs/status.md index 2c1177b2..9d604bfc 100644 --- a/docs/status.md +++ b/docs/status.md @@ -4,7 +4,7 @@ The living map of what has shipped, what is on `main` but unreleased, what is in what is next. Update it in the same PR that changes any of those; a reader should be able to plan the next session from this page alone. Release evidence lives in [`reviews/`](reviews/). -_Last updated 2026-10-13._ +_Last updated 2026-10-15._ ## Shipped @@ -232,7 +232,7 @@ accounts, and coverage views. Collapsible navigation and an oversized Demo Data frame 471 synthetic calls across 11 sources, including GitHub Copilot. Filters, call details, CSV export, and both appearances work against the same fictional workspace; missing costs remain unpriced. This is not yet a desktop navigation entry -or live usage collector. Run and provenance details: [usage preview](usage-preview.md). +or live usage collector. Run and provenance details: [usage preview](analytics.md#the-standalone-preview). **Consistent themes and live agent activity.** The right workspace, review/browser controls, menus, status colors and typography now share Jev/OpenCoven tokens with the chat and sidebar. @@ -548,6 +548,14 @@ v0.0.11 artifacts, including the original CI failures and remaining acceptance l ## On main, unreleased +- **Notes hierarchy recovery.** Folder-title changes reserve names against their + children; restored folders stay separate from newer same-named folders while + retaining attachments. Interrupted restores use the same placement rules, and + migration resumes under already-published parents without overwriting them. + Migration also reserves each folder note’s name before placing its children. + Folder settlement records durable intent so interrupted directory and note + renames finish before a read derives the hierarchy. + - **Delete selected Space text.** Backspace/Delete now removes a safely mapped selection in rendered page text and places the editing caret at the deletion. Plain paragraphs use DOM offsets so repeated words and spaces delete the exact @@ -579,6 +587,12 @@ v0.0.11 artifacts, including the original CI failures and remaining acceptance l thread event in `app/events.sqlite` (`node:sqlite`) with a durable cursor. It writes alongside the state files, which stay authoritative. A real session replays from the journal to its exact saved transcript. The resume endpoint and retention come next. [Event journal](event-journal.md). +- **Analytics in the rail.** The rail's Analytics icon opens the usage dashboard on what this Mac + actually used. Each turn that calls a model, Auto or not, records its tokens, cache reads and + writes, and output in `app/usage.jsonl`, by model, project, thread and account. Prompts, files + and replies are never recorded, and costs stay unpriced. The dashboard is its own document in a + native view served from `modex-analytics://`, without the desktop bridge; Settings → General can + hide the icon. The standalone preview keeps its Demo Data. [Analytics](analytics.md). - **Thread archiving on Mac and iPhone.** A thread can be put away from the Mac (sidebar row menu, title bar ⋯ menu) or the phone (hold a thread, or the transcript's ⋯ menu). Archived threads leave the working list: the Mac keeps them under **Archived (n)** per project, where @@ -588,6 +602,18 @@ v0.0.11 artifacts, including the original CI failures and remaining acceptance l adds `POST /v1/threads/:id/archive` and an `archived` flag on snapshot threads; an older Mac answers the phone with 501. Companion build 6 does not include the phone side; it ships with the next iPhone build. +- **One CI run per PR push.** `CI` runs on `push` only for `main`; every other branch is tested by + its pull request's run, which reports the required `unit + e2e (macOS)` check. Before, each + push to a PR branch queued two identical macOS runs, and on 2026-10-15 about 30 runs waited + for 2–3 hosted macOS runners. A branch pushed without a PR gets no CI until one is opened. + +- **Fable falls back to Opus when out of usage credits.** When Claude Code refuses Fable for + usage credits before anything ran, Modex reruns the turn on Opus in the same session, posts + a warning that says so, and starts Fable turns on Opus for the next hour. A refusal after a + reply, tool or reasoning keeps its failure card, so no work runs twice. The CLI's synthetic + refusal reply no longer shows as an assistant bubble, and the card now reads "out of usage + credits" instead of "unknown". Empty fallback replies retain a Retry card, and Auto + records the model that actually ran without learning a user override. Settings → General turns the fallback off; it is on by default. - **Notes are Markdown files** (first slice of notes in folders). Space pages now live under `MODEX_HOME/notes/` as one Markdown file per page, in Personal › Notes; a page with child pages is a folder holding a note of the same name. Ids, revisions, history, trash, comments and the @@ -598,7 +624,10 @@ v0.0.11 artifacts, including the original CI failures and remaining acceptance l - **Workspaces, projects and folders in Space.** Space's sidebar shows the notes folder as Workspace › Project › Folder › pages and files. Create a workspace from Space options, and a project, folder or page from a row's menu; rename, move (Move to…), reveal in Finder, and delete - what is empty. Each is a real folder on disk; a file opens in its default app. Tying each Modex + what is empty. Folder moves reserve names against their children and replay interrupted folder-note + renames without overwriting intervening external edits; default page creation follows renamed or + moved default containers even if their index write was interrupted. Creating a project or + folder expands its container to show the editor. Each is a real folder on disk; a file opens in its default app. Tying each Modex project to its own notes, and file import, come next. ## In flight