k0-board 0.1.0

package/server/pdf.js

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { CACHE_DIR } from './paths.js'
+import { shell } from '../platform/index.js'
+
+// ── The document on paper ─────────────────────────────────────────────────────
+// The PDF is made by the browser, because the page has to come out the same as what you see:
+// same layout engine, same print CSS, same fonts. Writing one here would mean a large
+// dependency and a worse result.
+//
+// So a headless Chrome is opened on the viewer's page and asked to print it to a file. The
+// difference from ⌘P is that here we decide the margins and what the browser adds:
+// `--no-pdf-header-footer` removes the date, the address and the page number, and the margin
+// is the one in the CSS `@page`. From the print dialog, whatever the user picked in there wins.
+//
+// Two things learned by trying it, which explain the code below:
+//   1. Chrome writes the PDF and THEN stays up. It does not exit on its own: it has to be
+//      stopped as soon as it is done, or every download leaves a process hanging around.
+//   2. Two Chromes on the same profile directory wait for each other forever. So requests are
+//      served one at a time, in a queue.
+
+/** The browser that prints, or nothing. Printing and downloading the raw file do not use it. */
+export const browser = () => shell.findChrome()
+
+// A profile of its own, kept aside: without one, Chrome would attach to the user's real
+// profile. Keeping it between runs saves a few seconds.
+const PROFILE = path.join(CACHE_DIR, 'chrome')
+
+const TIMEOUT = 30000 // past this, something went wrong and nobody is waiting any more
+/** How Chrome says it has finished, on its error channel. */
+const DONE = /bytes written to file/i
+
+/** The queue: one print at a time, so two Chromes never fight over the same profile. */
+let queue = Promise.resolve()
+
+/**
+ * The page at `url`, printed, as the bytes of a PDF.
+ * Any address this server can serve will do.
+ */
+export function render(url) {
+  const mine = queue.then(
+    () => once(url),
+    () => once(url)
+  )
+  // The queue must never break: if one print goes wrong, the next one still starts.
+  queue = mine.catch(() => {})
+  return mine
+}
+
+function once(url) {
+  const bin = browser()
+  if (!bin) throw new Error('Install Google Chrome or Chromium to download PDFs')
+
+  const out = path.join(os.tmpdir(), `k0-${process.pid}-${Date.now()}.pdf`)
+  fs.mkdirSync(PROFILE, { recursive: true })
+
+  const child = spawn(bin, [
+    '--headless',
+    '--disable-gpu',
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-background-networking',
+    '--disable-sync',
+    '--disable-extensions',
+    '--no-pdf-header-footer',
+    // The document arrives after the page has loaded, and without this Chrome would print the
+    // blank sheet from before. It is not a real wait: Chrome runs the clock itself and stops
+    // as soon as nothing more is coming.
+    '--virtual-time-budget=8000',
+    `--user-data-dir=${PROFILE}`,
+    `--print-to-pdf=${out}`,
+    url,
+  ])
+
+  return new Promise((resolve, reject) => {
+    let over = false
+    const end = (err, buf) => {
+      if (over) return
+      over = true
+      clearTimeout(timer)
+      child.kill('SIGKILL')
+      try {
+        fs.unlinkSync(out)
+      } catch {} // if it was never written there is nothing to remove
+      err ? reject(err) : resolve(buf)
+    }
+
+    const timer = setTimeout(() => end(new Error('The PDF took too long')), TIMEOUT)
+
+    // The signal that it is finished comes from here, not from the process exiting: Chrome
+    // writes the file and then stays up, and waiting for it to close would mean waiting forever.
+    let log = ''
+    child.stderr.on('data', (c) => {
+      log = (log + c).slice(-4000)
+      if (!DONE.test(log)) return
+      try {
+        end(null, fs.readFileSync(out))
+      } catch (e) {
+        end(e)
+      }
+    })
+
+    child.on('error', (e) => end(new Error(`The browser did not start: ${e.message}`)))
+    // If instead it exits before having written anything, there is no PDF: better to say so
+    // now than to sit still until the time runs out.
+    child.on('exit', () => setTimeout(() => end(new Error('The PDF did not come out')), 200))
+  })
+}

package/server/projects.js

