k0-board 0.3.0 → 0.5.0

package/platform/darwin/terminal.js

@@ -17,9 +17,17 @@ const PBPASTE = () => which('pbpaste', ['/usr/bin/pbpaste'])
 /** Escape for an AppleScript string literal. */
 const asq = (s) => String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
 
-/** How much of the free screen area a window takes: the rest is margin. */
+/** How much of the free screen area a window takes unless somebody asks for more. */
 const COVERAGE = 0.86
 
+/**
+ * How long a pass over the open windows may take. The five seconds `run` gives every other
+ * command is not enough for this one: Terminal answers in its own time, and a pass killed
+ * halfway through leaves half the windows changed and the other half as they were — which is
+ * precisely the failure this file used to have.
+ */
+const PASS_TIMEOUT = 20000
+
 /** In driving mode the terminal has to be readable from across the room. */
 export const DRIVING_FONT_SIZE = 22
 
@@ -38,13 +46,17 @@ export async function defaultFontSize() {
 
 /**
  * The piece of AppleScript that decides where a window goes and how big it is. It is written
- * once because two callers need it — the one that opens a new window and the one that puts
- * them back after the screen changes — and the rule has to be the same for both: otherwise
- * the first time a monitor is unplugged every window would change size for no reason.
+ * once because three callers need it — the one that opens a new window, the one that puts them
+ * back after the screen changes, and the one that follows the mode — and the rule has to be the
+ * same for all of them: otherwise the first time a monitor is unplugged every window would
+ * change size for no reason.
+ *
+ * `coverage` is how much of the free area the window takes: the usual share, or all of it when
+ * the mode wants windows readable from across the room.
  *
  * Leaves `x1`, `y1`, `w` and `h` behind, which is what `bounds` needs.
  */
-const GEOMETRY = `
+const geometry = (coverage = COVERAGE) => `
 use framework "AppKit"
 use scripting additions
 
@@ -53,8 +65,8 @@ use scripting additions
 set scr to current application's NSScreen's mainScreen()
 set frameH to item 2 of item 2 of (scr's frame() as list)
 set {{vx, vy}, {vw, vh}} to (scr's visibleFrame() as list)
-set w to round (vw * ${COVERAGE})
-set h to round (vh * ${COVERAGE})
+set w to round (vw * ${coverage})
+set h to round (vh * ${coverage})
 set x1 to round (vx + (vw - w) / 2)
 -- NSScreen counts from the bottom, Terminal from the top: this converts between them.
 set y1 to round (frameH - (vy + vh) + (vh - h) / 2)
@@ -74,9 +86,9 @@ set y1 to round (frameH - (vy + vh) + (vh - h) / 2)
  * - the window is sized BEFORE the command runs, so Claude Code's interface is born at the
  *   right size instead of having to redraw itself halfway through starting up.
  */
-export async function open({ command, title, fontSize }) {
+export async function open({ command, title, fontSize, coverage }) {
   const font = fontSize ?? (await defaultFontSize())
-  const script = `${GEOMETRY}
+  const script = `${geometry(coverage)}
 tell application "Terminal"
   activate
   do script ""
@@ -84,7 +96,7 @@ tell application "Terminal"
   set font size of tab 1 of win to ${font}
   set bounds of win to {x1, y1, x1 + w, y1 + h}
   do script "${asq(command)}" in tab 1 of win
-  -- The card's name in the title bar, not the command line with the session id in it.
+  -- The story's name in the title bar, not the command line with the session id in it.
   set custom title of tab 1 of win to "${asq(title)}"
   set winId to id of win
 end tell
@@ -96,65 +108,96 @@ return winId as string`
 const ids = (handles) => [...new Set((handles || []).map(Number).filter(Boolean))]
 
 /**
- * One `osascript` for every window, each in its own `try`.
+ * One `osascript` for the lot: it walks Terminal's OWN windows once and touches those whose id
+ * k0 asked about.
+ *
+ * The obvious shape is a `try` block per id, and it is the one that broke. k0 hands over the
+ * window id of every story it has ever opened — 218 of them on the board where this was found —
+ * and nearly all of them name a window closed weeks ago. Each dead id costs AppleScript an error
+ * to raise and swallow, about 33 milliseconds of it: the script took 7.4 seconds against the 5
+ * second limit on `run`, was killed halfway through, and the `catch` below read that as
+ * "Terminal is not running". Half the windows had changed, half had not, and nothing anywhere
+ * said so. It worked in the morning and stopped in the afternoon because the list only grows.
  *
- * The per-window `try` is there so that one window closed by hand in the meantime does not
- * take all the others down with it. And there is deliberately **no `activate`**: opening a
- * window needs Terminal in front, touching one that is already open does not — otherwise
- * every time you switch driving mode on or plug in a monitor, Terminal would jump in front
- * of whatever you were doing.
+ * Walking the windows that are actually open costs about a second and stops growing with the
+ * board's history: an id naming nothing simply never matches. The count comes back from
+ * AppleScript itself instead of being assumed, so the caller learns how many windows really
+ * moved, and a failure comes back as a sentence instead of as a zero.
+ *
+ * There is deliberately no `activate`: opening a window needs Terminal in front, touching one
+ * that is already open does not — otherwise every mode you clicked would bring Terminal forward
+ * over whatever you were doing.
+ *
+ * @returns {Promise<{touched: number, error?: string}>}
  */
-async function forEachWindow(preamble, body, list) {
-  const blocks = list.map((id) => `\n  try${body(id)}\n  end try`).join('')
+async function eachWindow(preamble, body, list) {
   try {
-    await run(OSASCRIPT(), ['-e', `${preamble}\ntell application "Terminal"${blocks}\nend tell`])
-    return { touched: list.length }
-  } catch {
-    return { touched: 0 } // Terminal is not running at all: there is nothing to touch
+    const out = await run(OSASCRIPT(), ['-e', windowPass(preamble, body, list)], { timeout: PASS_TIMEOUT })
+    return { touched: Number(String(out).trim()) || 0 }
+  } catch (err) {
+    return { touched: 0, error: String(err?.message || err).split('\n')[0].trim() }
   }
 }
 
 /**
- * Changes the font size of windows that are already open — which is what happens when
- * driving mode goes on or off.
+ * The script itself, kept apart from the running of it so that a test can read the shape
+ * without a Terminal to drive: whether the pass is one walk over the windows or the old walk
+ * over the ids is the whole point of this file, and it is worth being able to check.
+ */
+export const windowPass = (preamble, body, list) => `${preamble}
+set wanted to {${list.join(', ')}}
+set touched to 0
+tell application "Terminal"
+  repeat with win in windows
+    if (id of win) is in wanted then${body('win')}
+      set touched to touched + 1
+    end if
+  end repeat
+end tell
+return touched as string`
+
+/**
+ * Puts the windows k0 owns the way the mode wants them: the text at `fontSize`, the window at
+ * `coverage` of the free screen. Both in the same pass, deliberately.
  *
- * **Every window stays exactly where and as it is.** That is worth saying because it is not
- * free: Terminal.app keeps rows and columns when the font changes and resizes the window
- * accordingly — going from 12 to 22 more than doubles it. So the bounds are read first, the
- * font is changed, and the bounds are put back: **its own** bounds, not the centred ones.
- * k0's windows have rarely stayed where they were born — you move them, widen them, drag one
- * to the other monitor — and turning on driving mode is not the moment to sweep them all
- * back to the middle of the screen without being asked.
+ * They used to be two separate ideas. The font changed and the window was carefully put back
+ * exactly where it was, on the grounds that turning driving mode on is not the moment to sweep
+ * every window back to the middle of the screen. What that left behind was a window holding 22
+ * point text in a box measured for 12: the size of the text and the size of the window are one
+ * gesture, and doing half of it is worse than doing neither.
  *
- * What genuinely changes is how much text fits: at 22 points, fewer rows.
+ * The font goes first: Terminal keeps rows and columns when the font changes and resizes the
+ * window to match, so the bounds have to be set after it or they would be eaten.
+ *
+ * The price, said plainly because the old behaviour promised the opposite: a window you had
+ * dragged onto another screen comes back to the middle of the main one.
  */
-export async function setFont(handles, size) {
+export async function applyMode(handles, { fontSize, coverage } = {}) {
   const list = ids(handles)
   if (!list.length) return { touched: 0 }
-  const font = size ?? (await defaultFontSize())
-  return forEachWindow(
-    '',
-    (id) => `
-    set b to bounds of window id ${id}
-    set font size of tab 1 of window id ${id} to ${font}
-    set bounds of window id ${id} to b`,
+  const font = fontSize ?? (await defaultFontSize())
+  return eachWindow(
+    geometry(coverage),
+    (win) => `
+      set font size of tab 1 of ${win} to ${font}
+      set bounds of ${win} to {x1, y1, x1 + w, y1 + h}`,
     list
   )
 }
 
 /**
- * Puts the windows back in the middle of the screen at their usual size: what is needed when
- * the screen changes underneath them — a monitor plugged in or unplugged, a different
- * resolution — and the windows stay where they were, out of place or off screen.
+ * Puts the windows back in the middle of the screen at the size the mode asks for: what is
+ * needed when the screen changes underneath them — a monitor plugged in or unplugged, a
+ * different resolution — and the windows stay where they were, out of place or off screen.
  *
  * Here gathering them back to the centre is the point: they all end up where they were born,
  * as they were on the first day. The geometry is computed once for all of them, so none ends
  * up on a different screen from its siblings.
  */
-export async function relayout(handles) {
+export async function relayout(handles, { coverage } = {}) {
   const list = ids(handles)
   if (!list.length) return { touched: 0 }
-  return forEachWindow(GEOMETRY, (id) => `\n    set bounds of window id ${id} to {x1, y1, x1 + w, y1 + h}`, list)
+  return eachWindow(geometry(coverage), (win) => `\n      set bounds of ${win} to {x1, y1, x1 + w, y1 + h}`, list)
 }
 
 /**
@@ -179,30 +222,76 @@ export async function setTitle(handle, title) {
   }
 }
 
-/**
- * Brings the card's window back to the front, un-minimising it if it was parked.
- * Keeps you from losing track of which terminal is which.
- */
-export async function focus(handle) {
-  const id = Number(handle)
-  if (!id) return { ok: false, error: 'This card has no terminal window of its own' }
-  const script = `
+const raise = (id) => `
 tell application "Terminal"
   activate
   set w to window id ${id}
   set miniaturized of w to false
   set index of w to 1
 end tell`
+
+/**
+ * The window whose tab is called `title`, as an id — or nothing.
+ *
+ * Terminal's window ids do not survive Terminal being quit and reopened, and a session detached
+ * into a window somebody rearranged can end up behind an id k0 wrote down and that now belongs to
+ * nothing. The custom title `open()` sets is the other name the window has, and it is the one
+ * that survives: this is how a window k0 lost is found again rather than declared gone.
+ */
+async function byTitle(title) {
+  if (!title) return null
+  const script = `
+tell application "Terminal"
+  repeat with w in windows
+    try
+      if custom title of tab 1 of w is "${asq(title)}" then return id of w as string
+    end try
+  end repeat
+end tell
+return ""`
   try {
-    await run(OSASCRIPT(), ['-e', script])
-    return { ok: true }
+    return String(await run(OSASCRIPT(), ['-e', script])).trim() || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Brings the story's window back to the front, un-minimising it if it was parked.
+ * Keeps you from losing track of which terminal is which.
+ *
+ * `title` is the story's name, and it is the second way of finding the window. When the id no
+ * longer answers, the window is looked for by name before anybody is told it is gone — and the id
+ * that was found comes back with the answer, so the caller can write down the one that works
+ * instead of asking twice for the same thing.
+ */
+export async function focus(handle, title) {
+  const id = Number(handle)
+  if (id) {
+    try {
+      await run(OSASCRIPT(), ['-e', raise(id)])
+      return { ok: true }
+    } catch {
+      // Fall through: the id is stale, which is not the same as the window being gone.
+    }
+  }
+  const found = await byTitle(title)
+  if (!found) {
+    return {
+      ok: false,
+      error: id ? 'That window is gone' : 'This story has no terminal window of its own',
+    }
+  }
+  try {
+    await run(OSASCRIPT(), ['-e', raise(Number(found))])
+    return { ok: true, handle: found }
   } catch {
     return { ok: false, error: 'That window is gone' }
   }
 }
 
 /**
- * Closes a card's terminal: stops the session first, then closes the window.
+ * Closes a story's terminal: stops the session first, then closes the window.
  *
  * The order is not a detail. Closing a window that still has `claude` inside it makes macOS
  * put up the "terminate running processes" dialog and sit there waiting: the window does not
@@ -313,12 +402,97 @@ export async function type(text, handle) {
   }
 }
 
+/** Who has the keyboard right now: the frontmost process, and Terminal's front window if it is Terminal. */
+async function keyboard() {
+  let app = ''
+  try {
+    app = String(
+      await run(OSASCRIPT(), [
+        '-e',
+        'tell application "System Events" to get name of first application process whose frontmost is true',
+      ])
+    ).trim()
+  } catch {
+    /* System Events not answering: nobody, as far as we can tell */
+  }
+  let window = null
+  if (app === 'Terminal') {
+    try {
+      window = Number(await run(OSASCRIPT(), ['-e', 'tell application "Terminal" to get id of front window'])) || null
+    } catch {
+      /* no window in front */
+    }
+  }
+  return { app, window }
+}
+
+/**
+ * Runs a slash command inside the session: `/rename Foo`.
+ *
+ * Only keystrokes will do. `do script` — what `type` uses — writes the line in one block, and
+ * Claude Code takes a block as a message: `/rename Foo` typed that way was answered by the
+ * model explaining that it cannot rename the session. Typed key by key through System Events it
+ * runs. That needs the Accessibility permission, the same one `paste` needs, so without it the
+ * answer is an honest no.
+ *
+ * Never by raising the window. Keystrokes go to whatever is in front, and this was first written
+ * to bring the window up, type, and hand the keyboard back — and while it did, what the person at
+ * the keyboard was typing into another window landed in the box in front of the command. So the
+ * command is typed only when that window already has the keyboard, which is to say when you are
+ * looking at it; the caller comes back later otherwise.
+ *
+ * Verified before Enter, never blindly. Claude Code talks to the terminal now and then, and a
+ * key that lands in the middle of that exchange comes out as junk in front of the slash —
+ * `ltr/rename Foo`, seen — which Claude Code then reads as a message. So after the keys the line
+ * under the cursor is read back, and Enter is pressed only if it is exactly the command; anything
+ * else is deleted, a keystroke per character, and the caller is told.
+ */
+export async function command(text, handle, { ready, verify }) {
+  const id = Number(handle)
+  if (!id) return { sent: false, why: 'This story has no terminal window of its own' }
+  const now = await keyboard()
+  if (now.app !== 'Terminal' || now.window !== id) return { sent: false, why: 'The window is not in front' }
+  if (!ready(await readScreen(id))) return { sent: false, why: 'The input box is not free' }
+  // Takes away whatever is under the cursor. Generous on purpose: the box is empty once there is
+  // nothing left, and a Backspace on an empty box does nothing.
+  const clear = () =>
+    run(OSASCRIPT(), [
+      '-e',
+      `tell application "System Events"\n  repeat ${text.length + 16} times\n    key code 51\n  end repeat\nend tell`,
+    ])
+  try {
+    let why = 'The keys did not land clean'
+    // Twice at most: the junk is a matter of timing, and the second go usually lands.
+    for (let attempt = 0; attempt < 2; attempt++) {
+      await run(OSASCRIPT(), ['-e', `tell application "System Events" to keystroke "${asq(text)}"`])
+      await new Promise((r) => setTimeout(r, 400))
+      if (verify(await readScreen(id))) {
+        // Enter, and proof that it went in: a key event is posted, not delivered, and one can
+        // miss — seen, with the command left sitting in the box.
+        for (let enter = 0; enter < 2; enter++) {
+          await run(OSASCRIPT(), ['-e', 'tell application "System Events" to key code 36'])
+          await new Promise((r) => setTimeout(r, 400))
+          if (!verify(await readScreen(id))) return { sent: true }
+        }
+        why = 'Enter did not go in'
+      }
+      // Wrong line under the cursor, or the right one that will not go: take it away rather than
+      // leave it — a box with a stray command in it is one nobody can type into.
+      await clear()
+    }
+    return { sent: false, why }
+  } catch (err) {
+    return { sent: false, why: String(err.stderr || err.message).trim() }
+  }
+}
+
 export const capabilities = {
   windows: true,
   font: true,
   readScreen: true,
   pasteWithoutSending: true,
   title: true,
+  commands: true,
 }
 
 export { posixCommand as buildCommand } from '../shared/command.js'

package/platform/index.js

@@ -33,13 +33,14 @@ const unsupported = {
       throw new Error(`k0 cannot open terminals on ${process.platform} yet.`)
     },
     setTitle: async () => false,
-    setFont: async () => ({ touched: 0 }),
+    applyMode: async () => ({ touched: 0 }),
     relayout: async () => ({ touched: 0 }),
     focus: async () => ({ ok: false, error: `Not supported on ${process.platform}` }),
     close: async () => ({ closed: false }),
     readScreen: async () => null,
     paste: async () => ({ pasted: false }),
     type: async () => ({ written: false }),
+    command: async () => ({ sent: false, why: `Not supported on ${process.platform}` }),
     defaultFontSize: async () => 12,
   },
   power: {
@@ -65,6 +66,7 @@ const unsupported = {
   },
   shell: {
     revealInFileManager: async () => {},
+    openInFileManager: async () => {},
     openBrowser: async () => {},
     findChrome: () => null,
     homeSkipList: () => new Set(),

package/platform/linux/index.js

@@ -24,6 +24,7 @@ export const capabilities = {
   service: service.capabilities(),
   tray: !!which('python3'),
   revealInFileManager: shell.capabilities().revealInFileManager,
+  openInFileManager: shell.capabilities().openInFileManager,
 }
 
 export const notes = {
@@ -51,6 +52,9 @@ export const notes = {
     'Font size belongs to your terminal emulator and every one of them spells it differently, ' +
     'so driving mode enlarges the board but not the terminals. Set a bigger font in your ' +
     'emulator’s own preferences if you want both.',
+  'terminal.commands':
+    'Renaming a story renames its Claude Code session only once the session has ended: k0 has ' +
+    'not yet been seen to run /rename inside a live session through tmux, so it does not try.',
   ...(capabilities.tray
     ? {}
     : { tray: 'python3 with PyGObject is needed for a tray icon. The board works without it.' }),
@@ -61,6 +65,16 @@ export const notes = {
           'Neither ss nor lsof was found, so k0 cannot see which port a dev server is listening ' +
           'on. Install iproute2 (for ss) and the globe will know where to send you.',
       }),
+  ...(capabilities.openInFileManager
+    ? {}
+    : {
+        revealInFileManager:
+          'xdg-open was not found, so k0 has no way to hand a file or a folder to your file ' +
+          'manager. Install xdg-utils and the button will work.',
+        openInFileManager:
+          'xdg-open was not found, so k0 has no way to hand a file or a folder to your file ' +
+          'manager. Install xdg-utils and the button will work.',
+      }),
   ...(capabilities.servers.adopt
     ? {}
     : {

package/platform/linux/shell.js

@@ -31,6 +31,15 @@ export async function revealInFileManager(abs) {
   if (open) await runQuiet(open, [path.dirname(abs)])
 }
 
+/**
+ * Opening a directory needs none of the dance above: every desktop that has a file manager at
+ * all hands a directory to it through xdg-open.
+ */
+export async function openInFileManager(abs) {
+  const open = XDG_OPEN()
+  if (open) await runQuiet(open, [abs])
+}
+
 export const openBrowser = (url) => run(XDG_OPEN(), [url], { timeout: 4000 })
 
 const CHROME_CANDIDATES = [
@@ -94,4 +103,4 @@ export function findClaude() {
   return claudeBin
 }
 
-export const capabilities = () => ({ revealInFileManager: !!XDG_OPEN() })
+export const capabilities = () => ({ revealInFileManager: !!XDG_OPEN(), openInFileManager: !!XDG_OPEN() })

package/platform/linux/tray.py

@@ -152,7 +152,7 @@ def _forget(notification):
         _shown.remove(notification)
 
 
-def notify(card_id, title, body):
+def notify(story_id, title, body):
     """Say that a session is waiting, and let the click take you to it.
 
     The action is named `default`, which is what a notification daemon calls the click on the
@@ -163,7 +163,7 @@ def notify(card_id, title, body):
     if Notify is not None:
         try:
             note = Notify.Notification.new(title, body, None)
-            note.add_action("default", "Open", lambda *_: api(f"/api/card/{card_id}/focus", {}))
+            note.add_action("default", "Open", lambda *_: api(f"/api/story/{story_id}/focus", {}))
             note.connect("closed", _forget)
             _shown.append(note)
             if note.show():
@@ -212,12 +212,12 @@ class Tray:
         return True
 
     def announce(self, waiting):
-        """Notify about cards that have just started waiting, not about every one every time."""
-        now = {(card["id"], card["status"]) for card in waiting}
+        """Notify about stories that have just started waiting, not about every one every time."""
+        now = {(story["id"], story["status"]) for story in waiting}
         if not self.first_pass:
-            for card in waiting:
-                if (card["id"], card["status"]) not in self.seen:
-                    notify(card["id"], LABELS.get(card["status"], "k0"), card.get("title", ""))
+            for story in waiting:
+                if (story["id"], story["status"]) not in self.seen:
+                    notify(story["id"], LABELS.get(story["status"], "k0"), story.get("title", ""))
         self.seen = now
         self.first_pass = False
 
@@ -231,9 +231,9 @@ class Tray:
         elif not waiting:
             self.add_item("Nothing waiting for you", None, enabled=False)
         else:
-            for card in waiting:
-                label = f"{LABELS.get(card['status'], card['status'])} — {card.get('title', '')}"
-                self.add_item(label, lambda _w, c=card: api(f"/api/card/{c['id']}/focus", {}))
+            for story in waiting:
+                label = f"{LABELS.get(story['status'], story['status'])} — {story.get('title', '')}"
+                self.add_item(label, lambda _w, c=story: api(f"/api/story/{c['id']}/focus", {}))
 
         self.menu.append(Gtk.SeparatorMenuItem())
         for value, label in MODES:

package/platform/shared/command.js

@@ -8,18 +8,34 @@
  * a prompt passed as an argument can contain anything at all.
  */
 
+/**
+ * The environment the program is started with, as name/value pairs. A value is quoted like
+ * everything else; a name cannot be quoted at all — it sits bare in front of an `=` — so anything
+ * that is not plainly a name is refused before it can reach a shell.
+ */
+const envPairs = (env = {}) =>
+  Object.entries(env).map(([name, value]) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`not an environment variable name: ${JSON.stringify(name)}`)
+    return [name, value]
+  })
+
 /** POSIX single quotes: everything is literal inside them, and a quote ends and reopens them. */
 export const posixQuote = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`
 
-export const posixCommand = ({ cwd, bin, args = [] }) =>
-  ['cd', posixQuote(cwd), '&&', posixQuote(bin), ...args.map(posixQuote)].join(' ')
+// Through `env` rather than a bare `NAME=value` in front: the terminal hands the line to whatever
+// shell the user logs in with, and `env` reads the same in sh, zsh and fish alike.
+export const posixCommand = ({ cwd, bin, args = [], env }) => {
+  const pairs = envPairs(env).map(([name, value]) => `${name}=${posixQuote(value)}`)
+  return ['cd', posixQuote(cwd), '&&', ...(pairs.length ? ['env', ...pairs] : []), posixQuote(bin), ...args.map(posixQuote)].join(' ')
+}
 
 /** PowerShell single quotes: same idea, but a quote is escaped by doubling it. */
 export const powershellQuote = (s) => `'${String(s).replace(/'/g, "''")}'`
 
-export const powershellCommand = ({ cwd, bin, args = [] }) =>
+export const powershellCommand = ({ cwd, bin, args = [], env }) =>
   [
     `Set-Location ${powershellQuote(cwd)};`,
+    ...envPairs(env).map(([name, value]) => `$env:${name}=${powershellQuote(value)};`),
     '&',
     powershellQuote(bin),
     ...args.map(powershellQuote),