@happy-nut/monacori 0.1.3 → 0.1.6

package/README.md

@@ -1,24 +1,30 @@
 # monacori
 
-**Validation control plane for AI-generated code changes.** After an AI edits your repository, `monacori` produces verification evidence a human can actually trust.
+**A local desktop review workspace for AI-generated code changes.**
 
-It is *not* an agent orchestrator. It does not manage panes, sessions, worktrees, or model adapters. Its job is narrow on purpose: validate what the AI just did.
+Run `mo` after an AI edits your repository. monacori opens a side-by-side diff, lets you attach line-level questions or change requests, and bundles that feedback back into the AI CLI (command-line interface) session running in the built-in terminal.
 
-## Why
+![monacori reviewing a diff, adding a change request, and targeting the built-in terminal](assets/monacori-demo.gif)
 
-AI coding output is hard to trust when review depends on chat memory or a vague "done" claim. `monacori` keeps the review artifacts inside the repository, so the state of a change can be inspected, rerun, and discussed instead of taken on faith.
+## Why monacori
 
-The loop is simple:
+AI coding tools are fast, but their "done" message is not a review. monacori gives the human reviewer a dedicated control surface for the gap between generated code and trusted code:
 
-```text
-AI edits code.
-monacori runs verification.
-monacori creates a reviewable diff artifact.
-You inspect the evidence before accepting the change.
-```
+- See every changed, added, and untracked file in an IntelliJ-style review sidebar.
+- Review side-by-side diffs with syntax highlighting, changed-line emphasis, and keyboard navigation.
+- Leave questions or change requests directly on the relevant line.
+- Send all reviewer comments, with file paths and code context, into `claude`, `codex`, or another terminal session without copy-paste.
+- Keep all generated review state local, plain, and inspectable under `.monacori/`.
+
+## Workflow
+
+1. Let an AI coding tool make changes in your repository.
+2. Run `mo` from that repository.
+3. Inspect the diff, mark files as viewed, and attach line comments where needed.
+4. Open the built-in terminal and keep your AI CLI session beside the review.
+5. Send the merged questions or change requests back to the session as a focused follow-up prompt.
 
-![Diff review](assets/screenshots/diff-review.png)
-*Local desktop review app: side-by-side diff with changed lines highlighted and IntelliJ-style git status colors in the sidebar.*
+The result is a tighter review loop: the AI produces changes, the human reviews the actual diff, and the next prompt is grounded in exact file and line context.
 
 ## Install
 
@@ -26,63 +32,61 @@ You inspect the evidence before accepting the change.
 npm install -g @happy-nut/monacori
 ```
 
-After install, the short command is `mo`. A Homebrew tap (`happy-nut/monacori/monacori`) is also available.
+The short command is `mo`.
 
-## What you get
+Homebrew users can install from the tap as well:
 
-- **Local desktop review app** — diff review with changed-line highlighting and an IntelliJ-style sidebar that colors files by git status. Reads the repo directly, refreshes on change, no HTTP server.
-- **Integrated terminal** — run AI CLIs like `claude` or `codex` inside the app, and send a "merged prompt" (your question or fix request bundled with the relevant code context) straight to the session.
-- **Inline comments** — annotate the diff while you review.
-- **Verification logs & reports** — repeatable verification under `.monacori/logs/` and compact validation reports under `.monacori/reports/`.
-
-![Integrated terminal](assets/screenshots/terminal.png)
-*Run your AI CLI inside the review app, next to the diff it just produced.*
+```bash
+brew install happy-nut/monacori/monacori
+```
 
-## Quick start
+## Quick Start
 
-Inside the repository you want to validate:
+Inside any Git repository:
 
 ```bash
-mo                              # open the desktop review app for the current dir
-monacori check --include-untracked   # run verification, write a log, diff, and report
+mo
 ```
 
-On first run, `mo` creates `.monacori/`, adds it to `.gitignore`, and includes untracked files so new AI-created files show up immediately.
+On first run, `mo` creates `.monacori/`, adds it to `.gitignore`, and includes untracked files so new AI-created files appear immediately.
+
+## Highlights
+
+- **Desktop diff review**: reads the repository directly, refreshes from local Git state, and does not require a web server.
+- **AI handoff comments**: questions and change requests are stored with their file, line, and code context.
+- **Integrated terminal**: keep `claude`, `codex`, or a shell open inside the same window, with split panes when needed.
+- **Source navigation**: jump between changed files, search indexed files, preview source, and move through hunks from the keyboard.
+- **Plain local artifacts**: generated review files and state are Markdown, JSON, and static HTML under `.monacori/`.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `mo` | Open the desktop review app (alias for `monacori open`). |
-| `monacori check` | Run verification, then create a diff and a validation report. `-- <cmd>` overrides commands for one run. |
-| `monacori verify` | Run configured verification commands and store the log. Exits non-zero on failure. |
-| `monacori diff` | Generate a browser-based side-by-side diff page. `--watch` serves a live-reloading review. |
-| `monacori app` | Launch the desktop review app (same as `mo`). |
-| `monacori report` | Store a manual report under `.monacori/reports/`. |
-| `monacori status` | Print branch, git status, diff stat, verification commands, and recent reports/logs. |
-
-## Repository state
-
-`monacori init` (run automatically by `mo`) creates:
-
-```text
-.monacori/
-  config.json   verification commands and diff defaults
-  state.md      compact validation history
-  diffs/        generated browser diff reviews
-  reports/      validation reports
-  logs/         verification logs
+| `mo` | Open the desktop diff-review app for the current repository. Alias for `monacori open`. |
+| `monacori open` | Launch the review app, auto-initialize `.monacori/`, and include untracked files by default. |
+| `monacori app` | Launch the same desktop app explicitly. |
+| `monacori init` | Initialize `.monacori/` in the current directory. |
+| `monacori install` | Initialize and write agent instruction snippets. Use `--apply-agent-docs` to patch `AGENTS.md` or `CLAUDE.md`. |
+
+Useful review options:
+
+```bash
+mo --staged              # review only staged changes
+mo --tracked-only        # exclude untracked files
+mo --base main           # compare against a specific base
+mo --context 20          # show more context around each hunk
 ```
 
