@nuasite/notes 0.1.0

package/src/storage/json-store.ts

@@ -0,0 +1,196 @@
+/**
+ * JSON file store for `@nuasite/notes`.
+ *
+ * One file per page lives at `<notesDir>/pages/<slug>.json`. Reads tolerate a
+ * missing file (returns an empty page). Writes are atomic (write to a `.tmp`
+ * file, then rename) and serialized per slug via an in-memory mutex so
+ * concurrent POSTs don't clobber each other.
+ *
+ * The store is intentionally simple — no caching, no in-memory index, no
+ * background flush. Each request reads the file from disk, mutates, writes
+ * back. This is fine for the local-dev usage profile and matches how
+ * `@nuasite/cms` writes back to source files.
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { generateNoteId } from './id-gen'
+import { normalizePagePath, pageToSlug } from './slug'
+import type { NoteItem, NoteItemPatch, NotesPageFile } from './types'
+
+const FILE_VERSION_HEADER = '// @nuasite/notes v1\n'
+
+function nowIso(): string {
+	return new Date().toISOString()
+}
+
+/**
+ * Per-slug write mutex. Concurrent POSTs to the same page are serialized;
+ * different pages can write in parallel. Cleared after each lock release.
+ */
+const locks = new Map<string, Promise<unknown>>()
+
+async function withLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+	const prev = locks.get(key) ?? Promise.resolve()
+	let release!: () => void
+	const next = new Promise<void>((resolve) => {
+		release = resolve
+	})
+	locks.set(key, prev.then(() => next))
+	try {
+		await prev
+		return await fn()
+	} finally {
+		release()
+		// If we're the tail of the chain, clean up so the map doesn't grow unbounded
+		if (locks.get(key) === prev.then(() => next)) {
+			locks.delete(key)
+		}
+	}
+}
+
+export interface JsonStoreOptions {
+	/** Absolute path to the project root. Required so the store can resolve `notesDir`. */
+	projectRoot: string
+	/** Project-relative directory where note JSON files live. */
+	notesDir: string
+}
+
+export class NotesJsonStore {
+	private readonly pagesDir: string
+
+	constructor(private readonly options: JsonStoreOptions) {
+		this.pagesDir = path.resolve(options.projectRoot, options.notesDir, 'pages')
+	}
+
+	/** Resolve the absolute path of the JSON file for a given page. */
+	private fileFor(page: string): string {
+		return path.join(this.pagesDir, `${pageToSlug(page)}.json`)
+	}
+
+	/** Read a page's notes file from disk, or return an empty page if missing. */
+	async readPage(page: string): Promise<NotesPageFile> {
+		const normalized = normalizePagePath(page)
+		const filePath = this.fileFor(normalized)
+		try {
+			const raw = await fs.readFile(filePath, 'utf-8')
+			// Tolerate the optional version header
+			const stripped = raw.startsWith('//') ? raw.slice(raw.indexOf('\n') + 1) : raw
+			const parsed = JSON.parse(stripped) as NotesPageFile
+			// Normalize legacy / partial files
+			return {
+				page: parsed.page ?? normalized,
+				lastUpdated: parsed.lastUpdated ?? nowIso(),
+				items: Array.isArray(parsed.items) ? parsed.items : [],
+			}
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+				return { page: normalized, lastUpdated: nowIso(), items: [] }
+			}
+			throw err
+		}
+	}
+
+	/** Write a page's notes file to disk atomically. Creates parents as needed. */
+	private async writePageFile(page: string, file: NotesPageFile): Promise<void> {
+		const filePath = this.fileFor(page)
+		await fs.mkdir(path.dirname(filePath), { recursive: true })
+		const body = FILE_VERSION_HEADER + JSON.stringify(file, null, '\t') + '\n'
+		const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`
+		await fs.writeFile(tmp, body, 'utf-8')
+		await fs.rename(tmp, filePath)
+	}
+
+	/** Add a new item. Generates the id, createdAt, and defaults status to "open". */
+	async addItem(
+		page: string,
+		input: Omit<NoteItem, 'id' | 'createdAt' | 'status' | 'replies'> & {
+			id?: string
+			createdAt?: string
+			status?: NoteItem['status']
+			replies?: NoteItem['replies']
+		},
+	): Promise<NoteItem> {
+		const normalized = normalizePagePath(page)
+		return withLock(normalized, async () => {
+			const file = await this.readPage(normalized)
+			const item: NoteItem = {
+				id: input.id ?? generateNoteId(),
+				type: input.type,
+				targetCmsId: input.targetCmsId,
+				targetSourcePath: input.targetSourcePath,
+				targetSourceLine: input.targetSourceLine,
+				targetSnippet: input.targetSnippet,
+				range: input.range ?? null,
+				body: input.body,
+				author: input.author,
+				createdAt: input.createdAt ?? nowIso(),
+				status: input.status ?? 'open',
+				replies: input.replies ?? [],
+			}
+			file.items.push(item)
+			file.page = normalized
+			file.lastUpdated = nowIso()
+			await this.writePageFile(normalized, file)
+			return item
+		})
+	}
+
+	/** Patch an existing item. Returns the updated item, or null if not found. */
+	async updateItem(page: string, id: string, patch: NoteItemPatch): Promise<NoteItem | null> {
+		const normalized = normalizePagePath(page)
+		return withLock(normalized, async () => {
+			const file = await this.readPage(normalized)
+			const idx = file.items.findIndex(it => it.id === id)
+			if (idx === -1) return null
+			const existing = file.items[idx]!
+			const updated: NoteItem = {
+				...existing,
+				...patch,
+				// `range: null` is a meaningful patch (clearing a range), preserve it
+				range: 'range' in patch ? (patch.range ?? null) : existing.range,
+				updatedAt: nowIso(),
+			}
+			file.items[idx] = updated
+			file.lastUpdated = nowIso()
+			await this.writePageFile(normalized, file)
+			return updated
+		})
+	}
+
+	/** Delete an item by id. Returns true if it existed. */
+	async deleteItem(page: string, id: string): Promise<boolean> {
+		const normalized = normalizePagePath(page)
+		return withLock(normalized, async () => {
+			const file = await this.readPage(normalized)
+			const idx = file.items.findIndex(it => it.id === id)
+			if (idx === -1) return false
+			file.items.splice(idx, 1)
+			file.lastUpdated = nowIso()
+			await this.writePageFile(normalized, file)
+			return true
+		})
+	}
+
+	/** List all pages that have at least one note item. Used by the agency inbox (Phase 5). */
+	async listAllPages(): Promise<NotesPageFile[]> {
+		try {
+			const files = await fs.readdir(this.pagesDir)
+			const pages: NotesPageFile[] = []
+			for (const f of files) {
+				if (!f.endsWith('.json')) continue
+				try {
+					const raw = await fs.readFile(path.join(this.pagesDir, f), 'utf-8')
+					const stripped = raw.startsWith('//') ? raw.slice(raw.indexOf('\n') + 1) : raw
+					pages.push(JSON.parse(stripped) as NotesPageFile)
+				} catch (err) {
+					console.warn(`[nuasite-notes] Skipping malformed notes file ${f}:`, err instanceof Error ? err.message : err)
+				}
+			}
+			return pages
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []
+			throw err
+		}
+	}
+}

package/src/storage/slug.ts

@@ -0,0 +1,35 @@
+/**
+ * Slug helpers for mapping page paths to JSON file names.
+ *
+ * The notes overlay anchors items to page paths like `/inspekce-nemovitosti`,
+ * `/blog/post-name`, or `/`. We need a stable filesystem-safe representation
+ * of those paths so the JSON store can write one file per page.
+ *
+ * Rules:
+ *   - Leading slash is stripped.
+ *   - The root page `/` becomes `index`.
+ *   - Trailing slashes are stripped.
+ *   - Path separators become double underscores so nested paths stay readable.
+ *   - Anything outside `[a-z0-9._-]` is replaced with a single dash.
+ */
+
+const SAFE_RE = /[^a-z0-9._-]+/g
+
+export function pageToSlug(page: string): string {
+	const trimmed = page.trim().replace(/^\/+|\/+$/g, '')
+	if (!trimmed) return 'index'
+	return trimmed
+		.toLowerCase()
+		.split('/')
+		.map(seg => seg.replace(SAFE_RE, '-').replace(/^-+|-+$/g, '') || '-')
+		.join('__')
+}
+
+export function normalizePagePath(page: string): string {
+	if (!page) return '/'
+	let p = page.trim()
+	if (!p.startsWith('/')) p = '/' + p
+	// Drop trailing slash except for root
+	if (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1)
+	return p
+}

package/src/storage/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Storage types for `@nuasite/notes`.
+ *
+ * One JSON file per page lives at `<notesDir>/pages/<slug>.json` and contains
+ * a flat list of items. Each item is either an element-level `comment` or a
+ * range-level `suggestion` (Google Docs style strikethrough/insertion diff).
+ *
+ * Both item types share the same target metadata so the sidebar can render
+ * them in a unified list ordered by creation time.
+ */
+
+/**
+ * Item lifecycle. Notes start as `open`. Reviewers (or the agency) move them
+ * through the other states. `applied` is reserved for suggestions that have
+ * been written back to the source file via the apply flow (Phase 4).
+ */
+export type NoteStatus = 'open' | 'resolved' | 'applied' | 'rejected' | 'stale'
+
+export type NoteType = 'comment' | 'suggestion'
+
+/**
+ * Range payload for `type: "suggestion"` items.
+ *
+ * We intentionally store the original substring (`anchorText`) instead of
+ * character offsets so the suggestion can survive small edits to surrounding
+ * text. On load, the overlay walks text nodes inside the target element
+ * looking for `anchorText`. If not found, the suggestion is marked stale.
+ */
+export interface NoteRange {
+	/** Exact substring used as the search anchor when re-attaching on load. */
+	anchorText: string
+	/** Original text the reviewer wants to replace. Usually equal to anchorText for v0.1. */
+	originalText: string
+	/** The reviewer's proposed replacement text. */
+	suggestedText: string
+	/** Optional reasoning the reviewer leaves for the agency. */
+	rationale?: string
+}
+
+export interface NoteReply {
+	id: string
+	author: string
+	body: string
+	createdAt: string
+}
+
+/**
+ * One note item — either an element comment or a range suggestion.
+ *
+ * `targetCmsId` is the anchor: it points at a `data-cms-id` element from the
+ * `@nuasite/cms` manifest, which knows how to map back to file + line + snippet.
+ * The other `target*` fields are denormalized copies of the manifest entry at
+ * the time the note was created so the sidebar has something to render even
+ * if the source file has drifted.
+ */
+export interface NoteItem {
+	id: string
+	type: NoteType
+
+	/** Anchor element from the CMS manifest. */
+	targetCmsId: string
+	targetSourcePath?: string
+	targetSourceLine?: number
+	targetSnippet?: string
+
+	/** Only set when type === 'suggestion'. */
+	range: NoteRange | null
+
+	body: string
+	author: string
+	createdAt: string
+	updatedAt?: string
+
+	status: NoteStatus
+	replies: NoteReply[]
+}
+
+/**
+ * Shape of one `<notesDir>/pages/<slug>.json` file on disk.
+ */
+export interface NotesPageFile {
+	/** Page path the items are anchored to, e.g. `/inspekce-nemovitosti` or `/`. */
+	page: string
+	/** ISO timestamp of the most recent mutation. */
+	lastUpdated: string
+	items: NoteItem[]
+}
+
+/**
+ * Patch payload for `updateItem`. All fields are optional; only the provided
+ * ones are merged onto the existing item.
+ */
+export interface NoteItemPatch {
+	body?: string
+	status?: NoteStatus
+	range?: NoteRange | null
+	targetSnippet?: string
+	targetSourcePath?: string
+	targetSourceLine?: number
+}

package/src/tsconfig.json

@@ -0,0 +1,6 @@
+{
+	"extends": "../tsconfig.settings.json",
+	"compilerOptions": {
+		"outDir": "../dist/types"
+	}
+}

package/src/types.ts

@@ -0,0 +1,50 @@
+/**
+ * Public types for `@nuasite/notes`.
+ *
+ * Phase 0: only the integration options live here. Item types
+ * (`NoteItem`, `NoteRange`, `NoteStatus`) and storage types are added
+ * in Phase 1 alongside the JSON store.
+ */
+
+export interface NuaNotesOptions {
+	/**
+	 * Master switch. Defaults to `true` in dev, ignored in build.
+	 */
+	enabled?: boolean
+
+	/**
+	 * Directory (relative to project root) where note JSON files are stored,
+	 * one file per page at `<notesDir>/pages/<slug>.json`.
+	 *
+	 * Default: `data/notes`
+	 */
+	notesDir?: string
+
+	/**
+	 * Hide the `@nuasite/cms` editor chrome when notes mode is active
+	 * (URL flag `?nua-notes` or cookie `nua-notes-mode=1`).
+	 *
+	 * When `false`, both UIs may render simultaneously and pointer events
+	 * collide. Only set to `false` if you know what you're doing.
+	 *
+	 * Default: `true`
+	 */
+	hideCmsInReviewMode?: boolean
+
+	/**
+	 * URL query flag that activates notes review mode. Reviewers append
+	 * this to any page URL to switch from CMS edit mode to notes review mode.
+	 *
+	 * Default: `nua-notes`
+	 */
+	urlFlag?: string
+
+	/**
+	 * Forward `/_nua/notes/*` requests through this proxy target. Mirrors the
+	 * pattern used by `@nuasite/cms` for sandbox/hosted dev. The target backend
+	 * must implement the matching `/notes/*` endpoints.
+	 *
+	 * Example: `http://localhost:8787`
+	 */
+	proxy?: string
+}