@nuasite/notes 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nuasite/notes",
+  "description": "Astro integration adding a Pastel-style comment + Google Docs-style suggestion overlay alongside @nuasite/cms.",
+  "files": [
+    "dist/**",
+    "src/**",
+    "README.md",
+    "package.json"
+  ],
+  "homepage": "https://github.com/nuasite/nuasite/blob/main/packages/notes/README.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuasite/nuasite.git",
+    "directory": "packages/notes"
+  },
+  "license": "Apache-2.0",
+  "version": "0.1.0",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "astro": "6.1.4",
+    "preact": "^10.29.1"
+  },
+  "peerDependencies": {
+    "astro": "6.1.4",
+    "typescript": "^6.0.2"
+  },
+  "scripts": {
+    "build": "vite build --config vite.config.overlay.ts",
+    "prepack": "bun run build && bun run ../../scripts/workspace-deps/resolve-deps.ts"
+  },
+  "keywords": [
+    "astro",
+    "cms",
+    "devtools",
+    "nuasite",
+    "review",
+    "comments",
+    "suggestions"
+  ]
+}

package/src/apply/apply-suggestion.ts

@@ -0,0 +1,157 @@
+/**
+ * Apply a suggestion's text replacement back to the source file.
+ *
+ * Each suggestion item already carries the source location it was created
+ * against (`targetSourcePath`, `targetSourceLine`) — both populated from the
+ * `@nuasite/cms` per-page manifest at create time. That gives us everything
+ * we need to perform the apply locally without peer-importing CMS internals:
+ *
+ *   1. Read the source file at `targetSourcePath`.
+ *   2. Find `range.originalText` in the file.
+ *      - If it appears exactly once → replace it.
+ *      - If it appears multiple times → use `targetSourceLine` to pick the
+ *        nearest occurrence (within a small window). This handles repeated
+ *        words / boilerplate inside large files.
+ *      - If it doesn't appear → drift detected, return `stale`.
+ *   3. Atomically write the file back (write `.tmp`, rename).
+ *
+ * The Vite watcher inside CMS picks up the file write and triggers HMR,
+ * which reloads the page and shows the applied text. The notes API handler
+ * also fires its own HMR full-reload to be safe.
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { NoteItem } from '../storage/types'
+
+export type ApplyResult =
+	| { ok: true; file: string; before: string; after: string }
+	| { ok: false; reason: 'not-suggestion' | 'missing-source' | 'file-error' | 'not-found' | 'ambiguous'; message: string }
+
+interface ApplyOptions {
+	projectRoot: string
+}
+
+const LINE_WINDOW = 8
+
+function* findAllOccurrences(haystack: string, needle: string): Generator<number> {
+	if (!needle) return
+	let from = 0
+	while (true) {
+		const idx = haystack.indexOf(needle, from)
+		if (idx < 0) return
+		yield idx
+		from = idx + needle.length
+	}
+}
+
+function lineOfOffset(content: string, offset: number): number {
+	let line = 1
+	for (let i = 0; i < offset && i < content.length; i++) {
+		if (content[i] === '\n') line++
+	}
+	return line
+}
+
+/**
+ * Resolve `targetSourcePath` to an absolute path inside the project root.
+ * Defends against path traversal: the resolved path must stay inside the
+ * project root.
+ */
+function resolveSafe(projectRoot: string, sourcePath: string): string | null {
+	const root = path.resolve(projectRoot)
+	const candidate = path.resolve(root, sourcePath)
+	if (!candidate.startsWith(root + path.sep) && candidate !== root) return null
+	return candidate
+}
+
+export async function applySuggestion(item: NoteItem, options: ApplyOptions): Promise<ApplyResult> {
+	if (item.type !== 'suggestion' || !item.range) {
+		return { ok: false, reason: 'not-suggestion', message: 'Only suggestion items can be applied' }
+	}
+	if (!item.targetSourcePath) {
+		return {
+			ok: false,
+			reason: 'missing-source',
+			message: 'Suggestion is missing targetSourcePath. Cannot resolve which file to edit.',
+		}
+	}
+	const abs = resolveSafe(options.projectRoot, item.targetSourcePath)
+	if (!abs) {
+		return { ok: false, reason: 'missing-source', message: `Refusing to write outside project root: ${item.targetSourcePath}` }
+	}
+
+	let content: string
+	try {
+		content = await fs.readFile(abs, 'utf-8')
+	} catch (err) {
+		return {
+			ok: false,
+			reason: 'file-error',
+			message: `Could not read ${item.targetSourcePath}: ${err instanceof Error ? err.message : String(err)}`,
+		}
+	}
+
+	const original = item.range.originalText
+	const replacement = item.range.suggestedText
+	if (!original) {
+		return { ok: false, reason: 'not-found', message: 'Suggestion has empty originalText' }
+	}
+
+	const occurrences = Array.from(findAllOccurrences(content, original))
+	if (occurrences.length === 0) {
+		return {
+			ok: false,
+			reason: 'not-found',
+			message: `Original text not found in ${item.targetSourcePath}. Source may have drifted since the suggestion was made.`,
+		}
+	}
+
+	let chosenOffset: number
+	if (occurrences.length === 1) {
+		chosenOffset = occurrences[0]!
+	} else {
+		// Pick the occurrence closest to targetSourceLine (within a small window).
+		const targetLine = item.targetSourceLine ?? 0
+		let best: { offset: number; dist: number } | null = null
+		for (const off of occurrences) {
+			const ln = lineOfOffset(content, off)
+			const dist = Math.abs(ln - targetLine)
+			if (!best || dist < best.dist) best = { offset: off, dist }
+		}
+		if (!best || best.dist > LINE_WINDOW) {
+			return {
+				ok: false,
+				reason: 'ambiguous',
+				message:
+					`Original text appears ${occurrences.length} times in ${item.targetSourcePath} and none are near targetSourceLine ${targetLine}. Refusing to apply.`,
+			}
+		}
+		chosenOffset = best.offset
+	}
+
+	const before = content.slice(Math.max(0, chosenOffset - 40), chosenOffset + original.length + 40)
+	const newContent = content.slice(0, chosenOffset) + replacement + content.slice(chosenOffset + original.length)
+	const after = newContent.slice(Math.max(0, chosenOffset - 40), chosenOffset + replacement.length + 40)
+
+	// Atomic write — same pattern the JSON store uses.
+	const tmp = `${abs}.${process.pid}.${Date.now()}.tmp`
+	try {
+		await fs.writeFile(tmp, newContent, 'utf-8')
+		await fs.rename(tmp, abs)
+	} catch (err) {
+		// Clean up tmp on failure
+		try {
+			await fs.unlink(tmp)
+		} catch (cleanupErr) {
+			console.warn(`[nuasite-notes] Failed to clean up temp file ${tmp}:`, cleanupErr instanceof Error ? cleanupErr.message : cleanupErr)
+		}
+		return {
+			ok: false,
+			reason: 'file-error',
+			message: `Could not write ${item.targetSourcePath}: ${err instanceof Error ? err.message : String(err)}`,
+		}
+	}
+
+	return { ok: true, file: item.targetSourcePath, before, after }
+}