-Keep `.monacori/` ignored unless your team explicitly wants to commit validation state.
+## Local State
+
+`monacori init` creates a git-ignored `.monacori/` directory for generated diff reviews, local config, comments, logs, and validation notes. Keep it ignored unless your team intentionally wants to version review artifacts.
 
-## Design principles
+## Design Principles
 
-- Verification evidence beats chat memory.
-- Generated artifacts are plain Markdown, JSON, logs, or static HTML.
-- No required AI agent, terminal multiplexer, editor, or worktree strategy.
-- The default command should be useful after any AI-generated edit.
-- A change is not accepted until the evidence is clear or the gap is documented.
+- Real diffs beat chat summaries.
+- Human review should stay close to the code and the running AI session.
+- The core should be local, inspectable, and agent-agnostic.
+- No required terminal multiplexer, editor plugin, hosted service, or worktree strategy.
 
 ## License
 

package/dist/app-main.js

@@ -71,8 +71,37 @@ ipcMain.handle("monacori:pty-spawn", (_event, size) => {
         if (mainWindow && !mainWindow.isDestroyed())
             mainWindow.webContents.send(channel, payload);
     };
-    t.onData((data) => deliver("monacori:pty-data", { id, data }));
-    t.onExit(() => { terms.delete(id); deliver("monacori:pty-exit", { id }); });
+    // pty output can arrive as many tiny chunks (thousands/sec under fast output). One IPC per chunk floods
+    // the renderer, so coalesce: buffer chunks and flush on a short timer, or immediately once the buffer is
+    // large — bounding both IPC traffic and added latency.
+    let outBuf = "";
+    let flushTimer;
+    const flushOut = () => {
+        flushTimer = undefined;
+        if (!outBuf)
+            return;
+        const data = outBuf;
+        outBuf = "";
+        deliver("monacori:pty-data", { id, data });
+    };
+    t.onData((data) => {
+        outBuf += data;
+        if (outBuf.length >= 64 * 1024) {
+            if (flushTimer)
+                clearTimeout(flushTimer);
+            flushOut();
+        }
+        else if (!flushTimer) {
+            flushTimer = setTimeout(flushOut, 12);
+        }
+    });
+    t.onExit(() => {
+        if (flushTimer)
+            clearTimeout(flushTimer);
+        flushOut(); // deliver any buffered tail before signaling exit
+        terms.delete(id);
+        deliver("monacori:pty-exit", { id });
+    });
     return { ok: true, id };
 });
 ipcMain.on("monacori:pty-write", (_event, msg) => { terms.get(msg?.id)?.write(msg.data); });