@@ -0,0 +1,152 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { projectRecency } from './db.js'
+import { hasDocs } from './files.js'
+import { shell } from '../platform/index.js'
+
+const HOME = os.homedir()
+const CLAUDE_JSON = path.join(HOME, '.claude.json')
+
+/** Still there? A renamed or deleted directory is no longer a project. */
+function exists(dir) {
+  try {
+    return fs.statSync(dir).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Is it empty? An empty directory under your home is one you have just made, and it cannot be
+ * anything other than a project about to start: it is the sign installed software never has.
+ * Entries are read one at a time rather than with `readdirSync`, which for a directory full of
+ * things would drag the whole lot along on every round of the board. Anything starting with a
+ * dot does not count: the metadata file the file manager scatters the moment you walk past
+ * must not make an empty directory look full.
+ */
+function isEmpty(dir) {
+  let d
+  try {
+    d = fs.opendirSync(dir)
+  } catch {
+    return false
+  }
+  try {
+    for (;;) {
+      const e = d.readSync()
+      if (!e) return true
+      if (!e.name.startsWith('.')) return false
+    }
+  } catch {
+    return false
+  } finally {
+    try {
+      d.closeSync()
+    } catch {
+      /* already closed: does not change the answer */
+    }
+  }
+}
+
+/**
+ * When you last opened each project according to Claude Code, which keeps it in
+ * ~/.claude.json. Careful: `lastStartTime` is rewritten when the session ENDS, so on its own
+ * it only tells you about the past — the present is k0's to know (see below).
+ */
+function lastUsed() {
+  const map = new Map()
+  try {
+    const data = JSON.parse(fs.readFileSync(CLAUDE_JSON, 'utf8'))
+    for (const [p, v] of Object.entries(data.projects || {})) {
+      const t = Number(v?.lastStartTime) || Number(v?.lastSessionModified) || 0
+      if (t) map.set(p, t)
+    }
+  } catch {
+    /* no history: fall back to alphabetical order */
+  }
+  return map
+}
+
+/**
+ * The candidate directories: everything under your home, plus the ones Claude Code has seen
+ * elsewhere. No cache and no filtering on `.git`: a directory just created or just renamed has
+ * to show up with the right name on the first refresh of the page, and reading the home
+ * directory costs far too little to put off.
+ */
+function scan(fromClaude) {
+  const paths = new Set()
+  const skip = shell.homeSkipList()
+
+  for (const name of fs.readdirSync(HOME)) {
+    if (name.startsWith('.') || skip.has(name)) continue
+    const dir = path.join(HOME, name)
+    if (exists(dir)) paths.add(dir)
+  }
+  for (const dir of fromClaude) {
+    // No worktrees: they are temporary copies, not projects.
+    if (dir.includes(`${path.sep}.claude-worktrees${path.sep}`) || dir.includes('/.claude-worktrees/')) continue
+    if (exists(dir)) paths.add(dir)
+  }
+
+  return [...paths]
+}
+
+/**
+ * The repositories, most used at the top. Recency is the fresher of two histories: Claude
+ * Code's, which knows where you have worked even outside k0, and k0's own cards, which are the
+ * only thing that notices a session still open right now.
+ */
+export function listProjects() {
+  const fromClaude = lastUsed()
+  const mine = new Map(projectRecency().map((r) => [r.project_path, Number(r.at) || 0]))
+  // A repository with a card is always selectable, even if it lives outside your home — but
+  // only while its directory exists: the old name of a renamed one does not come back.
+  const paths = new Set([...scan(fromClaude.keys()), ...[...mine.keys()].filter(exists)])
+  // Your home is not a project: it is the directory that contains them all. It ends up here
+  // because Claude Code notes a session started from it in ~/.claude.json too, but as a
+  // repository it means nothing — and in the list it would sit among its own children.
+  paths.delete(HOME)
+
+  const list = [...paths].map((dir) => ({
+    name: path.basename(dir),
+    path: dir,
+    last_used: Math.max(fromClaude.get(dir) || 0, mine.get(dir) || 0),
+    // Your stuff, or installed stuff? One sign is enough: a `.git`, a history in Claude Code, a
+    // card, a document in there, or the opposite of all of them — that there is nothing in it
+    // yet. Under your home there are also directories that are only ever programs, and those
+    // stay out precisely because they are full of things nobody reads.
+    // The empty question is asked last: it touches the disk, and by then only the few
+    // directories no other sign has already claimed still ask it.
+    known:
+      fromClaude.has(dir) ||
+      mine.has(dir) ||
+      fs.existsSync(path.join(dir, '.git')) ||
+      hasDocs(dir) ||
+      isEmpty(dir),
+  }))
+  list.sort((a, b) => b.last_used - a.last_used || a.name.localeCompare(b.name))
+  return list
+}
+
+/**
+ * The cards still standing: the ones whose directory exists. It is the same rule as the
+ * repository list above — "a card is kept alive by its directory" — carried over to the board
+ * too, which used to work its columns out from the cards alone. Without it, a deleted or
+ * renamed directory leaves a column behind forever.
+ *
+ * Hide, do not delete: the cards stay in the database, and if the directory comes back one day
+ * — an external disk remounted, a directory put back — so do they.
+ *
+ * The disk is asked once per repository and not once per card: there are a couple of dozen
+ * columns and a few hundred cards, and this round runs every second.
+ */
+export function onDisk(cards) {
+  const alive = new Map()
+  return cards.filter((c) => {
+    if (!alive.has(c.project_path)) alive.set(c.project_path, exists(c.project_path))
+    return alive.get(c.project_path)
+  })
+}
+
+export const projectName = (p) => path.basename(p)

package/server/sessions.js

@@ -0,0 +1,341 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { StringDecoder } from 'node:string_decoder'
+import { PROJECTS_DIR } from './watcher.js'
+
+/**
+ * Claude Code sessions that have already happened, ready to become cards.
+ *
+ * Nothing is written here: it only reads ~/.claude/projects, where Claude Code keeps the
+ * transcript of every session in a JSONL file.
+ */
+
+/** How much is read from the head of a transcript to decide whether to open all of it. */
+const HEAD = 64 * 1024
+
+/**
+ * The mark of a real session.
+ *
+ * Claude Code's interface writes a `{"type":"mode",…}` line; a `claude -p`, a subagent or a
+ * skill launched from a script does not. It is a clean split — on one real machine it
+ * separated 145 genuine sessions from 867 automated runs — and it can be read without opening
+ * the whole file.
+ *
+ * The line is usually at the top, but not always: if you paste the prompt while Claude is
+ * still starting up, the transcript begins with the lines of the send queue and the `mode`
+ * ends up further down. Which is why the end is checked too — without that check, real
+ * sessions were being lost, and the best ones at that: a pasted document and a question.
+ */
+const MODE = /^\{"type":"mode"/m
+
+/** The bite a transcript is read in: some of them run to megabytes. */
+const CHUNK = 1 << 20
+
+const CLIP_FIRST = 700
+const CLIP_RECENT = 250
+const CLIP_REPLY = 500
+const RECENT = 3
+
+/**
+ * Opens and reads a piece of a file. Returns an empty string if the file disappeared in the
+ * meantime: a scan must never stall over one transcript fewer.
+ */
+function slice(file, from, len) {
+  let fd
+  try {
+    fd = fs.openSync(file, 'r')
+  } catch {
+    return ''
+  }
+  try {
+    const buf = Buffer.alloc(len)
+    const n = fs.readSync(fd, buf, 0, len, from)
+    return buf.subarray(0, n).toString('utf8')
+  } catch {
+    return ''
+  } finally {
+    fs.closeSync(fd)
+  }
+}
+
+const CWD = /"cwd":"((?:[^"\\]|\\.)*)"/
+
+function firstCwd(text) {
+  const m = CWD.exec(text)
+  if (!m) return null
+  try {
+    return JSON.parse(`"${m[1]}"`)
+  } catch {
+    return null // string cut in half by the edge of the window
+  }
+}
+
+/**
+ * From the `cwd` to a column on the board. It walks up to the first `.git`; if that is a file
+ * rather than a directory we are inside a worktree, and then the work belongs to the
+ * repository the worktree came from — not to the temporary copy, which tomorrow will not be
+ * there. With no `.git` anywhere it falls back to the directory under your home.
+ */
+function resolveRoot(cwd) {
+  let dir = cwd
+  for (;;) {
+    const dot = path.join(dir, '.git')
+    let st = null
+    try {
+      st = fs.statSync(dot)
+    } catch {
+      /* nothing here: go up */
+    }
+    if (st?.isDirectory()) return dir
+    if (st?.isFile()) {
+      const m = /gitdir:\s*(.+)/.exec(fs.readFileSync(dot, 'utf8'))
+      const base = m?.[1].trim().split('/.git/worktrees/')[0]
+      return base && fs.existsSync(base) ? base : dir
+    }
+    const up = path.dirname(dir)
+    if (up === dir) break
+    dir = up
+  }
+  // No `.git` anywhere: to k0 a project is also just a directory you have worked in — a
+  // folder of notes is not a repository and belongs on the board like everything else.
+  // The directory under your home is what counts, so subdirectories do not each open a
+  // column of their own.
+  const home = os.homedir()
+  if (cwd.startsWith(home + path.sep)) {
+    const first = cwd.slice(home.length + 1).split(path.sep)[0]
+    if (first) return path.join(home, first)
+  }
+  return cwd
+}
+
+function repoOf(cwd, cache) {
+  if (cache.has(cwd)) return cache.get(cwd)
+  const r = resolveRoot(cwd)
+  const ok =
+    r && fs.existsSync(r) && !r.includes('/.claude/worktrees/') && !r.includes('/.claude-worktrees/') ? r : null
+  cache.set(cwd, ok)
+  return ok
+}
+
+/** Walks a transcript line by line without holding all of it in memory. */
+function eachLine(file, fn) {
+  let fd
+  try {
+    fd = fs.openSync(file, 'r')
+  } catch {
+    return
+  }
+  const buf = Buffer.alloc(CHUNK)
+  const decoder = new StringDecoder('utf8')
+  let rest = ''
+  try {
+    let pos = 0
+    for (;;) {
+      const n = fs.readSync(fd, buf, 0, CHUNK, pos)
+      if (!n) break
+      pos += n
+      const parts = (rest + decoder.write(buf.subarray(0, n))).split('\n')
+      rest = parts.pop() ?? ''
+      for (const line of parts) fn(line)
+    }
+    rest += decoder.end()
+    if (rest) fn(rest)
+  } finally {
+    fs.closeSync(fd)
+  }
+}
+
+/** Lines that are not your words but the program's scaffolding. */
+const NOISE =
+  /^(<command-name>|<command-message>|<command-args>|<local-command|<user-prompt-submit-hook|<system-reminder>|<bash-input>|<bash-stdout>|Caveat: The messages below|\[Request interrupted)/
+
+function textOf(o) {
+  const c = o.message?.content
+  if (typeof c === 'string') return c
+  if (!Array.isArray(c)) return ''
+  return c
+    .filter((x) => x?.type === 'text' && typeof x.text === 'string')
+    .map((x) => x.text)
+    .join('\n')
+}
+
+function clean(s) {
+  return s
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+const clip = (s, n) => (s.length > n ? s.slice(0, n).trimEnd() + '…' : s)
+
+/**
+ * The gist of a session: enough to say what it was about and where it got to, without
+ * dragging megabytes of conversation along.
+ */
+function digest(file) {
+  const out = {
+    turns: 0,
+    first_prompt: '',
+    recent_prompts: [],
+    last_reply: '',
+    title_hint: null,
+    started_at: null,
+    ended_at: null,
+  }
+  let aiTitle = null
+  let custom = null
+
+  eachLine(file, (line) => {
+    if (!line.startsWith('{')) return
+    let o
+    try {
+      o = JSON.parse(line)
+    } catch {
+      return
+    }
+
+    // The title Claude Code has already written for itself: one set by hand wins.
+    if (o.type === 'ai-title' && o.aiTitle) {
+      aiTitle = o.aiTitle
+      return
+    }
+    if (o.type === 'custom-title' && o.customTitle) {
+      custom = o.customTitle
+      return
+    }
+
+    if (o.timestamp) {
+      const t = Date.parse(o.timestamp)
+      if (t) {
+        if (!out.started_at || t < out.started_at) out.started_at = t
+        if (!out.ended_at || t > out.ended_at) out.ended_at = t
+      }
+    }
+
+    // Subagents talk among themselves: that is not the conversation with you.
+    if (o.isSidechain) return
+
+    if (o.type === 'user') {
+      const t = clean(textOf(o))
+      if (!t || NOISE.test(t)) return
+      out.turns++
+      if (!out.first_prompt) out.first_prompt = clip(t, CLIP_FIRST)
+      out.recent_prompts.push(clip(t, CLIP_RECENT))
+      if (out.recent_prompts.length > RECENT) out.recent_prompts.shift()
+      return
+    }
+
+    if (o.type === 'assistant') {
+      const t = clean(textOf(o))
+      if (t) out.last_reply = clip(t, CLIP_REPLY)
+    }
+  })
+
+  out.title_hint = custom || aiTitle || null
+  return out
+}
+
+/**
+ * The sessions worth offering as cards, most recent first.
+ *
+ * Two passes, because the second one is expensive: first the head of every transcript in the
+ * window is checked, to keep only the real sessions and work out which repository they belong
+ * to; then only the ones that actually fit under the per-repository cap are read in full.
+ *
+ * `exclude` are the session ids already on a card: re-importing must not make duplicates.
+ * `live` are the sessions still running, which can be attached too.
+ * `root` only changes in the tests, to look at a directory of fake transcripts.
+ */
+export function scanSessions({
+  days = 14,
+  perRepo = 10,
+  exclude = new Set(),
+  live = new Set(),
+  root = PROJECTS_DIR,
+} = {}) {
+  const cutoff = Date.now() - days * 86400000
+  const byRepo = new Map()
+  const roots = new Map()
+
+  let dirs
+  try {
+    dirs = fs.readdirSync(root)
+  } catch {
+    return [] // no transcripts on this machine: nothing to import
+  }
+
+  for (const dir of dirs) {
+    const full = path.join(root, dir)
+    let files
+    try {
+      files = fs.readdirSync(full)
+    } catch {
+      continue
+    }
+    for (const name of files) {
+      if (!name.endsWith('.jsonl')) continue
+      const sessionId = name.slice(0, -'.jsonl'.length)
+      if (exclude.has(sessionId)) continue
+
+      const file = path.join(full, name)
+      let st
+      try {
+        st = fs.statSync(file)
+      } catch {
+        continue
+      }
+      if (!st.size || st.mtimeMs < cutoff) continue
+
+      // Two reads of 64 KB at most, head and tail, and the tail only if it is needed.
+      const head = slice(file, 0, HEAD)
+      let tailText = null
+      const tail = () => (tailText ??= st.size > HEAD ? slice(file, st.size - HEAD, HEAD) : '')
+
+      if (!MODE.test(head) && !MODE.test(tail())) continue
+
+      // Which directory it was running in. Always read from the transcript, never by
+      // reversing the directory name: that name is lossy — `my_project` and `my-project`
+      // become the same slug — and there is no way back from it.
+      const cwd = firstCwd(head) ?? firstCwd(tail())
+      if (!cwd) continue
+      const repo = repoOf(cwd, roots)
+      if (!repo) continue // the repository is gone: the session cannot be resumed
+
+      const list = byRepo.get(repo)
+      if (list) list.push({ sessionId, file, cwd, mtime: st.mtimeMs })
+      else byRepo.set(repo, [{ sessionId, file, cwd, mtime: st.mtimeMs }])
+    }
+  }
+
+  const out = []
+  for (const [repo, list] of byRepo) {
+    list.sort((a, b) => b.mtime - a.mtime)
+    let taken = 0
+    for (const c of list) {
+      if (taken >= perRepo) break
+      const d = digest(c.file)
+      // Not one word of yours in the transcript: there is nothing for a card to say.
+      if (!d.turns) continue
+      taken++
+      out.push({
+        session_id: c.sessionId,
+        project_path: repo,
+        project_name: path.basename(repo),
+        cwd: c.cwd,
+        alive: live.has(c.sessionId),
+        started_at: d.started_at ?? c.mtime,
+        ended_at: d.ended_at ?? c.mtime,
+        turns: d.turns,
+        title_hint: d.title_hint,
+        first_prompt: d.first_prompt,
+        recent_prompts: d.recent_prompts,
+        last_reply: d.last_reply,
+      })
+    }
+  }
+
+  out.sort((a, b) => b.ended_at - a.ended_at)
+  return out
+}