package/src/dev/api-handlers.ts

@@ -0,0 +1,215 @@
+/**
+ * Dev API route handlers for `/_nua/notes/*`.
+ *
+ * All handlers operate on a single `NotesJsonStore` and follow the same
+ * shape as `@nuasite/cms`'s api-routes: parse query/body, mutate, send JSON.
+ *
+ * Routes (all mounted under `/_nua/notes/`):
+ *
+ *   GET    /list?page=/<page>      → list items for one page
+ *   GET    /inbox                   → list items across all pages (Phase 5 use)
+ *   POST   /create                  → create a comment or suggestion
+ *   POST   /update                  → patch an existing item
+ *   POST   /resolve                 → mark item as resolved
+ *   POST   /reopen                  → reopen a resolved item
+ *   POST   /delete                  → delete an item
+ *   POST   /apply                   → write a suggestion's replacement back to source
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { applySuggestion } from '../apply/apply-suggestion'
+import type { NotesJsonStore } from '../storage/json-store'
+import type { NoteItem, NoteItemPatch, NoteRange, NoteStatus, NoteType } from '../storage/types'
+import { parseJsonBody, sendError, sendJson } from './request-utils'
+
+export interface NotesApiContext {
+	store: NotesJsonStore
+	projectRoot: string
+}
+
+interface CreateBody {
+	page: string
+	type: NoteType
+	targetCmsId: string
+	targetSourcePath?: string
+	targetSourceLine?: number
+	targetSnippet?: string
+	range?: NoteRange | null
+	body: string
+	author: string
+}
+
+interface UpdateBody {
+	page: string
+	id: string
+	patch: NoteItemPatch
+}
+
+interface IdBody {
+	page: string
+	id: string
+}
+
+function getQuery(url: string): URLSearchParams {
+	const q = url.indexOf('?')
+	return new URLSearchParams(q >= 0 ? url.slice(q + 1) : '')
+}
+
+export async function handleNotesApiRoute(
+	route: string,
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: NotesApiContext,
+): Promise<void> {
+	const { store } = ctx
+	const method = req.method ?? 'GET'
+
+	// GET /list?page=/some-page
+	if (method === 'GET' && route === 'list') {
+		const params = getQuery(req.url ?? '')
+		const page = params.get('page')
+		if (!page) {
+			sendError(res, 'Missing required query param: page', 400, req)
+			return
+		}
+		const file = await store.readPage(page)
+		sendJson(res, file, 200, req)
+		return
+	}
+
+	// GET /inbox — all items across all pages
+	if (method === 'GET' && route === 'inbox') {
+		const pages = await store.listAllPages()
+		sendJson(res, { pages }, 200, req)
+		return
+	}
+
+	// POST /create
+	if (method === 'POST' && route === 'create') {
+		const body = await parseJsonBody<CreateBody>(req)
+		if (!body.page || !body.type || !body.targetCmsId || !body.author) {
+			sendError(res, 'Missing required fields: page, type, targetCmsId, author', 400, req)
+			return
+		}
+		if (body.type !== 'comment' && body.type !== 'suggestion') {
+			sendError(res, `Invalid type: ${body.type}`, 400, req)
+			return
+		}
+		if (body.type === 'suggestion' && !body.range) {
+			sendError(res, 'Suggestion items require a range payload', 400, req)
+			return
+		}
+		// Comments must have a body; suggestions may have an empty body since
+		// the diff itself communicates the change.
+		if (body.type === 'comment' && !body.body?.trim()) {
+			sendError(res, 'Comment items require a non-empty body', 400, req)
+			return
+		}
+		const item = await store.addItem(body.page, {
+			type: body.type,
+			targetCmsId: body.targetCmsId,
+			targetSourcePath: body.targetSourcePath,
+			targetSourceLine: body.targetSourceLine,
+			targetSnippet: body.targetSnippet,
+			range: body.range ?? null,
+			body: body.body ?? '',
+			author: body.author,
+		})
+		sendJson(res, { item }, 201, req)
+		return
+	}
+
+	// POST /update
+	if (method === 'POST' && route === 'update') {
+		const body = await parseJsonBody<UpdateBody>(req)
+		if (!body.page || !body.id || !body.patch) {
+			sendError(res, 'Missing required fields: page, id, patch', 400, req)
+			return
+		}
+		const updated = await store.updateItem(body.page, body.id, body.patch)
+		if (!updated) {
+			sendError(res, `Item not found: ${body.id}`, 404, req)
+			return
+		}
+		sendJson(res, { item: updated }, 200, req)
+		return
+	}
+
+	// POST /resolve and POST /reopen — convenience wrappers around update
+	if (method === 'POST' && (route === 'resolve' || route === 'reopen')) {
+		const body = await parseJsonBody<IdBody>(req)
+		if (!body.page || !body.id) {
+			sendError(res, 'Missing required fields: page, id', 400, req)
+			return
+		}
+		const status: NoteStatus = route === 'resolve' ? 'resolved' : 'open'
+		const updated = await store.updateItem(body.page, body.id, { status })
+		if (!updated) {
+			sendError(res, `Item not found: ${body.id}`, 404, req)
+			return
+		}
+		sendJson(res, { item: updated }, 200, req)
+		return
+	}
+
+	// POST /delete
+	if (method === 'POST' && route === 'delete') {
+		const body = await parseJsonBody<IdBody>(req)
+		if (!body.page || !body.id) {
+			sendError(res, 'Missing required fields: page, id', 400, req)
+			return
+		}
+		const ok = await store.deleteItem(body.page, body.id)
+		if (!ok) {
+			sendError(res, `Item not found: ${body.id}`, 404, req)
+			return
+		}
+		sendJson(res, { ok: true }, 200, req)
+		return
+	}
+
+	// POST /apply — write the suggestion's replacement back to the source file
+	if (method === 'POST' && route === 'apply') {
+		const body = await parseJsonBody<IdBody>(req)
+		if (!body.page || !body.id) {
+			sendError(res, 'Missing required fields: page, id', 400, req)
+			return
+		}
+		const file = await store.readPage(body.page)
+		const item = file.items.find(it => it.id === body.id)
+		if (!item) {
+			sendError(res, `Item not found: ${body.id}`, 404, req)
+			return
+		}
+		if (item.type !== 'suggestion' || !item.range) {
+			sendError(res, 'Only suggestion items can be applied', 400, req)
+			return
+		}
+
+		const result = await applySuggestion(item, { projectRoot: ctx.projectRoot })
+
+		if (!result.ok) {
+			// Drift detected — mark the item as stale so the sidebar can warn
+			// the agency without losing the suggestion.
+			if (result.reason === 'not-found' || result.reason === 'ambiguous') {
+				const updated = await store.updateItem(body.page, body.id, { status: 'stale' })
+				sendJson(res, { item: updated, error: result.message, reason: result.reason }, 409, req)
+				return
+			}
+			sendError(res, result.message, 400, req)
+			return
+		}
+
+		// Successful write — flip the item to `applied`. The middleware will
+		// fire a Vite full-reload after this returns; CMS's own watcher also
+		// notices the source-file change and triggers HMR.
+		const updated = await store.updateItem(body.page, body.id, { status: 'applied' })
+		sendJson(res, { item: updated, file: result.file, before: result.before, after: result.after }, 200, req)
+		return
+	}
+
+	sendError(res, `Unknown notes route: ${method} ${route}`, 404, req)
+}
+
+// Re-export for tests / external use
+export type { NoteItem }

package/src/dev/middleware.ts

@@ -0,0 +1,65 @@
+/**
+ * Vite dev middleware mounting `/_nua/notes/*`.
+ *
+ * Mirrors the structure of `@nuasite/cms`'s `createDevMiddleware`:
+ *   - Filters by URL prefix and short-circuits other requests
+ *   - Handles CORS preflight before dispatching
+ *   - Catches handler errors and surfaces them as 500 JSON responses
+ *   - Triggers a Vite HMR full-reload after content-modifying POSTs so
+ *     pages currently open in a browser reflect the new note immediately
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { NotesJsonStore } from '../storage/json-store'
+import type { NotesApiContext } from './api-handlers'
+import { handleNotesApiRoute } from './api-handlers'
+import { handleCors, sendError } from './request-utils'
+
+/** Minimal ViteDevServer interface — same shape used by `@nuasite/cms`. */
+export interface ViteDevServerLike {
+	middlewares: {
+		use: (middleware: (req: IncomingMessage, res: ServerResponse, next: () => void) => void) => void
+	}
+	ws?: {
+		send: (payload: { type: string; path?: string }) => void
+	}
+}
+
+const ROUTE_PREFIX = '/_nua/notes/'
+
+export function createNotesDevMiddleware(
+	server: ViteDevServerLike,
+	store: NotesJsonStore,
+	projectRoot: string,
+): void {
+	const ctx: NotesApiContext = { store, projectRoot }
+
+	server.middlewares.use((req, res, next) => {
+		const url = req.url ?? ''
+		if (!url.startsWith(ROUTE_PREFIX)) {
+			next()
+			return
+		}
+
+		if (handleCors(req, res)) return
+
+		const route = url.replace(ROUTE_PREFIX, '').split('?')[0] ?? ''
+
+		handleNotesApiRoute(route, req, res, ctx)
+			.then(() => {
+				// Mirror CMS: explicitly trigger full-reload after content-modifying
+				// routes. In sandboxed dev environments (E2B etc.) chokidar events
+				// may not fire reliably for note JSON files, so we send the HMR
+				// event directly. The overlay re-fetches `/list` on reload.
+				if (req.method === 'POST' && server.ws) {
+					server.ws.send({ type: 'full-reload' })
+				}
+			})
+			.catch((error) => {
+				console.error('[nuasite-notes] API error:', error)
+				if (!res.headersSent) {
+					sendError(res, error instanceof Error ? error.message : 'Internal server error', 500, req)
+				}
+			})
+	})
+}

