@happy-nut/monacori 0.1.26 → 0.1.27

package/README.md

@@ -2,9 +2,9 @@
 
 **A local desktop review workspace for AI-generated code changes.**
 
-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.
+Run `mo` after an AI edits your repository. monacori opens the real local diff, lets you attach line-level questions or change requests, and turns that feedback into a grounded follow-up prompt for the AI CLI session running in the built-in terminal.
 
-![monacori reviewing a diff, adding a change request, and targeting the built-in terminal](assets/monacori-demo.gif)
+![monacori reviewing an AI-generated diff, adding a line-level change request, merging the prompt, and sending it to the integrated terminal](assets/monacori-core-flow.gif)
 
 ## Why monacori
 
@@ -16,6 +16,15 @@ AI coding tools are fast, but their "done" message is not a review. monacori giv
 - 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/`.
 
+## Core Flow
+
+monacori's core value is a grounded correction loop:
+
+1. Review the exact Git diff produced by an AI coding tool.
+2. Attach a question or change request on the relevant line.
+3. Merge those comments into a prompt that includes file paths, line numbers, and code context.
+4. Send the prompt into the integrated terminal so the next AI turn starts from reviewed evidence, not a chat summary.
+
 ## Workflow
 
 1. Let an AI coding tool make changes in your repository.
@@ -89,6 +98,12 @@ npm unlink -g @happy-nut/monacori     # restore the published `mo`
 `src/viewer.client.js` and `src/viewer.css` are copied (not compiled) into `dist/` by the build, so
 re-run `npm run build` (or `npm run dev`) after editing them.
 
+Regenerate the README demo GIF from a temporary sample repository:
+
+```bash
+npm run demo:gif
+```
+
 ### Tests
 
 ```bash

package/dist/self-update.d.ts

@@ -1,8 +1,24 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 export type RelaunchTarget = {
     relaunch(options?: {
         args?: string[];
     }): void;
     exit(exitCode?: number): void;
 };
+type SpawnFn = typeof spawn;
+type SpawnSyncFn = typeof spawnSync;
+type ExistsFn = typeof existsSync;
+type RelaunchDeps = {
+    spawn?: SpawnFn;
+    spawnSync?: SpawnSyncFn;
+    existsSync?: ExistsFn;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+};
 export declare function relaunchArgsForCwd(argv: string[], cwd: string): string[];
-export declare function relaunchUpdatedApp(app: RelaunchTarget, argv: string[], cwd: string): void;
+export declare function cliArgsForCwd(argv: string[], cwd: string): string[];
+export declare function globalMoBinCandidates(prefix: string, platform: NodeJS.Platform): string[];
+export declare function resolveGlobalMoBin(deps?: RelaunchDeps): string | null;
+export declare function relaunchUpdatedApp(app: RelaunchTarget, argv: string[], cwd: string, deps?: RelaunchDeps): void;
+export {};

package/dist/self-update.js

@@ -1,3 +1,6 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 export function relaunchArgsForCwd(argv, cwd) {
     const args = argv.slice(1);
     const cwdIndex = args.indexOf("--cwd");
@@ -12,7 +15,63 @@ export function relaunchArgsForCwd(argv, cwd) {
     }
     return args;
 }
