@sov3rain/nota 0.1.0 → 0.2.0

package/README.md

@@ -29,12 +29,15 @@ nota --no-open path/to/plan.md
 ### Set up agent instructions
 
 ```bash
-nota init          # all agents (Claude, Codex, Cursor)
+nota init          # choose agents interactively
+nota init all      # all agents, non-interactive
 nota init claude   # Claude only
 nota init codex    # Codex only
 nota init cursor   # Cursor only
 ```
 
+The interactive mode starts with no agents selected, so you explicitly choose the agent instructions to install.
+
 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

package/bin/agentInstructions.mjs

@@ -0,0 +1,56 @@
+export function getAgentInstructionBlock() {
+  return `<!-- nota:start -->
+## Plan Annotation Workflow
+
+When the user asks for an implementation plan, create a Markdown file in:
+
+\`\`\`text
+.agent-plans/<linux-epoch-seconds>-<topic>.md
+\`\`\`
+
+The filename must start with the current Unix epoch timestamp in seconds, not a formatted date.
+
+Then launch the local annotation tool and wait for the command to exit.
+
+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. Keep the command attached and do not continue with implementation until the \`nota\` process exits.
+
+When the \`nota\` process exits, treat that as the signal that the user has finished annotating. 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 -->
+`;
+}

package/bin/agentInstructions.test.mjs

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { getAgentInstructionBlock } from './agentInstructions.mjs';
+
+describe('getAgentInstructionBlock', () => {
+  it('instructs agents to wait for the nota process to exit', () => {
+    const block = getAgentInstructionBlock();
+
+    expect(block).toContain('wait for the command to exit');
+    expect(block).toContain('do not continue with implementation until the `nota` process exits');
+    expect(block).toContain('When the `nota` process exits');
+    expect(block).not.toContain('until the user says they are done annotating');
+  });
+
+  it('keeps the Windows npm shim guidance', () => {
+    const block = getAgentInstructionBlock();
+
+    expect(block).toContain('nota.cmd .agent-plans/<file>.md');
+    expect(block).toContain('Do not use `Start-Process -FilePath nota`');
+  });
+});

package/bin/nota.mjs

@@ -7,6 +7,7 @@ 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 MIME_TYPES = {
@@ -16,6 +17,12 @@ const MIME_TYPES = {
   '.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];
@@ -29,7 +36,19 @@ if (command === 'init') {
     process.exit(0);
   }
 
-  await initAgentInstructions(args[1] ?? 'all');
+  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);
 }
 
@@ -262,17 +281,11 @@ function openBrowser(url) {
 function printUsage() {
   console.log(`Usage:
   nota [--no-open] <path/to/plan.md>
+  nota init
   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);
-  }
-
+async function initAgentInstructions(targets) {
   await mkdir(resolve(process.cwd(), '.agent-plans'), { recursive: true });
   await writeFile(resolve(process.cwd(), '.agent-plans', '.gitkeep'), '', { flag: 'a' });
 
@@ -285,14 +298,38 @@ async function initAgentInstructions(target) {
 }
 
 function getAgentTargets(target) {
-  const allTargets = ['codex', 'claude', 'cursor'];
-
-  if (target === 'all') return allTargets;
-  if (allTargets.includes(target)) return [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);
@@ -309,61 +346,6 @@ function getAgentInstructionPath(agent) {
   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 -->';

package/dist/assets/index-CUPUlyC5.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:32px;padding:0 12px;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:16px;padding:10px 20px;display:flex}.eyebrow{color:#647084;text-transform:uppercase;margin:0 0 4px;font-size:12px;font-weight:750}.topbar h1,.comment-pane-header h2{margin:0}.topbar h1{font-size:20px}.comment-pane-header 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;width:100%;max-width:90ch;min-height:0;margin:0 auto;overflow:auto}.tiptap{outline:none;min-height:100%;padding:28px}.tiptap>:first-child{margin-top:0}.tiptap p{line-height:1.65}.tiptap h1,.tiptap h2,.tiptap h3,.tiptap h4,.tiptap h5,.tiptap h6{color:#121a27;margin:1.4em 0 .55em;font-weight:750;line-height:1.25}.tiptap h1{font-size:2rem}.tiptap h2{font-size:1.6rem}.tiptap h3{font-size:1.35rem}.tiptap h4{font-size:1.15rem}.tiptap h5{font-size:1rem}.tiptap h6{color:#48556a;text-transform:uppercase;font-size:.9rem}.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}}