@@ -151,6 +180,8 @@ app.whenReady().then(async () => {
         submenu: [
             { label: "All questions", accelerator: "Control+Command+Shift+/", click: () => sendMerged("q") },
             { label: "All change requests", accelerator: "Control+Command+Shift+.", click: () => sendMerged("c") },
+            // Cmd/Ctrl+Shift+N opens (and toggles) the single freeform prompt memo — a Markdown scratchpad.
+            { label: "Prompt memo", accelerator: "CommandOrControl+Shift+N", click: () => mainWindow?.webContents.send("monacori:open-memo") },
             { type: "separator" },
             // Whitespace-ignore re-runs git diff with --ignore-all-space and reloads (main-process action,
             // so a menu checkbox is simpler than a renderer IPC round-trip).
@@ -190,7 +221,7 @@ app.whenReady().then(async () => {
             { type: "separator" },
             { label: "Focus Previous Pane", accelerator: "CommandOrControl+Alt+[", click: () => mainWindow?.webContents.send("monacori:terminal-pane-focus", -1) },
             { label: "Focus Next Pane", accelerator: "CommandOrControl+Alt+]", click: () => mainWindow?.webContents.send("monacori:terminal-pane-focus", 1) },
-            { label: "Rename Pane", accelerator: "F2", click: () => mainWindow?.webContents.send("monacori:terminal-pane-rename") },
+            { label: "Rename Pane", accelerator: "CommandOrControl+Alt+R", click: () => mainWindow?.webContents.send("monacori:terminal-pane-rename") },
         ],
     });
     Menu.setApplicationMenu(Menu.buildFromTemplate(menuTemplate));
@@ -222,7 +253,10 @@ app.whenReady().then(async () => {
     // paint and swap it in. The first build used to run synchronously *before* the window existed, so the
     // screen stayed blank for the first few seconds of startup; now the user sees a loading screen instead.
     await mainWindow.loadURL("data:text/html;charset=utf-8," + encodeURIComponent(LOADING_HTML));
-    setImmediate(() => {
+    // Give the loading spinner a few frames to actually paint before the (synchronous) first build blocks
+    // the main process — otherwise the spinner looks frozen until the build finishes. The boot overlay in
+    // the review HTML then takes over, so there's no blank gap when loadFile swaps the page in.
+    setTimeout(() => {
         try {
             const firstBuild = writeReviewFile(options);
             currentSignature = firstBuild.signature;
@@ -235,7 +269,7 @@ app.whenReady().then(async () => {
             console.error(error instanceof Error ? error.message : String(error));
             app.quit();
         }
-    });
+    }, 60);
 }).catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     app.quit();
@@ -260,7 +294,13 @@ async function refreshIfChanged() {
         const next = writeReviewFile(options);
         if (next.signature !== currentSignature) {
             currentSignature = next.signature;
-            mainWindow.webContents.reloadIgnoringCache();
+            // Refresh the diff in place instead of reloading the window. A full reload re-runs the renderer,
+            // whose beforeunload kills every pty — so an integrated terminal running claude/codex would die on
+            // each working-tree change. We send only the compact update payload (diff/trees/status/data — no
+            // xterm blob), and the renderer transplants it + re-fetches per-file bodies/source over the existing
+            // IPC (currentBodies/currentSourceData were just refreshed by writeReviewFile above).
+            if (next.update)
+                mainWindow.webContents.send("monacori:diff-update", next.update);
         }
     }
     catch (error) {
@@ -284,7 +324,7 @@ function writeReviewFile(input) {
     writeFileSync(reviewPath(), build.html);
     currentBodies = build.lazyBodies ?? [];
     currentSourceData = build.lazySourceData ?? "[]";
-    return { signature: build.signature };
+    return { signature: build.signature, html: build.html, update: build.update };
 }
 function reviewPath() {
     return join(options.root, FLOW_DIR, REVIEW_FILE);

package/dist/build.js

@@ -3,7 +3,7 @@ import { basename } from "node:path";
 import { isGitRepository } from "./git.js";
 import { collectHttpEnvironments, collectReviewFileStates, collectSourceFiles, parseUnifiedDiff, readUnifiedDiff } from "./diff.js";
 import { renderDiff2Html } from "./highlight.js";
-import { diffSubtitle, renderDiffHtml, renderNotGitRepoHtml, shouldLazyRender, splitDiffForLazy } from "./render.js";
+import { diffSubtitle, renderDiffHtml, renderDiffTree, renderNotGitRepoHtml, renderReviewStatus, renderSourceTree, shouldLazyRender, splitDiffForLazy } from "./render.js";
 export function buildDiffReview(input) {
     if (!isGitRepository(process.cwd())) {
         return {
@@ -65,6 +65,27 @@ export function buildDiffReview(input) {
         signature,
         generatedAt,
     });
+    // Compact payload for in-place refresh: just the regions the renderer swaps on a watch change. Reuses
+    // the same fragment renderers as the full page, minus the heavy bits (xterm blob, embedded source).
+    const update = {
+        signature,
+        generatedAt,
+        diffContainer: diffSplit.container || '<div class="empty" data-i18n="diff.noDiff">No diff to review.</div>',
+        changesPanel: renderDiffTree(files),
+        filesTree: renderSourceTree(sourceFiles),
+        reviewStatus: renderReviewStatus({
+            files: files.length,
+            hunks,
+            embeddedFiles: sourceFiles.filter((file) => file.embedded).length,
+            sourceFileCount: sourceFiles.length,
+            ignoreWhitespace: input.ignoreWhitespace,
+            watch: input.watch,
+            generatedAt,
+        }),
+        fileStates,
+        sourceFilesMeta: lazyLoad ? sourceFiles.map((file) => ({ ...file, content: "", image: "" })) : sourceFiles,
+        httpEnvironments,
+    };
     return {
         html,
         files: files.length,
@@ -73,5 +94,6 @@ export function buildDiffReview(input) {
         generatedAt,
         lazyBodies: diffSplit.bodies,
         lazySourceData: lazyLoad ? JSON.stringify(sourceFiles) : undefined,
+        update,
     };
 }