@sov3rain/nota 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# nota
+
+A local annotation tool for AI agent implementation plans.
+
+`nota` opens a Markdown plan in a browser-based editor where you can highlight text and leave comments using [CriticMarkup](https://github.com/CriticMarkup/CriticMarkup-toolkit). The agent reads those comments back and adjusts the plan or implementation accordingly.
+
+## Install
+
+```bash
+npm install -g nota
+```
+
+## Usage
+
+### Annotate a plan
+
+```bash
+nota path/to/plan.md
+```
+
+Opens the file in a local web UI. Highlight any text to leave a comment. When you're done, click **Done** — the agent reads the annotated file and processes your feedback.
+
+Pass `--no-open` to start the server without opening the browser automatically:
+
+```bash
+nota --no-open path/to/plan.md
+```
+
+### Set up agent instructions
+
+```bash
+nota init          # all agents (Claude, Codex, Cursor)
+nota init claude   # Claude only
+nota init codex    # Codex only
+nota init cursor   # Cursor only
+```
+
+Writes the annotation workflow instructions into `CLAUDE.md`, `AGENTS.md`, or `.cursor/rules/nota.mdc`. Safe to re-run — existing files are updated in place, not overwritten.
+
+## How it works
+
+1. The agent creates a plan as `.agent-plans/<date>-<topic>.md` and runs `nota` on it
+2. You annotate the plan in the browser
+3. Feedback is stored as CriticMarkup inline in the file:
+   ```
+   {==highlighted text==}{>>your comment<<}
+   ```
+4. The agent reads the annotations and updates the plan or proceeds with implementation
+
+## License
+
+MIT

package/bin/nota.mjs

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { access, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+const MIME_TYPES = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+};
+
+const args = process.argv.slice(2);
+const command = args[0];
+const wantsHelp = args.includes('--help') || args.includes('-h');
+const shouldOpenBrowser = !args.includes('--no-open');
+const targetFile = args.find((arg) => !arg.startsWith('-'));
+
+if (command === 'init') {
+  if (wantsHelp) {
+    printUsage();
+    process.exit(0);
+  }
+
+  await initAgentInstructions(args[1] ?? 'all');
+  process.exit(0);
+}
+
+if (wantsHelp || !targetFile) {
+  printUsage();
+  process.exit(wantsHelp ? 0 : 1);
+}
+
+const documentPath = resolve(process.cwd(), targetFile);
+const distDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'dist');
+const session = randomBytes(24).toString('hex');
+
+await ensureReadableFile(documentPath);
+await ensureBuildExists(distDir);
+
+const server = createServer((request, response) => {
+  handleRequest(request, response).catch((error) => {
+    console.error(error);
+    sendJson(response, 500, { error: 'Internal server error' });
+  });
+});
+
+server.listen(0, '127.0.0.1', () => {
+  const address = server.address();
+  const port = typeof address === 'object' && address ? address.port : 0;
+  const url = `http://127.0.0.1:${port}/?session=${session}`;
+
+  console.log(`Plan Annotation: ${documentPath}`);
+  console.log(`Open: ${url}`);
+  if (shouldOpenBrowser) {
+    openBrowser(url);
+  }
+});
+
+process.on('SIGINT', () => {
+  server.close(() => process.exit(0));
+});
+
+async function handleRequest(request, response) {
+  const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+  const apiHandler = getApiHandler(url.pathname, request.method);
+
+  if (apiHandler) {
+    await apiHandler(request, response, url);
+    return;
+  }
+
+  await serveStaticFile(url.pathname, response);
+}
+
+async function handleDocumentApi(request, response, url) {
+  if (!isAuthorized(request, url)) {
+    sendJson(response, 403, { error: 'Forbidden' });
+    return;
+  }
+
+  if (request.method === 'GET') {
+    await sendDocument(response);
+    return;
+  }
+
+  if (request.method === 'PUT') {
+    await saveDocument(request, response);
+    return;
+  }
+
+  response.writeHead(405, { Allow: 'GET, PUT' });
+  response.end();
+}
+
+async function serveStaticFile(pathname, response) {
+  const candidate = resolveStaticPath(pathname);
+
+  if (!candidate) {
+    sendForbiddenStaticFile(response);
+    return;
+  }
+
+  const fileStat = await getStaticFileStat(candidate);
+
+  if (!fileStat) {
+    sendNotFound(response);
+    return;
+  }
+
+  response.writeHead(200, {
+    'Content-Type': MIME_TYPES[extname(candidate)] ?? 'application/octet-stream',
+  });
+  createReadStream(candidate).pipe(response);
+}
+
+function getApiHandler(pathname, method) {
+  const route = `${method} ${pathname}`;
+
+  return (
+    {
+      'GET /api/document': handleDocumentApi,
+      'PUT /api/document': handleDocumentApi,
+      'POST /api/shutdown': handleShutdownApi,
+    }[route] ?? null
+  );
+}
+
+function handleShutdownApi(request, response, url) {
+  if (!isAuthorized(request, url)) {
+    sendJson(response, 403, { error: 'Forbidden' });
+    return;
+  }
+
+  sendJson(response, 200, { ok: true });
+  setTimeout(() => process.exit(0), 100);
+}
+
+async function sendDocument(response) {
+  sendJson(response, 200, {
+    filename: documentPath.split(/[\\/]/).pop() ?? 'document.md',
+    markdown: await readFile(documentPath, 'utf8'),
+  });
+}
+
+async function saveDocument(request, response) {
+  const body = await readRequestBody(request);
+  const parsed = JSON.parse(body);
+
+  if (!parsed || typeof parsed.markdown !== 'string') {
+    sendJson(response, 400, { error: 'Expected markdown string' });
+    return;
+  }
+
+  await writeFile(documentPath, parsed.markdown, 'utf8');
+  sendJson(response, 200, { ok: true });
+}
+
+function resolveStaticPath(pathname) {
+  const relativePath = pathname === '/' ? 'index.html' : decodeURIComponent(pathname.slice(1));
+  const candidate = resolve(distDir, relativePath);
+
+  return isInsideDirectory(candidate, distDir) ? candidate : null;
+}
+
+function isInsideDirectory(candidate, directory) {
+  return (
+    candidate === directory ||
+    candidate.startsWith(`${directory}\\`) ||
+    candidate.startsWith(`${directory}/`)
+  );
+}
+
+async function getStaticFileStat(filePath) {
+  try {
+    const fileStat = await stat(filePath);
+    return fileStat.isFile() ? fileStat : null;
+  } catch {
+    return null;
+  }
+}
+
+function sendForbiddenStaticFile(response) {
+  response.writeHead(403);
+  response.end();
+}
+
+function sendNotFound(response) {
+  response.writeHead(404);
+  response.end('Not found');
+}
+
+function isAuthorized(request, url) {
+  return (
+    request.headers['x-nota-session'] === session || url.searchParams.get('session') === session
+  );
+}
+
+function readRequestBody(request) {
+  return new Promise((resolveBody, rejectBody) => {
+    let body = '';
+
+    request.setEncoding('utf8');
+    request.on('data', (chunk) => {
+      body += chunk;
+
+      if (Buffer.byteLength(body, 'utf8') > MAX_BODY_BYTES) {
+        rejectBody(new Error('Request body too large'));
+        request.destroy();
+      }
+    });
+    request.on('end', () => resolveBody(body));
+    request.on('error', rejectBody);
+  });
+}
+
+function sendJson(response, statusCode, payload) {
+  response.writeHead(statusCode, { 'Content-Type': 'application/json; charset=utf-8' });
+  response.end(JSON.stringify(payload));
+}
+
+async function ensureReadableFile(filePath) {
+  try {
+    const fileStat = await stat(filePath);
+    if (!fileStat.isFile()) throw new Error('Not a file');
+    await access(filePath);
+  } catch {
+    console.error(`Cannot read markdown file: ${filePath}`);
+    process.exit(1);
+  }
+}
+
+async function ensureBuildExists(buildDir) {
+  try {
+    await access(join(buildDir, 'index.html'));
+  } catch {
+    console.error('Missing dist/index.html. Run `npm run build` before using the CLI from source.');
+    process.exit(1);
+  }
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  const command = platform === 'win32' ? 'cmd' : platform === 'darwin' ? 'open' : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  const child = spawn(command, args, {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+
+  child.unref();
+}
+
+function printUsage() {
+  console.log(`Usage:
+  nota [--no-open] <path/to/plan.md>
+  nota init [codex|claude|cursor|all]`);
+}
+
+async function initAgentInstructions(target) {
+  const targets = getAgentTargets(target);
+
+  if (!targets) {
+    console.error('Unknown agent target. Expected codex, claude, cursor, or all.');
+    process.exit(1);
+  }
+
+  await mkdir(resolve(process.cwd(), '.agent-plans'), { recursive: true });
+  await writeFile(resolve(process.cwd(), '.agent-plans', '.gitkeep'), '', { flag: 'a' });
+
+  for (const agent of targets) {
+    await writeAgentInstructions(agent);
+  }
+
+  console.log(`Plan Annotation instructions installed for: ${targets.join(', ')}`);
+  console.log('Plans directory ready: .agent-plans/');
+}
+
+function getAgentTargets(target) {
+  const allTargets = ['codex', 'claude', 'cursor'];
+
+  if (target === 'all') return allTargets;
+  if (allTargets.includes(target)) return [target];
+
+  return null;
+}
+
+async function writeAgentInstructions(agent) {
+  const filePath = resolve(process.cwd(), getAgentInstructionPath(agent));
+  const block = getAgentInstructionBlock(agent);
+
+  await mkdir(dirname(filePath), { recursive: true });
+  await upsertMarkedBlock(filePath, block);
+  console.log(`Updated ${filePath}`);
+}
+
+function getAgentInstructionPath(agent) {
+  if (agent === 'codex') return 'AGENTS.md';
+  if (agent === 'claude') return 'CLAUDE.md';
+
+  return join('.cursor', 'rules', 'nota.mdc');
+}
+
+function getAgentInstructionBlock() {
+  return `<!-- nota:start -->
+## Plan Annotation Workflow
+
+When the user asks for an implementation plan, create a Markdown file in:
+
+\`\`\`text
+.agent-plans/<date>-<topic>.md
+\`\`\`
+
+Then launch the local annotation tool.
+
+On Windows/PowerShell, use the npm \`.cmd\` shim explicitly:
+
+\`\`\`powershell
+nota.cmd .agent-plans/<file>.md
+\`\`\`
+
+Do not use \`Start-Process -FilePath nota\` on Windows/PowerShell; it can resolve to the extensionless npm shim and trigger the Windows "open with" dialog instead of running the CLI.
+
+On macOS/Linux:
+
+\`\`\`bash
+nota .agent-plans/<file>.md
+\`\`\`
+
+Tell the user that the plan is open for annotation. Do not continue with implementation until the user says they are done annotating.
+
+After the user is done, read the same Markdown file again. User feedback is stored as CriticMarkup:
+
+\`\`\`md
+{==text being discussed==}{>>user comment<<}
+\`\`\`
+
+Treat those comments as direct user feedback. Update the plan or implementation accordingly.
+
+Once all annotations have been processed, remove every CriticMarkup annotation from the file, as well as the global annotations block if present:
+
+\`\`\`md
+<!-- nota:globals
+[...]
+-->
+\`\`\`
+
+Leave only the plain Markdown content.
+
+If the \`nota\` command is unavailable, tell the user to install it globally:
+
+\`\`\`bash
+npm install -g nota
+\`\`\`
+<!-- nota:end -->
+`;
+}
+
+async function upsertMarkedBlock(filePath, block) {
+  const startMarker = '<!-- nota:start -->';
+  const endMarker = '<!-- nota:end -->';
+  const existing = await readOptionalFile(filePath);
+  const start = existing.indexOf(startMarker);
+  const end = existing.indexOf(endMarker);
+
+  if (start !== -1 && end !== -1 && end > start) {
+    const before = existing.slice(0, start).trimEnd();
+    const after = existing.slice(end + endMarker.length).trimStart();
+    await writeFile(filePath, joinTextBlocks(before, block.trimEnd(), after), 'utf8');
+    return;
+  }
+
+  await writeFile(filePath, joinTextBlocks(existing.trimEnd(), block.trimEnd()), 'utf8');
+}
+
+async function readOptionalFile(filePath) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function joinTextBlocks(...blocks) {
+  return `${blocks.filter(Boolean).join('\n\n')}\n`;
+}

package/dist/assets/index-47nROFLI.css

@@ -0,0 +1 @@
+:root{color:#18202f;font-synthesis:none;text-rendering:optimizelegibility;background:#f4f6f8;font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif}*{box-sizing:border-box}body{min-width:320px;height:100vh;margin:0;overflow:hidden}button{color:#18202f;cursor:pointer;font:inherit;background:#fff;border:1px solid #c6ccd6;border-radius:6px;min-height:38px;padding:0 14px;font-weight:650}button:hover:not(:disabled){border-color:#7a8799}button:disabled{cursor:not-allowed;opacity:.55}button.primary{color:#fff;background:#215f88;border-color:#215f88}button.done{color:#fff;background:#1a6b3c;border-color:#1a6b3c}button.done:hover:not(:disabled){background:#145230;border-color:#145230}.app-shell{flex-direction:column;height:100vh;display:flex;overflow:hidden}.topbar{background:#fff;border-bottom:1px solid #d9dee7;justify-content:space-between;align-items:center;gap:24px;padding:18px 24px;display:flex}.eyebrow{color:#647084;text-transform:uppercase;margin:0 0 4px;font-size:12px;font-weight:750}h1,h2{margin:0}h1{font-size:24px}h2{font-size:16px}.file-actions{align-items:center;gap:10px;display:flex}.copy-plan-button{min-width:132px}.hidden-input{display:none}.save-status{color:#647084;white-space:nowrap;font-size:13px;font-weight:650}.workspace{flex:1;grid-template-columns:minmax(0,1fr) minmax(280px,360px);min-height:0;display:grid;overflow:hidden}.editor-pane,.comment-pane{min-width:0;min-height:0;padding:20px}.editor-pane{border-right:1px solid #d9dee7;flex-direction:column;display:flex}.editor-frame{background:#fff;border:1px solid #d9dee7;border-radius:8px;flex:1;min-height:0;overflow:auto}.tiptap{outline:none;min-height:100%;padding:28px}.tiptap>:first-child{margin-top:0}.tiptap p{line-height:1.65}.tiptap code{color:#202b3c;background:#eef2f6;border-radius:4px;padding:2px 4px;font-family:Cascadia Code,SFMono-Regular,Consolas,Liberation Mono,monospace;font-size:.9em}.tiptap pre{color:#f5f7fb;background:#18202f;border:1px solid #2d3748;border-radius:8px;margin:18px 0;padding:14px 16px;line-height:1.6;overflow-x:auto}.tiptap pre code{color:inherit;white-space:pre;background:0 0;border-radius:0;padding:0;font-size:13px;display:block}.tiptap mark[data-comment]{cursor:text;background:#fff0a6;border-bottom:2px solid #d29a1f;border-radius:3px;padding:1px 2px}.tiptap .pending-annotation{background:#d8ebff;border-bottom:2px solid #3978b8;border-radius:3px;padding:1px 2px}.tiptap pre mark[data-comment],.tiptap pre .pending-annotation{color:#18202f}.comment-pane{background:#fbfcfd;flex-direction:column;gap:16px;display:flex;overflow:hidden}.comment-pane-header{justify-content:space-between;align-items:center;display:flex}.comment-pane-actions{align-items:center;gap:8px;display:flex}.comment-pane-header span{color:#48556a;text-align:center;background:#e7ecf2;border-radius:999px;min-width:28px;padding:4px 8px;font-size:12px;font-weight:700}.small-button{min-height:32px;padding:0 10px;font-size:13px}.comment-list{flex-direction:column;flex:1;gap:12px;min-height:0;padding-right:2px;display:flex;overflow:auto}.comment-item{background:#fff;border:1px solid #d9dee7;border-radius:8px;flex-direction:column;gap:10px;padding:12px;display:flex}.comment-item.active{border-color:#215f88;box-shadow:0 0 0 3px #215f8824}.comment-item-header{align-items:flex-start;gap:8px;display:flex}.comment-target{color:#3d3320;text-align:left;text-overflow:ellipsis;white-space:nowrap;background:#f7f2d0;border:0;flex:1;min-width:0;min-height:0;padding:8px;font-size:13px;font-weight:700;line-height:1.35;display:block;overflow:hidden}.global-comment-target{color:#25455f;background:#e8f1f8}.delete-comment-button{color:#8f2d2d;flex:none;min-height:30px;padding:0 8px;font-size:12px}.delete-comment-button:hover:not(:disabled){border-color:#b24545}textarea{color:#18202f;font:inherit;resize:vertical;border:1px solid #c6ccd6;border-radius:8px;width:100%;min-height:96px;padding:12px;line-height:1.5}textarea:focus{border-color:#215f88;outline:3px solid #215f882e}.empty-state{color:#647084;margin:0;line-height:1.5}.modal-backdrop{z-index:20;background:#121a2775;justify-content:center;align-items:center;padding:20px;display:flex;position:fixed;inset:0}.modal{background:#fff;border-radius:8px;flex-direction:column;gap:14px;width:min(100%,520px);max-width:520px;padding:20px;display:flex;box-shadow:0 24px 80px #121a2747}.modal textarea{min-height:180px}.modal-actions{justify-content:flex-end;gap:10px;display:flex}@media (width<=800px){.topbar{flex-direction:column;align-items:flex-start}.workspace{grid-template-rows:minmax(0,1fr) minmax(220px,36vh);grid-template-columns:1fr}.editor-pane{border-right:0}.comment-pane{border-top:1px solid #d9dee7}}