-export function relaunchUpdatedApp(app, argv, cwd) {
+export function cliArgsForCwd(argv, cwd) {
+    const args = ["--cwd", cwd];
+    if (argv.includes("--no-watch"))
+        args.push("--no-watch");
+    return args;
+}
+export function globalMoBinCandidates(prefix, platform) {
+    if (platform === "win32") {
+        return [join(prefix, "mo.cmd"), join(prefix, "mo")];
+    }
+    return [join(prefix, "bin", "mo"), join(prefix, "mo")];
+}
+export function resolveGlobalMoBin(deps = {}) {
+    const spawnSyncImpl = deps.spawnSync ?? spawnSync;
+    const existsImpl = deps.existsSync ?? existsSync;
+    const platform = deps.platform ?? process.platform;
+    const result = spawnSyncImpl("npm", ["prefix", "-g"], {
+        encoding: "utf8",
+        shell: true,
+        env: deps.env ?? process.env,
+    });
+    if (result.status !== 0 || typeof result.stdout !== "string")
+        return null;
+    const prefix = result.stdout.trim().split(/\r?\n/).pop()?.trim();
+    if (!prefix)
+        return null;
+    return globalMoBinCandidates(prefix, platform).find((candidate) => existsImpl(candidate)) ?? null;
+}
+function spawnDetached(spawnImpl, command, args, cwd, env, shell) {
+    const child = spawnImpl(command, args, { cwd, detached: true, stdio: "ignore", env, shell });
+    child.unref();
+    return child;
+}
+export function relaunchUpdatedApp(app, argv, cwd, deps = {}) {
+    const spawnImpl = deps.spawn ?? spawn;
+    const env = deps.env ?? process.env;
+    const cliArgs = cliArgsForCwd(argv, cwd);
+    const moBin = resolveGlobalMoBin(deps);
+    if (moBin) {
+        try {
+            spawnDetached(spawnImpl, moBin, cliArgs, cwd, env, false);
+            app.exit(0);
+            return;
+        }
+        catch {
+            // Fall through to npm exec; the bin path can exist but still fail to spawn if a manager rewrites it.
+        }
+    }
+    try {
+        spawnDetached(spawnImpl, "npm", ["exec", "-g", "--", "mo", ...cliArgs], cwd, env, true);
+        app.exit(0);
+        return;
+    }
+    catch {
+        // Last resort only. app.relaunch() uses the current executable path; after a rebrand update that path
+        // may be the stale Electron.app/Contents/MacOS/Electron, so prefer the freshly installed CLI above.
+    }
     app.relaunch({ args: relaunchArgsForCwd(argv, cwd) });
     app.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happy-nut/monacori",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "Validation control plane for AI-generated code changes.",
   "type": "module",
   "main": "dist/app-main.js",
@@ -22,6 +22,7 @@
     "assets",
     "scripts/patch-electron-name.mjs",
     "scripts/fix-pty-spawn-helper.mjs",
+    "scripts/record-demo.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -34,6 +35,7 @@
     "icon": "node scripts/gen-icon.mjs",
     "postinstall": "node scripts/patch-electron-name.mjs && node scripts/fix-pty-spawn-helper.mjs",
     "prepare": "npm run build",
+    "demo:gif": "npm run build && electron scripts/record-demo.mjs",
     "smoke": "npm run build && node dist/cli.js --help",
     "pretest": "npm run build",
     "test": "node --test test/*.test.mjs",

package/scripts/record-demo.mjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+
+import { app, BrowserWindow } from "electron";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { buildDiffReview } from "../dist/cli.js";
+
+const repoRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const outputGif = resolve(repoRoot, "assets", "monacori-core-flow.gif");
+const width = 1280;
+const height = 760;
+const frameRate = 10;
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: "utf8", ...options });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || `${command} failed`).trim());
+  }
+  return result.stdout;
+}
+
+function git(cwd, args) {
+  execFileSync("git", args, { cwd, stdio: "ignore" });
+}
+
+function writeDemoFile(root, path, contents) {
+  const fullPath = join(root, path);
+  mkdirSync(dirname(fullPath), { recursive: true });
+  writeFileSync(fullPath, contents);
+}
+
+function createDemoRepo(workRoot) {
+  const demoRepo = join(workRoot, "checkout-flow");
+  mkdirSync(demoRepo, { recursive: true });
+
+  writeDemoFile(demoRepo, "README.md", "# Checkout Flow\n\nReview automation for order changes.\n");
+  writeDemoFile(
+    demoRepo,
+    "src/reviewQueue.ts",
+    [
+      "export type ReviewItem = {",
+      "  id: string;",
+      "  title: string;",
+      "  status: \"open\" | \"archived\";",
+      "  createdAt: number;",
+      "  priority?: \"low\" | \"normal\" | \"high\";",
+      "};",
+      "",
+      "export function buildReviewQueue(items: ReviewItem[]): ReviewItem[] {",
+      "  return items",
+      "    .filter((item) => item.status === \"open\")",
+      "    .sort((a, b) => a.createdAt - b.createdAt);",
+      "}",
+      "",
+    ].join("\n"),
+  );
+  writeDemoFile(
+    demoRepo,
+    "src/prompt.ts",
+    [
+      "export function nextPrompt(file: string, line: number): string {",
+      "  return `Please inspect ${file}:${line}.`;",
+      "}",
+      "",
+    ].join("\n"),
+  );
+
+  git(demoRepo, ["init", "-b", "main"]);
+  git(demoRepo, ["config", "user.email", "demo@monacori.local"]);
+  git(demoRepo, ["config", "user.name", "Monacori Demo"]);
+  git(demoRepo, ["add", "."]);
+  git(demoRepo, ["commit", "-m", "baseline review flow"]);
+
+  writeDemoFile(
+    demoRepo,
+    "src/reviewQueue.ts",
+    [
+      "export type ReviewItem = {",
+      "  id: string;",
+      "  title: string;",
+      "  status: \"open\" | \"archived\";",
+      "  createdAt: number;",
+      "  priority?: \"low\" | \"normal\" | \"high\";",
+      "  assignee?: string;",
+      "};",
+      "",
+      "export function buildReviewQueue(items: ReviewItem[], includeArchived = false): ReviewItem[] {",
+      "  return items",
+      "    .filter((item) => includeArchived || item.status === \"open\")",
+      "    .map((item) => ({",
+      "      ...item,",
+      "      title: item.title.trim(),",
+      "      assignee: item.assignee || \"ai-agent\",",
+      "    }))",
+      "    .sort((a, b) => String(b.priority).localeCompare(String(a.priority)));",
+      "}",
+      "",
+    ].join("\n"),
+  );
+  writeDemoFile(
+    demoRepo,
+    "src/prompt.ts",
+    [
+      "export function nextPrompt(file: string, line: number, comment: string): string {",
+      "  return [`Please inspect ${file}:${line}.`, comment].join(\"\\n\\n\");",
+      "}",
+      "",
+    ].join("\n"),
+  );
+  writeDemoFile(
+    demoRepo,
+    "docs/review-notes.md",
+    [
+      "# AI Review Notes",
+      "",
+      "- Check whether archived items should be opt-in.",
+      "- Preserve stable ordering for equal priorities.",
+      "",
+    ].join("\n"),
+  );
+
+  return demoRepo;
+}
+
+function fakePtyPrelude() {
+  return String.raw`<script>
+window.monacoriClipboard = { write: function (text) { window.__demoClipboard = String(text || ''); } };
+window.monacoriSettings = { all: { 'monacori-theme': 'dark', 'monacori-locale': 'en' }, set: function (key, value) { this.all[key] = value; } };
+window.monacoriMenu = {};
+window.monacoriPty = (function () {
+  var nextId = 0;
+  var dataHandlers = [];
+  var exitHandlers = [];
+  function emit(id, data) {
+    dataHandlers.forEach(function (fn) { fn({ id: id, data: data }); });
+  }
+  return {
+    spawn: function () {
+      var id = ++nextId;
+      setTimeout(function () {
+        emit(id, '\x1b[32mcodex\x1b[0m demo-session ready\r\n$ ');
+      }, 120);
+      return Promise.resolve({ id: id });
+    },
+    onData: function (fn) { dataHandlers.push(fn); },
+    onExit: function (fn) { exitHandlers.push(fn); },
+    resize: function () {},
+    kill: function (msg) { exitHandlers.forEach(function (fn) { fn({ id: msg && msg.id }); }); },
+    bell: function () {},
+    write: function (msg) {
+      var id = msg && msg.id;
+      var text = String((msg && msg.data) || '').replace(/\n/g, '\r\n');
+      setTimeout(function () {
+        emit(id, '\r\n' + text + '\r\n\x1b[36m# grounded follow-up prompt received\x1b[0m\r\n$ ');
+      }, 80);
+    },
+  };
+})();
+window.__demoCaption = function (text) {
+  var el = document.getElementById('demo-caption');
+  if (!el) {
+    el = document.createElement('div');
+    el.id = 'demo-caption';
+    document.body.appendChild(el);
+  }
+  el.textContent = text;
+};
+</script>`;
+}
+
+function demoStyles() {
+  return String.raw`<style>
+#demo-caption {
+  position: fixed;
+  left: 78px;
+  top: 18px;
+  z-index: 9999;
+  padding: 8px 12px;
+  border: 1px solid rgba(255, 255, 255, .15);
+  border-radius: 7px;
+  background: rgba(25, 28, 32, .88);
+  color: #e6edf3;
+  font: 600 13px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, .25);
+}
+.demo-pulse {
+  outline: 2px solid #ffc66d !important;
+  outline-offset: 2px;
+}
+</style>`;
+}
+
+function renderDemoHtml(demoRepo, workRoot) {
+  const review = buildDiffReview({
+    root: demoRepo,
+    includeUntracked: true,
+    staged: false,
+    context: 4,
+    title: "monacori",
+    app: true,
+    lazy: false,
+    lazyLoad: false,
+  });
+  const html = review.html
+    .replace("</head>", `${demoStyles()}\n</head>`)
+    .replace("<body>", `<body>\n${fakePtyPrelude()}`);
+  const htmlPath = join(workRoot, "monacori-demo.html");
+  writeFileSync(htmlPath, html);
+  return htmlPath;
+}
+
+async function waitFor(win, predicate, timeoutMs = 6000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const ok = await win.webContents.executeJavaScript(`Boolean(${predicate})`);
+    if (ok) return;
+    await new Promise((resolve) => setTimeout(resolve, 80));
+  }
+  throw new Error(`Timed out waiting for ${predicate}`);
+}
+
+async function pause(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function capture(win, frameDir, state, repeats = 6) {
+  await pause(90);
+  const image = await win.capturePage();
+  const png = image.toPNG();
+  for (let i = 0; i < repeats; i += 1) {
+    state.index += 1;
+    writeFileSync(join(frameDir, `frame-${String(state.index).padStart(4, "0")}.png`), png);
+  }
+}
+
+async function captureTyping(win, frameDir, state, selector, text) {
+  await win.webContents.executeJavaScript(`document.querySelector(${JSON.stringify(selector)}).value = ""`);
+  for (let i = 0; i < text.length; i += 4) {
+    const chunk = text.slice(0, i + 4);
+    await win.webContents.executeJavaScript(`
+      var el = document.querySelector(${JSON.stringify(selector)});
+      el.value = ${JSON.stringify(chunk)};
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+    `);
+    await capture(win, frameDir, state, 1);
+  }
+}
+
+async function recordFrames(htmlPath, frameDir) {
+  const win = new BrowserWindow({
+    width,
+    height,
+    show: false,
+    paintWhenInitiallyHidden: true,
+    backgroundColor: "#2b2b2b",
+    webPreferences: {
+      offscreen: true,
+      contextIsolation: false,
+      nodeIntegration: false,
+      sandbox: false,
+    },
+  });
+  const state = { index: 0 };
+  await win.loadURL(`${pathToFileURL(htmlPath).href}#hunk-0`);
+  await waitFor(win, "!document.getElementById('boot-overlay')");
+  await waitFor(win, "document.querySelector('#diff-view:not(.hidden) .diff-active-row')");
+
+  await win.webContents.executeJavaScript(`
+    window.__demoCaption('1. Review the exact AI-generated diff');
+    document.querySelector('.diff-active-row')?.classList.add('demo-pulse');
+  `);
+  await capture(win, frameDir, state, 10);
+
+  await win.webContents.executeJavaScript(`
+    document.querySelector('.diff-active-row')?.classList.remove('demo-pulse');
+    window.__demoCaption('2. Add a line-level change request');
+    openComposer('c');
+  `);
+  await waitFor(win, "document.querySelector('.mc-composer .mc-input')");
+  await capture(win, frameDir, state, 4);
+  await captureTyping(
+    win,
+    frameDir,
+    state,
+    ".mc-composer .mc-input",
+    "Keep archived reviews out of the default queue and preserve a stable priority order.",
+  );
+  await win.webContents.executeJavaScript("saveComposer()");
+  await waitFor(win, "document.querySelector('.mc-card.mc-c')");
+  await capture(win, frameDir, state, 8);
+
+  await win.webContents.executeJavaScript(`
+    window.__demoCaption('3. Merge comments into a grounded follow-up prompt');
+    openMergedView('c');
+  `);
+  await waitFor(win, "document.querySelector('#mc-merged-panel textarea')");
+  await capture(win, frameDir, state, 10);
+
+  await win.webContents.executeJavaScript(`
+    window.__demoCaption('4. Send the prompt into the integrated AI terminal');
+    var promptText = buildMergedText('c');
+    window.__monacoriTerminal.open();
+    window.__demoPromptText = promptText;
+  `);
+  await waitFor(win, "window.__monacoriTerminal && window.__monacoriTerminal.paneCount() > 0");
+  await capture(win, frameDir, state, 6);
+  await win.webContents.executeJavaScript("window.__monacoriTerminal.enterSendMode(window.__demoPromptText)");
+  await capture(win, frameDir, state, 6);
+  await win.webContents.executeJavaScript("window.__monacoriTerminal.send(window.__demoPromptText)");
+  await pause(300);
+  await capture(win, frameDir, state, 12);
+
+  win.destroy();
+  return state.index;
+}
+
+function makeGif(frameDir) {
+  if (!existsSync(outputGif)) mkdirSync(dirname(outputGif), { recursive: true });
+  const palette = join(frameDir, "palette.png");
+  run("ffmpeg", [
+    "-y",
+    "-framerate",
+    String(frameRate),
+    "-i",
+    join(frameDir, "frame-%04d.png"),
+    "-vf",
+    "fps=10,scale=960:-1:flags=lanczos,palettegen",
+    palette,
+  ]);
+  run("ffmpeg", [
+    "-y",
+    "-framerate",
+    String(frameRate),
+    "-i",
+    join(frameDir, "frame-%04d.png"),
+    "-i",
+    palette,
+    "-lavfi",
+    "fps=10,scale=960:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=3",
+    outputGif,
+  ]);
+}
+
+async function main() {
+  const workRoot = mkdtempSync(join(tmpdir(), "monacori-demo-"));
+  try {
+    const demoRepo = createDemoRepo(workRoot);
+    const htmlPath = renderDemoHtml(demoRepo, workRoot);
+    const frameDir = join(workRoot, "frames");
+    mkdirSync(frameDir, { recursive: true });
+    const frames = await recordFrames(htmlPath, frameDir);
+    makeGif(frameDir);
+    console.log(`wrote ${outputGif} from ${frames} frames`);
+  } finally {
+    if (process.env.MONACORI_KEEP_DEMO_FRAMES !== "1") {
+      rmSync(workRoot, { recursive: true, force: true });
+    } else {
+      console.log(`kept demo workdir: ${workRoot}`);
+    }
+  }
+}
+
+app.whenReady()
+  .then(main)
+  .then(() => app.quit())
+  .catch((error) => {
+    console.error(error instanceof Error ? error.stack || error.message : String(error));
+    app.exit(1);
+  });