proto-comments 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "proto-comments",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Figma-style review comments on a running React prototype, split by screen even in single-URL apps, stored in a JSON file a coding agent can apply.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "prototype",
+    "comments",
+    "review",
+    "feedback",
+    "annotations",
+    "design",
+    "ai-agent",
+    "claude"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./next": "./server/next.js",
+    "./storage": "./server/storage.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "proto-comments": "bin/proto-comments.js"
+  },
+  "files": [
+    "dist",
+    "server",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "esbuild": "0.24.2"
+  }
+}

package/server/next.js

@@ -0,0 +1,25 @@
+import { createStorage } from './storage.js';
+
+/**
+ * Route handlers for a Next.js App Router route, e.g. app/api/comments/route.js:
+ *
+ *   import { createNextHandlers } from 'proto-comments/next';
+ *   export const dynamic = 'force-dynamic';
+ *   export const { GET, POST, PATCH, DELETE } = createNextHandlers();
+ *
+ * Off outside `next dev` unless `enabled` is set.
+ */
+export function createNextHandlers({ file, enabled = process.env.NODE_ENV === 'development' } = {}) {
+  const storage = createStorage(file);
+  const run = method => async req => {
+    if (!enabled) return new Response('Not found', { status: 404 });
+    /* Same-origin JSON only: a page on another site must not be able to write comments, even with a "simple" request. */
+    const origin = req.headers.get('origin');
+    if (origin && new URL(origin).host !== req.headers.get('host')) return new Response('Forbidden', { status: 403 });
+    if (method !== 'GET' && !(req.headers.get('content-type') || '').startsWith('application/json')) return new Response('Unsupported Media Type', { status: 415 });
+    const body = method === 'GET' ? null : await req.json();
+    const { status, json } = await storage.handle(method, body);
+    return Response.json(json, { status });
+  };
+  return { GET: run('GET'), POST: run('POST'), PATCH: run('PATCH'), DELETE: run('DELETE') };
+}

package/server/storage.js

@@ -0,0 +1,69 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/* Comments live in one JSON file in the project, so a coding agent can read and resolve them directly. */
+export const DEFAULT_FILE = 'comments/comments.json';
+/* Same limit as the comment field in src/ui.jsx. */
+export const MAX_TEXT = 5000;
+
+export function createStorage(file = DEFAULT_FILE) {
+  const abs = path.resolve(process.cwd(), file);
+  /* Writes go one at a time, so two quick requests can't overwrite each other. */
+  let queue = Promise.resolve();
+  const locked = fn => (queue = queue.then(fn, fn));
+
+  async function read() {
+    try { return JSON.parse(await fs.readFile(abs, 'utf8')); } catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+  }
+  async function write(list) {
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, JSON.stringify(list, null, 2) + '\n');
+  }
+  const now = () => new Date().toISOString();
+  /* Numbers count open comments only: resolved ones show a check, so a new comment after them is #1 again. */
+  const nextN = list => Math.max(0, ...list.filter(c => c.status === 'open').map(c => c.n)) + 1;
+
+  /** One entry point for every transport (Next route, standalone server): returns { status, json }. */
+  async function handle(method, body) {
+    if (method === 'GET') return { status: 200, json: await read() };
+    const text = body?.text ?? body?.reply?.text;
+    if (typeof text === 'string' && text.length > MAX_TEXT) return { status: 413, json: { error: `Comment is longer than ${MAX_TEXT} characters` } };
+    return locked(async () => {
+      const list = await read();
+      if (method === 'POST') {
+        const { screen, screenLabel, context, snapshot, anchor, text, author } = body;
+        const n = nextN(list);
+        const c = { id: `c${Date.now().toString(36)}`, n, screen, screenLabel, context, anchor, text, author, status: 'open', queued: false, createdAt: now(), replies: [], snapshot };
+        await write([...list, c]);
+        return { status: 200, json: c };
+      }
+      if (method === 'PATCH') {
+        const { id, ids, queued, status, reply, author } = body;
+        if (ids) {
+          list.forEach(x => { if (ids.includes(x.id)) x.queued = !!queued; });
+          await write(list);
+          return { status: 200, json: list };
+        }
+        const c = list.find(x => x.id === id);
+        if (!c) return { status: 404, json: { error: 'Not found' } };
+        if (status === 'open' && c.status === 'resolved') {
+          /* Reopened: its old number may belong to a newer open comment by now. */
+          if (list.some(x => x.status === 'open' && x.n === c.n)) c.n = nextN(list);
+          delete c.resolvedBy; delete c.resolvedAt;
+        }
+        if (status) c.status = status;
+        if (status === 'resolved') Object.assign(c, { queued: false, resolvedBy: author, resolvedAt: now() });
+        if (reply) c.replies.push({ ...reply, createdAt: now() });
+        await write(list);
+        return { status: 200, json: c };
+      }
+      if (method === 'DELETE') {
+        await write(body.all ? [] : list.filter(x => x.id !== body.id));
+        return { status: 200, json: { ok: true } };
+      }
+      return { status: 405, json: { error: 'Method not allowed' } };
+    });
+  }
+
+  return { file: abs, read, write, handle };
+}