@sov3rain/nota 0.1.0 → 0.2.1

package/bin/nota.mjs

@@ -1,126 +1,150 @@
-#!/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';
-
+#!/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';
+import { getAgentInstructionBlock } from './agentInstructions.mjs';
+
 const MAX_BODY_BYTES = 5 * 1024 * 1024;
+const HEARTBEAT_TIMEOUT_MS = 15_000;
+const HEARTBEAT_CHECK_MS = 5_000;
 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);
-}
-
+  '.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 AGENT_TARGETS = ['codex', 'claude', 'cursor'];
+const AGENT_LABELS = {
+  codex: 'Codex',
+  claude: 'Claude',
+  cursor: 'Cursor',
+};
+
+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);
+  }
+
+  const targets = args[1] ? getAgentTargets(args[1]) : await promptForAgentTargets();
+
+  if (!targets) {
+    console.error('Unknown agent target. Expected codex, claude, cursor, or all.');
+    process.exit(1);
+  }
+
+  if (targets.length === 0) {
+    console.log('No agents selected. Nothing to install.');
+    process.exit(0);
+  }
+
+  await initAgentInstructions(targets);
+  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);
-
+let lastHeartbeatAt = null;
+
+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' });
+    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);
-  }
-});
-
+const heartbeatTimeout = setInterval(closeInactiveServer, HEARTBEAT_CHECK_MS);
+heartbeatTimeout.unref();
+
+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);
-}
-
+
+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}`;
 
@@ -128,267 +152,249 @@ function getApiHandler(pathname, method) {
     {
       'GET /api/document': handleDocumentApi,
       'PUT /api/document': handleDocumentApi,
+      'POST /api/heartbeat': handleHeartbeatApi,
       'POST /api/shutdown': handleShutdownApi,
     }[route] ?? null
   );
 }
 
-function handleShutdownApi(request, response, url) {
+function handleHeartbeatApi(request, response, url) {
   if (!isAuthorized(request, url)) {
     sendJson(response, 403, { error: 'Forbidden' });
     return;
   }
 
+  lastHeartbeatAt = Date.now();
   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');
+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 readOptionalFile(filePath) {
-  try {
-    return await readFile(filePath, 'utf8');
-  } catch {
-    return '';
-  }
-}
+function closeInactiveServer() {
+  if (!lastHeartbeatAt) return;
+  if (Date.now() - lastHeartbeatAt < HEARTBEAT_TIMEOUT_MS) return;
 
-function joinTextBlocks(...blocks) {
-  return `${blocks.filter(Boolean).join('\n\n')}\n`;
+  console.log('No active annotation tab detected. Closing nota server.');
+  server.close(() => process.exit(0));
 }
+
+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
+  nota init [codex|claude|cursor|all]`);
+}
+
+async function initAgentInstructions(targets) {
+  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) {
+  if (target === 'all') return AGENT_TARGETS;
+  if (AGENT_TARGETS.includes(target)) return [target];
+
+  return null;
+}
+
+async function promptForAgentTargets() {
+  if (!process.stdin.isTTY) {
+    console.error('Interactive init requires a TTY. Use `nota init all` or `nota init <agent>`.');
+    process.exit(1);
+  }
+
+  try {
+    const { checkbox } = await import('@inquirer/prompts');
+
+    return await checkbox({
+      message: 'Select AI agents to support',
+      choices: AGENT_TARGETS.map((agent) => ({
+        name: AGENT_LABELS[agent],
+        value: agent,
+      })),
+    });
+  } catch (error) {
+    if (error?.name === 'ExitPromptError') {
+      console.log('\nInitialization cancelled.');
+      process.exit(1);
+    }
+
+    throw error;
+  }
+}
+
+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');
+}
+
+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`;
+}