k0-board 0.4.0 → 0.6.0

package/bin/k0-board.js

@@ -75,6 +75,22 @@ function copyTree(from, to) {
   }
 }
 
+/** The same files, byte for byte, and no others — on either side. */
+function sameTree(a, b) {
+  const files = (dir) =>
+    fs
+      .readdirSync(dir, { withFileTypes: true, recursive: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => path.relative(dir, path.join(entry.parentPath, entry.name)))
+      .sort()
+  const left = files(a)
+  const right = files(b)
+  return (
+    left.length === right.length &&
+    left.every((f, i) => f === right[i] && fs.readFileSync(path.join(a, f)).equals(fs.readFileSync(path.join(b, f))))
+  )
+}
+
 // ── The tray icon ────────────────────────────────────────────────────────────
 /**
  * The three trays are three different things — a compiled Swift app, a Python script, a
@@ -258,7 +274,7 @@ async function install() {
     note(`Where: ${extra.target}`)
   }
 
-  // Last of all, on purpose: by now the imported cards are on the board, so what opens is
+  // Last of all, on purpose: by now the imported stories are on the board, so what opens is
   // somebody's own work rather than an empty grid they would have to reload.
   if (up && !flag('no-open')) {
     say(`\n${bold('Done.')} The board is open at ${await openBoard()}`)
@@ -268,23 +284,74 @@ async function install() {
   if (process.platform === 'win32') note(`If that name does not resolve, use http://127.0.0.1:${PORT}`)
 }
 
+// The commands you type at Claude Code, and every one of them ships in the package. Claude Code
+// only ever looks in two places for a skill — the repository you have open, and your own
+// `~/.claude/skills/` — and neither of them is where npm puts k0, so a command that is not copied
+// out is a command that does not exist however carefully it was written. `k0-whatsnew` and
+// `k0-changelog` are deliberately not here: k0 runs those two itself, from its own directory, and
+// nobody types them.
+const SKILLS = [
+  ['k0-import', 'fills the board from sessions you already have'],
+  ['k0-epic', 'an epic, discussed in rounds, then a tree of stories'],
+  ['k0-story', 'one story, straight onto the board'],
+  ['k0-discuss', 'the same rounds against a story that exists'],
+  ['k0-split', 'a story that will not close, cut into tasks'],
+  ['k0-plan', 'plan mode, with the decisions written in as constraints'],
+  ['k0-work', 'the worktree, the work, the log, the merge back'],
+  ['k0-ultracode', 'a whole epic, run by a manager with agents under it'],
+  ['k0-verify', 'the counter-check, one decision at a time'],
+  ['k0-next', 'what to pick up now, and why'],
+  ['k0-order', 'priority and dependencies, dictated'],
+  // Not a command but a mod: nobody types it, Claude Code loads it from the same directory and it
+  // turns the files and artifacts named in a reply into links while k0 is running.
+  ['k0-links', 'what the last reply pointed at, one click away above the prompt', 'mod'],
+]
+
+/** How the list shows an entry: a command by what you type, the mod by its name. */
+const shown = ([name, , kind]) => (kind === 'mod' ? name : `/${name}`)
+
 /**
- * The import skill lives in the repository, which is enough for anybody who cloned it. For
- * anybody who installed with one command there is no repository to open Claude Code in, so it is
- * offered as a copy into their own skills directory — where it works from any project.
+ * The skills live in the repository, which is enough for anybody who cloned it. For anybody who
+ * installed with one command there is no repository to open Claude Code in, so they are offered
+ * as a copy into their own skills directory — where they work from any project.
+ *
+ * One question for all of them, and it is asked only about the ones that are not already there:
+ * somebody upgrading has answered it once, and being asked ten times is how a yes becomes a no.
+ *
+ * The ones that are already there are brought up to date without asking, for the same reason. A
+ * copy is taken once and Claude Code reads it from then on, so a command fixed in a new version
+ * went on running the old text for good — the yes was to having the commands, not to having the
+ * first version of them.
  */
 async function offerSkill() {
-  const from = path.join(APP_DIR, '.claude', 'skills', 'k0-import')
-  const to = path.join(os.homedir(), '.claude', 'skills', 'k0-import')
-  if (!fs.existsSync(from) || fs.existsSync(to)) return
+  const home = path.join(os.homedir(), '.claude', 'skills')
+  const source = (name) => path.join(APP_DIR, '.claude', 'skills', name)
+  const shipped = SKILLS.filter(([name]) => fs.existsSync(source(name)))
+
+  const stale = shipped.filter(([name]) => fs.existsSync(path.join(home, name)) && !sameTree(source(name), path.join(home, name)))
+  for (const [name] of stale) {
+    fs.rmSync(path.join(home, name), { recursive: true, force: true })
+    copyTree(source(name), path.join(home, name))
+  }
+  if (stale.length) ok(`brought up to date in ${home}: ${stale.map(shown).join(', ')}`)
+
+  const missing = shipped.filter(([name]) => !fs.existsSync(path.join(home, name)))
+  if (!missing.length) return
   say('')
+  for (const entry of missing) note(`${bold(shown(entry))} ${dim(`— ${entry[1]}`)}`)
+  const commands = missing.filter(([, , kind]) => kind !== 'mod').length
+  const mods = missing.length - commands
+  const what = [
+    commands && `${bold(String(commands))} ${commands === 1 ? 'command' : 'commands'}`,
+    mods && `${mods === 1 ? 'the mod' : `${bold(String(mods))} mods`}`,
+  ].filter(Boolean).join(' and ')
   const yes = await confirm(
-    `Install the ${bold('/k0-import')} skill for Claude Code? ${dim('(fills the board from sessions you already have)')}`,
+    `Install ${what} for Claude Code?`,
     { fallback: true }
   )
   if (!yes) return
-  copyTree(from, to)
-  ok(`copied into ${to}`)
+  for (const [name] of missing) copyTree(path.join(APP_DIR, '.claude', 'skills', name), path.join(home, name))
+  ok(`copied into ${home}`)
 }
 
 /**
@@ -327,7 +394,7 @@ async function offerImport() {
     const res = await api('/api/sessions/import', { items: items.slice(i, i + 30) })
     created += res.created
   }
-  ok(`${created} cards on the board`)
+  ok(`${created} stories on the board`)
   note('Run /k0-import inside Claude Code for titles written by reading the conversation.')
 }
 
@@ -404,12 +471,15 @@ async function doctor() {
   else if (state.running) warn('the service is running but the server is not answering')
   else warn('not running — `k0-board install` or `k0-board start`')
 
+  await cloudReport()
+
   step('What this machine can do')
   const rows = [
     ['open terminals', capabilities.terminal.pasteWithoutSending || capabilities.terminal.readScreen],
     ['place and raise windows', capabilities.terminal.windows],
     ['read a terminal to know when Claude Code is ready', capabilities.terminal.readScreen],
     ['leave a prompt unsent', capabilities.terminal.pasteWithoutSending],
+    ['rename a running session when its title changes', capabilities.terminal.commands],
     ['resize the terminal font for driving mode', capabilities.terminal.font],
     ['keep the machine awake', capabilities.power.keepAwake],
     ['keep the screen awake', capabilities.power.keepDisplayAwake],
@@ -446,6 +516,49 @@ async function doctor() {
   }
 }
 
+// ── k0 Cloud ─────────────────────────────────────────────────────────────────
+/**
+ * Signing in happens in the browser, on the board: that is where GitHub or Google send you back
+ * to. So this opens the board, which shows the way in when nobody is signed in yet, and says
+ * where things stand when somebody is.
+ */
+async function login() {
+  if (!(await alive())) {
+    fail('k0 is not running — `k0-board install` or `k0-board start` first')
+    process.exit(1)
+  }
+  const s = await api('/api/cloud')
+  if (!s.enabled) return warn('k0 Cloud is switched off on this machine (K0_CLOUD=off)')
+  if (s.linked && s.approved) return ok(`signed in as ${s.email || s.name}`)
+  if (s.linked) return note(`signed in as ${s.email || s.name}, waiting to be let in — the board notices by itself`)
+  const url = await openBoard()
+  say(`Sign in on the board: ${url}`)
+}
+
+async function logout() {
+  if (!(await alive())) {
+    fail('k0 is not running')
+    process.exit(1)
+  }
+  await api('/api/cloud/logout', {})
+  ok('signed out — the board stays on this machine, and stops syncing')
+}
+
+async function cloudReport() {
+  step('k0 Cloud')
+  if (!(await alive())) return warn('the server is not running, so there is nothing to ask')
+  const s = await api('/api/cloud').catch(() => null)
+  if (!s) return warn('the server did not say')
+  if (!s.enabled) return warn('switched off on this machine (K0_CLOUD=off)')
+  if (!s.linked) return warn('nobody is signed in — `k0-board login`')
+  ok(`signed in as ${s.email || s.name}`)
+  ;(s.approved ? ok : warn)(s.approved ? 'let in' : 'waiting to be let in')
+  if (s.needs_move) warn('the board on this machine has not been moved to the account yet — the board offers it')
+  ;(s.online === false ? warn : ok)(s.online === false ? 'k0 Cloud cannot be reached right now' : 'k0 Cloud answers')
+  if (s.pending) note(`${s.pending} change${s.pending === 1 ? '' : 's'} waiting to go up`)
+  if (s.sync_error) warn(s.sync_error)
+}
+
 // ── the rest ─────────────────────────────────────────────────────────────────
 async function restart() {
   await service.restart()
@@ -479,6 +592,8 @@ ${bold('k0-board')} — a board of sticky notes that drives your Claude Code ses
   ${bold('k0-board restart')}     restart the service
   ${bold('k0-board status')}      is it running?
   ${bold('k0-board doctor')}      what this machine can and cannot do, and why
+  ${bold('k0-board login')}       sign in to k0 Cloud with GitHub or Google (on the board)
+  ${bold('k0-board logout')}      sign out; the board stays on this machine
 
 Options
   ${bold('--yes')}            do not ask, assume yes
@@ -488,7 +603,7 @@ Options
 `)
 }
 
-const commands = { install, uninstall, start, restart, status, doctor, 'shift-enter': shiftEnter }
+const commands = { install, uninstall, start, restart, status, doctor, login, logout, 'shift-enter': shiftEnter }
 
 if (flag('help') || flag('h') || command === 'help') {
   usage()

package/menubar/K0MenuBar.swift

@@ -113,6 +113,11 @@ final class ImagePaste {
         try? FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
         clearOld()
         Timer.scheduledTimer(withTimeInterval: 0.3, repeats: true) { _ in self.tick() }
+        // And again every ten minutes, which is the whole fix. Swept only here, `clearOld` tidied
+        // away the images of the session before this one and then never ran again: this app starts
+        // at login and stays up for weeks, so the folder simply grew — to 907 MB across 414
+        // screenshots, none of which anybody could still paste.
+        Timer.scheduledTimer(withTimeInterval: 600, repeats: true) { _ in self.clearOld() }
         NSLog("k0: image pasting active (no permission required)")
     }
 
@@ -154,15 +159,40 @@ final class ImagePaste {
         return rep.representation(using: .png, properties: [:])
     }
 
-    /// Yesterday's images are of no use to anybody.
+    /// How long an image is worth keeping, and how much of it there may be at once.
+    ///
+    /// Age alone was never a bound. One screenshot off a large display is ten megabytes, so an
+    /// afternoon of them can outgrow the disk long before anything is a day old — which is exactly
+    /// what happened. Past the ceiling the oldest go first, so what is left is what you might still
+    /// be about to paste.
+    private static let keepFor: TimeInterval = 86400
+    private static let keepUnder = 200 * 1024 * 1024
+
+    /// Yesterday's images are of no use to anybody, and neither is a gigabyte of today's.
     private func clearOld() {
-        let cutoff = Date().addingTimeInterval(-86400)
         let f = FileManager.default
-        guard let files = try? f.contentsOfDirectory(at: folder, includingPropertiesForKeys: [.contentModificationDateKey])
+        let keys: [URLResourceKey] = [.contentModificationDateKey, .fileSizeKey]
+        guard let files = try? f.contentsOfDirectory(at: folder, includingPropertiesForKeys: keys)
         else { return }
+
+        let cutoff = Date().addingTimeInterval(-Self.keepFor)
+        var kept: [(url: URL, at: Date, size: Int)] = []
         for u in files {
-            let date = (try? u.resourceValues(forKeys: [.contentModificationDateKey]))?.contentModificationDate
-            if let date, date < cutoff { try? f.removeItem(at: u) }
+            let values = try? u.resourceValues(forKeys: Set(keys))
+            let at = values?.contentModificationDate ?? Date.distantPast
+            if at < cutoff {
+                try? f.removeItem(at: u)
+                continue
+            }
+            kept.append((u, at, values?.fileSize ?? 0))
+        }
+
+        var total = kept.reduce(0) { $0 + $1.size }
+        guard total > Self.keepUnder else { return }
+        for one in kept.sorted(by: { $0.at < $1.at }) {
+            if total <= Self.keepUnder { break }
+            try? f.removeItem(at: one.url)
+            total -= one.size
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k0-board",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A board of sticky notes that drives your Claude Code sessions",
   "keywords": [
     "claude-code",
@@ -16,7 +16,7 @@
     "type": "git",
     "url": "git+https://github.com/alessio-ragni/k0-board.git"
   },
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "author": "Alessio Ragni (https://alessioragni.com)",
   "type": "module",
   "bin": {
@@ -34,6 +34,18 @@
     "!menubar/k0.app",
     ".claude/skills/k0-import",
     ".claude/skills/k0-changelog",
+    ".claude/skills/k0-epic",
+    ".claude/skills/k0-story",
+    ".claude/skills/k0-plan",
+    ".claude/skills/k0-work",
+    ".claude/skills/k0-ultracode",
+    ".claude/skills/k0-discuss",
+    ".claude/skills/k0-split",
+    ".claude/skills/k0-order",
+    ".claude/skills/k0-verify",
+    ".claude/skills/k0-next",
+    ".claude/skills/k0-whatsnew",
+    ".claude/skills/k0-links",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/platform/contract.js

@@ -25,6 +25,7 @@
  * @property {boolean} terminal.readScreen           can read back what is on screen
  * @property {boolean} terminal.pasteWithoutSending  can leave a prompt sitting unsent
  * @property {boolean} terminal.title                can rename a window from outside
+ * @property {boolean} terminal.commands             can run a slash command inside a live session
  * @property {object} power
  * @property {boolean} power.keepAwake               can stop idle sleep
  * @property {boolean} power.keepDisplayAwake        can stop the display sleeping
@@ -49,7 +50,14 @@
  * so a capability added here later defaults to "no" everywhere instead of crashing.
  */
 export const NO_CAPABILITIES = {
-  terminal: { windows: false, font: false, readScreen: false, pasteWithoutSending: false, title: false },
+  terminal: {
+    windows: false,
+    font: false,
+    readScreen: false,
+    pasteWithoutSending: false,
+    title: false,
+    commands: false,
+  },
   power: { keepAwake: false, keepDisplayAwake: false, lidSleep: false, battery: false },
   metrics: { pressure: false, swap: false },
   servers: { run: false, ports: false, adopt: false },
@@ -71,10 +79,17 @@ export const NO_CAPABILITIES = {
  *   Opens a terminal running `command` and returns an opaque handle, or null if the
  *   platform has no notion of a handle it can address later.
  * @property {(handle: string, title: string) => Promise<boolean>} setTitle
- * @property {(handles: string[]) => Promise<{touched: number}>} setFont
- *   Applies the font size the current mode asks for, leaving each window where it is.
- * @property {(handles: string[]) => Promise<{touched: number}>} relayout
- * @property {(handle: string) => Promise<{ok: boolean, error?: string}>} focus
+ * @property {(handles: string[], opts?: {fontSize?: number, coverage?: number}) =>
+ *   Promise<{touched: number, error?: string}>} applyMode
+ *   Puts the windows the way the current mode wants them: the text at `fontSize`, the window at
+ *   `coverage` of the free screen. One gesture and not two — a window left holding large text at
+ *   a size measured for small text is worse than one that changed neither. What a platform cannot
+ *   do it leaves alone: where the font belongs to the emulator's own profile, only the size of
+ *   the window moves, and `terminal.font` says so.
+ * @property {(handles: string[], opts?: {coverage?: number}) => Promise<{touched: number}>} relayout
+ * @property {(handle: string, title?: string) => Promise<{ok: boolean, error?: string, handle?: string}>} focus
+ *   Brings a story's window up. `title` is the second way of finding it when the handle has gone
+ *   stale; a `handle` in the answer is the one that worked and is worth writing down.
  * @property {(opts: {handle: string, pid?: number}) => Promise<{closed: boolean}>} close
  * @property {(handle: string) => Promise<string|null>} readScreen
  *   What is on screen right now, or null when this platform cannot look.
@@ -82,6 +97,16 @@ export const NO_CAPABILITIES = {
  *   Puts `text` in front of the user WITHOUT submitting it.
  * @property {(text: string, handle: string) => Promise<{written: boolean, error?: string}>} type
  *   Writes `text` and submits it. The fallback when `paste` is unavailable.
+ * @property {(text: string, handle: string, opts: {ready: (screen: string|null) => boolean,
+ *   verify: (screen: string|null) => boolean}) => Promise<{sent: boolean, why?: string}>} command
+ *   Runs a slash command — `/rename Foo` — inside the session in that window. The keys go in
+ *   one by one, which is the only way Claude Code takes a command from outside: written as one
+ *   block, the way `type` does it, the same line reaches it as a message. Only when the window
+ *   already has the keyboard, never by taking it: raising a window under somebody's hands puts
+ *   what they were typing into it. `ready` looks at the screen before the first key and says
+ *   whether the input box is free to write in; `verify` looks after the last one and says whether
+ *   exactly that line is under the cursor — only then is Enter pressed, and a line that came out
+ *   wrong is deleted instead.
  * @property {() => Promise<number>} defaultFontSize
  */