@crouton-kit/humanloop 0.3.9 → 0.3.10

package/dist/cli.js

@@ -5,7 +5,7 @@ import { readdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { resolve, join, basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { launchReview } from './editor/review.js';
+import { launchReview, reviewVimscript } from './editor/review.js';
 import { validateDeck } from './inbox/deck-schema.js';
 import { ask, inbox } from './api.js';
 import { display } from './surfaces/display.js';
@@ -564,7 +564,13 @@ reviewCmd
     '         editor?: string|null, tmux?: bool=true }\n' +
     'stdout { job_id: string, output: string (absolute), follow_up: string }\n' +
     '\n' +
-    'Effects: spawns nvim/vim read-only; autosaves feedback JSON.\n')
+    'Effects: spawns nvim/vim read-only DETACHED in a tmux pane when tmux=true\n' +
+    '         and $TMUX set; returns before the human starts. Writes\n' +
+    '         <dir>/review.vim, <dir>/feedback.json (on finish), <dir>/job.log.\n' +
+    '         autosaves feedback JSON; the open pane live-reloads the source on\n' +
+    '         disk edits. The review is open-ended (a human may take many\n' +
+    '         minutes) — collect via `hl job result` with wait:true, run\n' +
+    '         backgrounded so the call does not block on the human.\n')
     .helpOption('-h, --help', 'Show help')
     .action(async () => {
     const input = parseStdinJson();
@@ -576,15 +582,52 @@ reviewCmd
         emitError({ error: 'file_not_found', message: `File not found: ${absFile}`, field: 'file', next: 'Check the file path.' });
     }
     const output = resolve(input.output ? input.output : `${absFile}.feedback.json`);
-    const noTmux = input.tmux === false;
-    const jobDir = mkdtempSync(join(tmpdir(), 'hl-review-'));
+    const useTmux = input.tmux !== false;
+    // Shared job dir: the detached child reuses the parent's via input.dir;
+    // a top-level call mints one. The review.vim is written up front (and the
+    // job_started logged) so the job is recognizable as a live review — and so
+    // the child sources the exact vimscript — before any pane is spawned.
+    const jobDir = input.dir ? resolve(input.dir) : mkdtempSync(join(tmpdir(), 'hl-review-'));
+    mkdirSync(jobDir, { recursive: true });
     const jobId = basename(jobDir);
-    appendJobLog(jobDir, { level: 'info', event: 'job_started', message: 'review open job started', data: { jobId, file: absFile } });
+    if (!input.dir) {
+        writeFileSync(join(jobDir, 'review.vim'), reviewVimscript());
+        appendJobLog(jobDir, { level: 'info', event: 'job_started', message: 'review open job started', data: { jobId, file: absFile } });
+    }
+    // tmux path: detach a child that owns the editor pane and return the handle
+    // now, mirroring `deck ask`. The child re-enters this leaf with tmux:false
+    // and the shared dir, falling through to the in-process branch below.
+    if (process.env['TMUX'] && useTmux) {
+        const scriptPath = process.argv[1];
+        if (!scriptPath) {
+            emitError({ error: 'internal', message: 'Cannot determine hl script path', next: 'Report this as a bug.' });
+        }
+        const sq = (s) => /^[a-zA-Z0-9_\-./:@%+=]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+        const childInput = JSON.stringify({ file: absFile, output, editor: input.editor ?? null, tmux: false, dir: jobDir });
+        const cmd = `echo ${sq(childInput)} | ${sq(process.execPath)} ${sq(scriptPath)} review open`;
+        try {
+            execFileSync('tmux', ['split-window', '-d', '-h', cmd], { stdio: 'ignore' });
+        }
+        catch (spawnErr) {
+            const msg = spawnErr instanceof Error ? spawnErr.message : String(spawnErr);
+            appendJobLog(jobDir, { level: 'error', event: 'job_failed', message: `tmux spawn failed: ${msg}` });
+            emitError({ error: 'internal', message: `tmux spawn failed: ${msg}`, next: 'Check that $TMUX is set. Or pass tmux:false.' });
+        }
+        process.stdout.write(JSON.stringify({
+            job_id: jobId,
+            output,
+            follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to block until the human finishes the review. They may take many minutes — run this backgrounded; you will be notified on completion.`,
+        }) + '\n');
+        process.exit(0);
+    }
+    // In-process path: the detached child (this pane is its TTY), or a degraded
+    // top-level call with no tmux. launchReview blocks until the editor exits.
     try {
         const result = await launchReview(absFile, {
             output,
             editor: (input.editor && typeof input.editor === 'string') ? input.editor : undefined,
-            noTmux,
+            noTmux: true,
+            jobDir,
         });
         appendJobLog(jobDir, { level: 'info', event: 'job_finished', message: 'review finished', data: { comments: result.comments.length } });
         writeFileSync(join(jobDir, 'feedback.json'), JSON.stringify(result, null, 2));
@@ -592,6 +635,7 @@ reviewCmd
             job_id: jobId,
             output,
             follow_up: `Call hl job result with stdin {"job_id":"${jobId}","wait":true} to retrieve the feedback.`,
+            ...(input.dir ? {} : { _note: 'No tmux: launchReview blocked synchronously. Result is already available.' }),
         }) + '\n');
         process.exit(0);
     }

package/dist/editor/review.d.ts

@@ -23,7 +23,16 @@ export interface ReviewOptions {
         w: string;
         h: string;
     };
+    /**
+     * Reuse this directory for `review.vim` instead of minting a fresh temp dir.
+     * The async `review open` kickoff passes its job dir so the detached child
+     * sources the same vimscript the parent already wrote there (which also lets
+     * the job be recognized as a review while it's still live). When the file
+     * already exists it is left untouched.
+     */
+    jobDir?: string;
 }
+export declare function reviewVimscript(): string;
 /**
  * Compact stdout rendering for the agent: per comment just the line:col
  * range, the original text in that span, and the note — plus the source

package/dist/editor/review.js

@@ -26,12 +26,13 @@ function resolveEditor(override) {
 // The entire review UX as a clean, minimal Vimscript config sourced via `-u`.
 // Works in both Neovim and Vim 8+. The source file is opened read-only; the
 // human anchors comments to real source lines/selections and quits to submit.
-function reviewVimscript() {
+export function reviewVimscript() {
     return [
         `" hl propose — review layer. Runs on a CLEAN config (nvim -u NONE: no`,
         `" init.lua, no LazyVim, no plugins/keymaps). Look/feel is ONLY the user's`,
-        `" 'gloam' colorscheme + built-in treesitter markdown highlighting, applied`,
-        `" below. The rest is the read-only guard, comment commands, and autosave.`,
+        `" 'gloam' colorscheme + built-in treesitter markdown highlighting + (when`,
+        `" installed) render-markdown.nvim for GFM tables/headings, applied below.`,
+        `" The rest is the read-only guard, comment commands, and autosave.`,
         `let g:hl_out = $HL_OUTPUT`,
         `let g:hl_src = $HL_SOURCE`,
         `let s:comments = []`,
@@ -146,35 +147,96 @@ function reviewVimscript() {
         `  echo 'Removed last comment — ' . len(s:comments) . ' left'`,
         `endfunction`,
         ``,
-        `function! s:List() abort`,
-        `  let l:wid = bufwinid('__HL_Comments__')`,
-        `  if l:wid != -1`,
-        `    call win_gotoid(l:wid) | close | return`,
-        `  endif`,
+        `" Build the list buffer lines plus a parallel map from buffer line -> comment`,
+        `" index (0-based; -1 for non-actionable rows like the quote continuation or`,
+        `" the empty-state hint). Stored on the buffer so the action maps can resolve`,
+        `" which comment the cursor is on.`,
+        `function! s:ListLines() abort`,
         `  let l:lines = []`,
+        `  let l:map = []`,
         `  if empty(s:comments)`,
-        `    let l:lines = ['(no comments yet — select text or put the cursor on a line, then <Space>c  or  :HLComment)']`,
+        `    call add(l:lines, '(no comments yet — select text or put the cursor on a line, then <Space>c  or  :HLComment)')`,
+        `    call add(l:map, -1)`,
         `  else`,
-        `    let l:i = 1`,
+        `    let l:idx = 0`,
         `    for l:c in s:comments`,
         `      let l:ln = get(l:c,'line',0)`,
         `      let l:end = get(l:c,'endLine',l:ln)`,
         `      let l:loc = l:ln == l:end ? ('L' . l:ln) : ('L' . l:ln . '-' . l:end)`,
-        `      call add(l:lines, l:i . '. [' . l:loc . ']  ' . get(l:c,'comment',''))`,
+        `      call add(l:lines, (l:idx+1) . '. [' . l:loc . ']  ' . get(l:c,'comment',''))`,
+        `      call add(l:map, l:idx)`,
         `      if !empty(get(l:c,'quote',''))`,
         `        call add(l:lines, '      > ' . substitute(get(l:c,'quote',''), "\\n", ' / ', 'g'))`,
+        `        call add(l:map, l:idx)`,
         `      endif`,
-        `      let l:i += 1`,
+        `      let l:idx += 1`,
         `    endfor`,
         `  endif`,
-        `  botright 10split __HL_Comments__`,
-        `  setlocal buftype=nofile bufhidden=wipe noswapfile nobuflisted`,
-        `  setlocal nonumber nocursorline winfixheight signcolumn=no`,
+        `  return [l:lines, l:map]`,
+        `endfunction`,
+        ``,
+        `" Refill the (already-open) comments buffer in place and refresh the line map.`,
+        `function! s:RenderList() abort`,
+        `  let [l:lines, l:map] = s:ListLines()`,
+        `  let b:hl_map = l:map`,
         `  setlocal modifiable`,
+        `  silent! 1,$delete _`,
         `  call setline(1, l:lines)`,
         `  setlocal nomodifiable`,
+        `endfunction`,
+        ``,
+        `" Comment index (0-based) under the cursor in the comments buffer, or -1.`,
+        `function! s:ListIdx() abort`,
+        `  if !exists('b:hl_map') | return -1 | endif`,
+        `  let l:lnum = line('.')`,
+        `  if l:lnum < 1 || l:lnum > len(b:hl_map) | return -1 | endif`,
+        `  return b:hl_map[l:lnum - 1]`,
+        `endfunction`,
+        ``,
+        `function! s:ListDelete() abort`,
+        `  let l:idx = s:ListIdx()`,
+        `  if l:idx < 0`,
+        `    echohl WarningMsg | echo 'No comment on this line' | echohl NONE | return`,
+        `  endif`,
+        `  call remove(s:comments, l:idx)`,
+        `  call s:Save()`,
+        `  call s:Marks()`,
+        `  call s:RenderList()`,
+        `  echo 'Deleted comment — ' . len(s:comments) . ' left'`,
+        `endfunction`,
+        ``,
+        `function! s:ListEdit() abort`,
+        `  let l:idx = s:ListIdx()`,
+        `  if l:idx < 0`,
+        `    echohl WarningMsg | echo 'No comment on this line' | echohl NONE | return`,
+        `  endif`,
+        `  let l:cur = get(s:comments[l:idx], 'comment', '')`,
+        `  let l:txt = input('Edit comment: ', l:cur)`,
+        `  redraw`,
+        `  if empty(trim(l:txt))`,
+        `    echohl WarningMsg | echo 'Edit cancelled — comment unchanged' | echohl NONE | return`,
+        `  endif`,
+        `  let s:comments[l:idx]['comment'] = l:txt`,
+        `  call s:Save()`,
+        `  call s:RenderList()`,
+        `  echo 'Updated comment'`,
+        `endfunction`,
+        ``,
+        `function! s:List() abort`,
+        `  let l:wid = bufwinid('__HL_Comments__')`,
+        `  if l:wid != -1`,
+        `    call win_gotoid(l:wid) | close | return`,
+        `  endif`,
+        `  botright 10split __HL_Comments__`,
+        `  setlocal buftype=nofile bufhidden=wipe noswapfile nobuflisted`,
+        `  setlocal nonumber cursorline winfixheight signcolumn=no`,
+        `  call s:RenderList()`,
         `  nnoremap <buffer> <silent> q :close<CR>`,
         `  nnoremap <buffer> <silent> <Space>l :close<CR>`,
+        `  nnoremap <buffer> <silent> dd :call <SID>ListDelete()<CR>`,
+        `  nnoremap <buffer> <silent> e :call <SID>ListEdit()<CR>`,
+        `  nnoremap <buffer> <silent> <CR> :call <SID>ListEdit()<CR>`,
+        `  echohl Question | echo 'list — e/<CR> edit · dd delete · q/<Space>l close' | echohl NONE`,
         `endfunction`,
         ``,
         `function! s:Submit() abort`,
@@ -189,7 +251,7 @@ function reviewVimscript() {
         `command! HLList call <SID>List()`,
         `command! HLUndo call <SID>Undo()`,
         `command! HLSubmit call <SID>Submit()`,
-        `command! HLHelp echo 'REVIEW  <Space>c comment (visual or line)   <Space>l list   <Space>u undo-last   <Space>s submit & quit   — or :HLComment/:HLList/:HLUndo/:HLSubmit   (any quit submits)'`,
+        `command! HLHelp echo 'REVIEW  <Space>c comment   <Space>l list   <Space>u undo-last   <Space>s submit & quit   |  in list: e/<CR> edit · dd delete · q close   (any quit submits)'`,
         ``,
         `" Highlights are (re)applied after any colorscheme so the user's theme`,
         `" (e.g. gloam) loads first, then our anchor highlight sits on top.`,
@@ -215,9 +277,51 @@ function reviewVimscript() {
         `  if &filetype !=# 'markdown' | setlocal filetype=markdown | endif`,
         `  " gloam only defines treesitter @markup.* highlight groups for markdown,`,
         `  " so the styling needs treesitter active. Built-in treesitter plus the`,
-        `  " site-dir markdown parser render it with zero plugins.`,
+        `  " site-dir markdown parser render it with zero plugins. When the user has`,
+        `  " render-markdown.nvim installed (lazy dir / packpath), pull it in too so`,
+        `  " GFM tables and headings render the same as their normal editor — it only`,
+        `  " draws extmarks/conceal, so the read-only buffer text (and the line:col`,
+        `  " anchors comments hang off of) is never touched.`,
         `  if has('nvim')`,
-        `    silent! lua pcall(vim.treesitter.start, 0, 'markdown')`,
+        `    silent! lua << HLLUA`,
+        `pcall(vim.treesitter.start, 0, 'markdown')`,
+        `pcall(function()`,
+        `  local path = vim.fn.stdpath('data') .. '/lazy/render-markdown.nvim'`,
+        `  if vim.fn.isdirectory(path) == 0 then`,
+        `    local hits = vim.fn.globpath(vim.o.packpath, '*/*/render-markdown.nvim', false, true)`,
+        `    path = hits[1]`,
+        `  end`,
+        `  if not path or vim.fn.isdirectory(path) == 0 then return end`,
+        `  vim.opt.runtimepath:prepend(path)`,
+        `  vim.g.render_markdown_config = {`,
+        `    file_types = { 'markdown' },`,
+        `    completions = { lsp = { enabled = false } },`,
+        `    heading = { border = false },`,
+        `  }`,
+        `  vim.cmd('silent! runtime plugin/render-markdown.lua')`,
+        `  -- Defer the initial paint to the next tick: during VimEnter the window`,
+        `  -- isn't laid out yet, so an immediate render no-ops and tables show raw`,
+        `  -- until the first cursor move. api.render() forces a paint for the`,
+        `  -- buffer's window (the live autocmds the plugin installed keep it updated`,
+        `  -- on edits/scroll thereafter). render-markdown refuses to draw while a`,
+        `  -- prompt mode is active ('r' hit-enter, 'rm' more, 'r?' confirm) — e.g. a`,
+        `  -- wrapped :echo — so re-defer until we're back in a normal state.`,
+        `  local function paint()`,
+        `    local m = vim.api.nvim_get_mode().mode`,
+        `    if m == 'r' or m == 'rm' or m == 'r?' then`,
+        `      vim.defer_fn(paint, 60)`,
+        `      return`,
+        `    end`,
+        `    pcall(function()`,
+        `      require('render-markdown.api').render({`,
+        `        buf = vim.api.nvim_get_current_buf(),`,
+        `        win = vim.api.nvim_get_current_win(),`,
+        `      })`,
+        `    end)`,
+        `  end`,
+        `  vim.schedule(paint)`,
+        `end)`,
+        `HLLUA`,
         `  endif`,
         `  " Buffer-local <Space> maps. Clean config has no which-key/<leader>`,
         `  " bindings to collide with, and these are gone outside this buffer.`,
@@ -230,11 +334,29 @@ function reviewVimscript() {
         `  call s:Load()`,
         `  call s:Marks()`,
         `  redraw`,
-        `  echohl Question | echo 'hl review — <Space>c comment   <Space>l list   <Space>u undo   <Space>s submit & quit   (:HLHelp)' | echohl NONE`,
+        `  " Keep this hint short: a line that wraps past the cmdline triggers the`,
+        `  " hit-enter prompt, whose mode blocks the deferred render-markdown paint.`,
+        `  " The full key list lives in :HLHelp (and is printed to stderr on launch).`,
+        `  echohl Question | echo 'hl review — <Space>c comment · l list · u undo · s submit  (:HLHelp)' | echohl NONE`,
         `endfunction`,
         `autocmd VimEnter * call s:Setup()`,
         `autocmd VimLeavePre * call s:Save()`,
         ``,
+        `" Watchmode: the source is opened read-only here but may be rewritten on`,
+        `" disk by the agent while the human reviews. autoread + a periodic checktime`,
+        `" (timers fire even when the tmux pane is unfocused) reload the buffer`,
+        `" silently — it is never locally modified, so there is nothing to clobber.`,
+        `" On reload, re-run Setup (read-only guard, treesitter, maps) and redraw the`,
+        `" comment anchors, which the reload cleared. Comments live in s:comments /`,
+        `" the autosave file, not the buffer, so they survive; their line anchors may`,
+        `" drift if the edit moved text, which is expected — the human sees the latest.`,
+        `set autoread`,
+        `autocmd FocusGained,BufEnter,CursorHold * silent! checktime`,
+        `autocmd FileChangedShellPost * call s:Setup() | call s:Marks() | redraw`,
+        `if exists('*timer_start')`,
+        `  let s:hl_watch = timer_start(1000, {-> execute('silent! checktime')}, {'repeat': -1})`,
+        `endif`,
+        ``,
     ].join('\n');
 }
 function atomicWrite(path, data) {
@@ -384,9 +506,12 @@ export async function launchReview(file, opts) {
     }
     const outPath = resolve(opts.output);
     const bin = resolveEditor(opts.editor);
-    const dir = mkdtempSync(join(tmpdir(), 'hl-review-'));
+    // When the async kickoff passes its job dir, source the review.vim the parent
+    // already wrote there; otherwise mint a private temp dir as before.
+    const dir = opts.jobDir ?? mkdtempSync(join(tmpdir(), 'hl-review-'));
     const initPath = join(dir, 'review.vim');
-    writeFileSync(initPath, reviewVimscript());
+    if (!existsSync(initPath))
+        writeFileSync(initPath, reviewVimscript());
     const env = {
         ...process.env,
         HL_OUTPUT: outPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "type": "module",
   "main": "dist/index.js",