@nuasite/notes 0.22.2 → 0.23.0

package/src/overlay/types.ts

@@ -8,7 +8,9 @@
  */
 
 export type NoteType = 'comment' | 'suggestion'
-export type NoteStatus = 'open' | 'resolved' | 'applied' | 'rejected' | 'stale'
+export type NoteStatus = 'open' | 'resolved' | 'applied' | 'rejected' | 'stale' | 'deleted'
+export type NoteRole = 'agency' | 'client'
+export type NoteHistoryAction = 'created' | 'updated' | 'resolved' | 'reopened' | 'applied' | 'deleted' | 'purged' | 'stale'
 
 export interface NoteRange {
 	anchorText: string
@@ -24,6 +26,13 @@ export interface NoteReply {
 	createdAt: string
 }
 
+export interface NoteHistoryEntry {
+	at: string
+	action: NoteHistoryAction
+	role?: NoteRole
+	note?: string
+}
+
 export interface NoteItem {
 	id: string
 	type: NoteType
@@ -38,6 +47,7 @@ export interface NoteItem {
 	updatedAt?: string
 	status: NoteStatus
 	replies: NoteReply[]
+	history: NoteHistoryEntry[]
 }
 
 export interface NotesPageFile {

package/src/storage/json-store.ts

@@ -16,7 +16,7 @@ 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'
+import type { NoteHistoryAction, NoteHistoryEntry, NoteItem, NoteItemPatch, NoteRole, NotesPageFile } from './types'
 
 const FILE_VERSION_HEADER = '// @nuasite/notes v1\n'
 
@@ -77,11 +77,20 @@ export class NotesJsonStore {
 			// 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
+			// Normalize legacy / partial files: items predating the history
+			// field get an empty array, items predating replies get an empty
+			// array. Everything else passes through untouched.
+			const items = Array.isArray(parsed.items)
+				? parsed.items.map((it) => ({
+					...it,
+					replies: Array.isArray(it.replies) ? it.replies : [],
+					history: Array.isArray((it as Partial<NoteItem>).history) ? (it as NoteItem).history : [],
+				}))
+				: []
 			return {
 				page: parsed.page ?? normalized,
 				lastUpdated: parsed.lastUpdated ?? nowIso(),
-				items: Array.isArray(parsed.items) ? parsed.items : [],
+				items,
 			}
 		} catch (err) {
 			if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
@@ -104,16 +113,19 @@ export class NotesJsonStore {
 	/** Add a new item. Generates the id, createdAt, and defaults status to "open". */
 	async addItem(
 		page: string,
-		input: Omit<NoteItem, 'id' | 'createdAt' | 'status' | 'replies'> & {
+		input: Omit<NoteItem, 'id' | 'createdAt' | 'status' | 'replies' | 'history'> & {
 			id?: string
 			createdAt?: string
 			status?: NoteItem['status']
 			replies?: NoteItem['replies']
+			history?: NoteItem['history']
 		},
+		role: NoteRole = 'client',
 	): Promise<NoteItem> {
 		const normalized = normalizePagePath(page)
 		return withLock(normalized, async () => {
 			const file = await this.readPage(normalized)
+			const now = input.createdAt ?? nowIso()
 			const item: NoteItem = {
 				id: input.id ?? generateNoteId(),
 				type: input.type,
@@ -124,9 +136,10 @@ export class NotesJsonStore {
 				range: input.range ?? null,
 				body: input.body,
 				author: input.author,
-				createdAt: input.createdAt ?? nowIso(),
+				createdAt: now,
 				status: input.status ?? 'open',
 				replies: input.replies ?? [],
+				history: input.history ?? [{ at: now, action: 'created', role }],
 			}
 			file.items.push(item)
 			file.page = normalized
@@ -136,34 +149,65 @@ export class NotesJsonStore {
 		})
 	}
 
-	/** Patch an existing item. Returns the updated item, or null if not found. */
-	async updateItem(page: string, id: string, patch: NoteItemPatch): Promise<NoteItem | null> {
+	/**
+	 * Patch an existing item. Returns the updated item, or null if not found.
+	 *
+	 * `historyAction` is appended to the item's audit trail. Default is
+	 * `'updated'`; status-changing helpers (`setStatus`) supply more specific
+	 * actions like `'resolved'` or `'applied'`.
+	 */
+	async updateItem(
+		page: string,
+		id: string,
+		patch: NoteItemPatch,
+		role: NoteRole = 'client',
+		historyAction: NoteHistoryAction = 'updated',
+		historyNote?: string,
+	): 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)
+			const idx = file.items.findIndex((it) => it.id === id)
 			if (idx === -1) return null
 			const existing = file.items[idx]!
+			const now = nowIso()
+			const entry: NoteHistoryEntry = { at: now, action: historyAction, role }
+			if (historyNote) entry.note = historyNote
 			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(),
+				updatedAt: now,
+				history: [...existing.history, entry],
 			}
 			file.items[idx] = updated
-			file.lastUpdated = nowIso()
+			file.lastUpdated = now
 			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> {
+	/**
+	 * Soft-delete an item — flip its status to `'deleted'` and append a
+	 * history entry. The item stays in the JSON file so the agency can
+	 * always see what happened. Returns the updated item, or null if not
+	 * found. Use `purgeItem` to hard-remove.
+	 */
+	async deleteItem(page: string, id: string, role: NoteRole = 'client'): Promise<NoteItem | null> {
+		return this.updateItem(page, id, { status: 'deleted' }, role, 'deleted')
+	}
+
+	/**
+	 * Hard-remove an item from the file. The agency uses this on items that
+	 * have already been soft-deleted (or that they explicitly want gone).
+	 * Returns true if the item existed.
+	 */
+	async purgeItem(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)
+			const idx = file.items.findIndex((it) => it.id === id)
 			if (idx === -1) return false
 			file.items.splice(idx, 1)
 			file.lastUpdated = nowIso()

package/src/storage/types.ts

@@ -10,14 +10,56 @@
  */
 
 /**
- * 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).
+ * Item lifecycle. Notes start as `open`. The agency moves them through the
+ * other states.
+ *
+ *   - `open`     — created, not yet acted on
+ *   - `resolved` — agency marked it handled (no source change)
+ *   - `applied`  — suggestion was written back to the source file
+ *   - `rejected` — agency declined the suggestion
+ *   - `stale`    — anchor text drifted; the suggestion can no longer be applied
+ *   - `deleted`  — soft-deleted by the agency. Items in this state stay on
+ *                  disk so the audit trail is preserved; the client UI hides
+ *                  them and the agency UI shows them in a collapsed section.
+ *                  A subsequent `purge` call hard-removes the file entry.
  */
-export type NoteStatus = 'open' | 'resolved' | 'applied' | 'rejected' | 'stale'
+export type NoteStatus = 'open' | 'resolved' | 'applied' | 'rejected' | 'stale' | 'deleted'
 
 export type NoteType = 'comment' | 'suggestion'
 
+/**
+ * Permission roles. Drives both UI affordances and server-side gating:
+ *
+ *   - `client` — the reviewer (default). Can create comments and suggestions
+ *                and nothing else. Cannot resolve, apply, delete, or purge.
+ *                Cannot see deleted items.
+ *   - `agency` — the agency owner. Full controls. The role is identified by
+ *                the `?nua-agency` URL flag (which sets a sticky cookie) and
+ *                a matching `x-nua-role: agency` header on every API call.
+ *
+ * v0.2 ships role enforcement on a per-instance trust basis: the role flag
+ * is unauthenticated and anyone who knows the URL can become "agency".
+ * That's intentional for v0.2 — the surface is dev-only and the threat model
+ * is "stop a non-technical client from accidentally clicking Apply", not
+ * "harden against an adversary". A real auth handshake can come later.
+ */
+export type NoteRole = 'agency' | 'client'
+
+/**
+ * One entry in an item's audit trail. Every mutation appends one of these
+ * to `item.history` so the agency can always see what happened to an item,
+ * even after a soft delete.
+ */
+export type NoteHistoryAction = 'created' | 'updated' | 'resolved' | 'reopened' | 'applied' | 'deleted' | 'purged' | 'stale'
+
+export interface NoteHistoryEntry {
+	at: string
+	action: NoteHistoryAction
+	role?: NoteRole
+	/** Optional one-line note for context. Currently used by 'applied' to record file path. */
+	note?: string
+}
+
 /**
  * Range payload for `type: "suggestion"` items.
  *
@@ -73,6 +115,14 @@ export interface NoteItem {
 
 	status: NoteStatus
 	replies: NoteReply[]
+
+	/**
+	 * Audit trail of every mutation that has touched this item, in
+	 * chronological order. Always contains at least one entry (`created`).
+	 * Items predating this field get an empty array on read; the create
+	 * timestamp is preserved separately on `createdAt`.
+	 */
+	history: NoteHistoryEntry[]
 }
 
 /**

package/src/types.ts

@@ -39,6 +39,17 @@ export interface NuaNotesOptions {
 	 */
 	urlFlag?: string
 
+	/**
+	 * URL query flag that activates agency mode. When set on a URL it grants
+	 * agency permissions (Apply, Resolve, Delete, Purge) and persists a sticky
+	 * cookie so subsequent navigation stays in agency mode without re-typing.
+	 * Without this flag — and without the cookie — the overlay runs in client
+	 * mode and the destructive actions are hidden.
+	 *
+	 * Default: `nua-agency`
+	 */
+	agencyFlag?: string
+
 	/**
 	 * Forward `/_nua/notes/*` requests through this proxy target. Mirrors the
 	 * pattern used by `@nuasite/cms` for sandbox/hosted dev. The target backend