package/src/dev/request-utils.ts

@@ -0,0 +1,71 @@
+/**
+ * Tiny HTTP helpers for the notes dev API. Mirrors `@nuasite/cms`'s
+ * `handlers/request-utils.ts` but kept local so notes has no runtime
+ * dependency on CMS internals (only on the published source-finder
+ * surface, used in Phase 4).
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+const MAX_BODY_SIZE = 2 * 1024 * 1024 // 2 MB — notes are text, no uploads
+
+export function readBody(req: IncomingMessage, maxSize: number = MAX_BODY_SIZE): Promise<Buffer> {
+	return new Promise((resolve, reject) => {
+		const chunks: Buffer[] = []
+		let totalSize = 0
+		req.on('data', (chunk: Buffer) => {
+			totalSize += chunk.length
+			if (totalSize > maxSize) {
+				req.destroy()
+				reject(new Error(`Request body exceeds maximum size of ${maxSize} bytes`))
+				return
+			}
+			chunks.push(chunk)
+		})
+		req.on('end', () => resolve(Buffer.concat(chunks)))
+		req.on('error', reject)
+	})
+}
+
+export async function parseJsonBody<T>(req: IncomingMessage): Promise<T> {
+	const buf = await readBody(req)
+	if (buf.length === 0) return {} as T
+	try {
+		return JSON.parse(buf.toString('utf-8')) as T
+	} catch {
+		throw new Error('Invalid JSON in request body')
+	}
+}
+
+function getCorsOrigin(req: IncomingMessage): string {
+	return req.headers.origin ?? '*'
+}
+
+export function sendJson(res: ServerResponse, data: unknown, status = 200, req?: IncomingMessage): void {
+	res.writeHead(status, {
+		'Content-Type': 'application/json',
+		'Cache-Control': 'no-store',
+		'Access-Control-Allow-Origin': req ? getCorsOrigin(req) : '*',
+		'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+		'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+	})
+	res.end(JSON.stringify(data))
+}
+
+export function sendError(res: ServerResponse, message: string, status = 400, req?: IncomingMessage): void {
+	sendJson(res, { error: message }, status, req)
+}
+
+export function handleCors(req: IncomingMessage, res: ServerResponse): boolean {
+	if (req.method === 'OPTIONS') {
+		res.writeHead(204, {
+			'Access-Control-Allow-Origin': getCorsOrigin(req),
+			'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+			'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+			'Access-Control-Max-Age': '86400',
+		})
+		res.end()
+		return true
+	}
+	return false
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { default, nuaNotes } from './integration'
+export type { NuaNotesOptions } from './types'