k0-board 0.4.0 → 0.6.0

package/server/files.js

@@ -19,11 +19,22 @@ const MAX_FILES = 20000 // past that, the listing is cut and says so
 const MAX_DEPTH = 12
 const MAX_TEXT = 2 << 20 // 2 MB: above that it is no longer a document to read
 
-// Directories that are nobody's work. Only needed where git is not: in a repository the
-// listing comes from git, which already knows the .gitignore.
-const SKIP = new Set([
-  'node_modules', 'dist', 'build', 'out', 'coverage', 'vendor', 'target', 'Pods', '__pycache__', 'venv',
-])
+// Directories that are nobody's work and hold nothing anybody reads. They are never even
+// entered: `node_modules` alone is tens of thousands of directories, and this walk is redone
+// every few seconds.
+const SKIP = new Set(['node_modules', 'coverage', 'vendor', 'target', 'Pods', '__pycache__', 'venv'])
+
+// Generated too — but generated is not the same as worthless. In a directory of documents this is
+// where the work comes out: the PDFs you print, and the pages you open with a double click. So
+// these are walked into, and the documents in them are listed like any others.
+const GENERATED = new Set(['out', 'dist', 'build'])
+
+// A document that is done — the kind of thing a build produces on purpose and a person then
+// prints. It is the narrower half of `DOC_EXT`, and it exists for one case only: a generated
+// directory that git was explicitly told to ignore. There k0 goes behind git's back for the file
+// you went there for, and a PDF is that file; a page is not, because one real site's `dist/` is
+// four thousand of them and none is what you were looking for.
+const FINISHED = new Set(['.pdf', '.docx', '.doc', '.odt', '.pages', '.rtf'])
 
 // Only documents go in the listing: things you read and print. In a real repository code is
 // 95% of the files, and among 2,499 `.tsx` files the document you were after is gone. This
@@ -36,6 +47,12 @@ const DOC_EXT = new Set([
 
 export const isDoc = (p) => DOC_EXT.has(path.extname(p).toLowerCase())
 
+/** A document that was produced to be kept, not a step on the way to one. */
+export const isFinished = (p) => FINISHED.has(path.extname(p).toLowerCase())
+
+/** Is one of the directories above this file a generated one? The file itself does not count. */
+export const inGenerated = (p) => p.split('/').slice(0, -1).some((s) => GENERATED.has(s))
+
 // The other half of what is worth listing: the files that say how a project is set up. They are
 // not documents — nobody prints an `.env` — but they are the ones you go looking for by hand, and
 // until now the viewer was the only place in k0 you could not reach them from. They stay behind a
@@ -49,8 +66,16 @@ const ENV_NAME = /^\.env(\..+)?$/
 export const isConfig = (p) =>
   CONFIG_EXT.has(path.extname(p).toLowerCase()) || ENV_NAME.test(path.basename(p))
 
-/** Everything the listing carries: documents to read, configuration to check. */
-export const isListed = (p) => isDoc(p) || isConfig(p)
+/**
+ * Everything the listing carries: documents to read, configuration to check. It reads the whole
+ * path, not the name, because the directory a file is in is half the answer.
+ *
+ * Out of a generated directory come the documents and nothing else. A document is a document
+ * wherever it was made — the page you open with a double click is not worth less than the PDF
+ * beside it, and it has to be findable by name like everything else. What stays behind is the
+ * configuration a build leaves lying about, which in `out/` is nobody's reading.
+ */
+export const isListed = (p) => (inGenerated(p) ? isDoc(p) : isDoc(p) || isConfig(p))
 
 // What can be written back from the page. Configuration, and the notes kept next to it — never
 // code: k0 is not an editor, and a `.js` changed in a browser tab with no undo and no syntax
@@ -191,16 +216,19 @@ export function safePath(root, rel) {
 }
 
 /**
- * Which of these paths really exist and are things the viewer can show.
+ * Which of these paths really exist and are things the viewer can show, as listing rows.
  *
- * It exists for one thing: documents name files that are not in the listing. The `SKIP`
- * directories are there so the listing is not full of generated things, but in a directory of
- * documents `out/` holds the real PDFs, the ones you print. When it is a document naming them,
- * that file counts: the document said so, not the directory.
+ * It exists for one thing: a text names files the listing does not carry. Out of a generated
+ * directory the listing takes only what is finished, so `out/report.html` — the two megabytes the
+ * PDF was printed from — is not in it; and where git rules, an ignored directory is not in it
+ * either. Written down by name, both count: the text said so, not the directory.
  *
  * It is not a shortcut for reading the disk: `safePath` keeps everything inside the
  * repository, `isDoc` keeps code out, and hidden paths do not pass — `.claude/` and friends
  * are configuration, not things to read.
+ *
+ * It answers with rows, not names, because whoever asked is going to draw them next to the
+ * others, and a row without its date would be the one that looked wrong.
  */
 export function exist(root, paths) {
   const out = []
@@ -210,7 +238,8 @@ export function exist(root, paths) {
     const abs = safePath(root, rel)
     if (!abs) continue
     try {
-      if (fs.statSync(abs).isFile()) out.push(rel)
+      const s = fs.statSync(abs)
+      if (s.isFile()) out.push(entry(rel, s))
     } catch {
       /* not there: it simply does not come back */
     }
@@ -238,13 +267,20 @@ async function scan(root) {
   const names = hasGit() && fs.existsSync(path.join(root, '.git')) ? await tracked(root) : null
   if (!names) return { git: false, ...walk(root, isListed) }
 
-  // git's listing is missing exactly the file all this was built for: an `.env` is ignored by
-  // definition, so `ls-files -co --exclude-standard` will never name it. So the disk is walked a
-  // second time for configuration alone — a handful of names, under the same bounds as the other
-  // walk — and what git already gave is kept as it is.
+  // git's listing is missing exactly the files all this was built for. An `.env` is ignored by
+  // definition, so `ls-files -co --exclude-standard` will never name it, and an `out/` in the
+  // `.gitignore` takes the finished PDFs down with it. Both are the file you went there for. So
+  // the disk is walked a second time for those two alone — a handful of names, under the same
+  // bounds as the other walk — and what git already gave is kept as it is.
+  //
+  // Only the finished ones, though, and this is the single place where a repository with git
+  // reads differently from a folder without. Where git is in charge, git decides: k0 goes behind
+  // its back for a PDF, which is a thing somebody went looking for, and not for a page, because a
+  // real site's ignored `dist/` is four thousand pages and not one of them is the answer. Where
+  // git names the directory itself, everything in it is listed, pages included.
   const fromGit = withStats(root, names)
   const seen = new Set(fromGit.files.map((f) => f.p))
-  const extra = walk(root, isConfig)
+  const extra = walk(root, (p) => (inGenerated(p) ? isFinished(p) : isConfig(p)))
   for (const f of extra.files) if (!seen.has(f.p)) fromGit.files.push(f)
   return { git: true, files: fromGit.files, truncated: fromGit.truncated || extra.truncated }
 }
@@ -284,7 +320,10 @@ const entry = (p, s) => {
   return row
 }
 
-/** Everything under `root` that `pick` accepts. */
+/**
+ * Everything under `root` that `pick` accepts — which is asked with the **path**, not the name,
+ * because whether a file counts depends on the directory it sits in as much as on its extension.
+ */
 function walk(root, pick) {
   const files = []
   let truncated = false
@@ -312,7 +351,7 @@ function walk(root, pick) {
         continue
       }
       // No symbolic links: a loop would send the walk round forever.
-      if (!e.isFile() || !pick(e.name)) continue
+      if (!e.isFile() || !pick(childRel)) continue
       try {
         const s = fs.statSync(child)
         files.push(entry(childRel, s))
@@ -423,7 +462,7 @@ function after(line, n) {
 /**
  * The files this session has touched: the ones still hanging in the working tree, plus the
  * ones inside commits made since it started. The working tree belongs to everybody and not
- * only to it — the same limit the git mark on the card already has — but it remains the right
+ * only to it — the same limit the git mark on the post-it already has — but it remains the right
  * answer to the question "what has changed here, now".
  */
 export async function changed(root, headAtStart) {

package/server/git.js

@@ -13,12 +13,27 @@ import { parseChanged } from './files.js'
 // "did I push it?" that is exact and instant — pushing updates the remote reference by itself
 // — and in exchange it never touches the network, your credentials, or your patience.
 
-const GIT = () => which('git', ['/usr/bin/git', '/usr/local/bin/git', 'C:\\Program Files\\Git\\cmd\\git.exe'])
-const available = () => !!GIT()
+/**
+ * Where git is on this machine, or null when it is nowhere k0 knows to look.
+ *
+ * Exported because `worktree.js` shells out to the same git. A second copy of this list is a
+ * second thing to remember on the day a layout nobody thought of has to be added to it, and the
+ * half that was forgotten does not fail loudly — it reports that the machine has no git at all.
+ */
+export const gitPath = () =>
+  which('git', ['/usr/bin/git', '/usr/local/bin/git', 'C:\\Program Files\\Git\\cmd\\git.exe'])
+
+const available = () => !!gitPath()
 
 const OPTS = { timeout: 4000, maxBuffer: 1 << 20 }
 
-const TTL = 5000 // how long a reading is worth before it is taken again
+// How long a reading is worth before it is taken again. Five seconds was a guess about how fast a
+// repository changes, and the answer is: far slower than that. Nothing here moves except when you
+// commit, and a mark half a minute old has never been wrong about whether there is work in the
+// tree. At five seconds the loop was spawning a couple of git processes per repository per round,
+// which on a real board was the single biggest thing k0 did all day — see the call in `index.js`,
+// which now also stops asking at all when nobody is looking.
+const TTL = 30000
 // The last column of the board lists every repository, which is dozens of them and none of
 // them working: those are looked at rarely and a few at a time. At five seconds it would be
 // eighty git processes every round, on a machine that is already struggling.
@@ -56,7 +71,7 @@ export function parseStatus(out) {
  * How many of those unpushed commits arrived AFTER the session started. The list is
  * newest-first, so they are the ones before `headAtStart`. If `headAtStart` is not in the list
  * it was already pushed, and all of them are the session's. Returns null when it cannot be
- * known, and then the card says nothing about it.
+ * known, and then the post-it says nothing about it.
  */
 export function sessionShare(shas, headAtStart) {
   if (!Array.isArray(shas) || !shas.length) return 0
@@ -67,7 +82,7 @@ export function sessionShare(shas, headAtStart) {
 
 async function hasRemote(dir) {
   if (remotes.has(dir)) return remotes.get(dir)
-  const yes = await run(GIT(), ['-C', dir, 'remote'], OPTS)
+  const yes = await run(gitPath(), ['-C', dir, 'remote'], OPTS)
     .then((out) => !!out.trim())
     .catch(() => false)
   remotes.set(dir, yes)
@@ -79,12 +94,18 @@ async function read(dir) {
   // destroyed. Costs nothing and saves launching git for nothing every five seconds.
   if (!fs.existsSync(path.join(dir, '.git'))) return null
 
+  // Counted here and not where the reading was scheduled: most of a board's directories are
+  // worktrees that no longer exist, and those turn back on the line above without ever reaching
+  // git. A number that counted them too would put three figures in front of somebody on a machine
+  // running almost no git at all.
+  taken.push(Date.now())
+
   // The three in parallel: two processes in a queue would double the wait for nothing. After
   // the first round `hasRemote` answers from memory and it is back to two processes.
   const [st, list, remote] = await Promise.all([
-    run(GIT(), ['--no-optional-locks', '-C', dir, 'status', '--porcelain=v2', '--branch'], OPTS).catch(() => null),
+    run(gitPath(), ['--no-optional-locks', '-C', dir, 'status', '--porcelain=v2', '--branch'], OPTS).catch(() => null),
     run(
-      GIT(),
+      gitPath(),
       ['--no-optional-locks', '-C', dir, 'rev-list', `--max-count=${MAX_UNPUSHED}`, 'HEAD', '--not', '--remotes'],
       OPTS
     )
@@ -101,6 +122,18 @@ async function read(dir) {
 }
 
 // ── Cache ─────────────────────────────────────────────────────────────────────
+// When each reading was taken, kept for a minute. Every reading is two git processes — three the
+// first time, before `hasRemote` knows — and this number, which used to be in the hundreds, is the
+// one worth putting where somebody can see it.
+const taken = []
+
+/** Readings started in the last minute. */
+export function recent() {
+  const since = Date.now() - 60000
+  while (taken.length && taken[0] < since) taken.shift()
+  return taken.length
+}
+
 function schedule(dir) {
   const e = cache.get(dir) ?? { at: 0, running: false, value: null }
   e.running = true
@@ -120,15 +153,21 @@ function schedule(dir) {
  * The directories that matter right now. Refreshes the stale ones and forgets the ones no
  * longer needed — a destroyed worktree disappears by itself. Waits for nothing: whoever asks
  * for the state gets what is there, and the board never stalls on git.
+ *
+ * `eager` is which of them to actually ask about, and it is a separate question from which to
+ * keep: away from the board only the repositories a session is working in are worth asking, but
+ * dropping the rest out of the cache would mean re-reading every one of them the moment you looked
+ * again — a burst of a couple of hundred readings for a glance. What is kept and what is refreshed
+ * are two lists, and only the second one shrinks.
  */
-export function watch(dirs, slow = []) {
+export function watch(dirs, slow = [], eager = dirs) {
   if (!available()) return
   const hot = new Set(dirs.filter(Boolean))
   const cold = new Set(slow.filter(Boolean).filter((d) => !hot.has(d)))
   const wanted = new Set([...hot, ...cold])
   for (const dir of [...cache.keys()]) if (!wanted.has(dir)) cache.delete(dir)
 
-  for (const dir of hot) due(dir, TTL)
+  for (const dir of new Set(eager.filter(Boolean))) if (hot.has(dir)) due(dir, TTL)
   // The repositories that are only in the list: a few per round, so within ten seconds they
   // are all done and then it stays quiet for a minute.
   let budget = SLOW_BATCH
@@ -154,7 +193,7 @@ export function stateOf(dir) {
 /** Where HEAD is at this moment. Needed once, when a session starts. */
 export async function head(dir) {
   if (!available()) return null
-  return run(GIT(), ['--no-optional-locks', '-C', dir, 'rev-parse', 'HEAD'], OPTS)
+  return run(gitPath(), ['--no-optional-locks', '-C', dir, 'rev-parse', 'HEAD'], OPTS)
     .then((out) => out.trim() || null)
     .catch(() => null)
 }
@@ -225,7 +264,7 @@ export function stripTrailers(body) {
 const authors = new Map()
 export async function authorEmail(dir) {
   if (authors.has(dir)) return authors.get(dir)
-  const email = await run(GIT(), ['-C', dir, 'config', 'user.email'], OPTS)
+  const email = await run(gitPath(), ['-C', dir, 'config', 'user.email'], OPTS)
     .then((out) => out.trim())
     .catch(() => '')
   authors.set(dir, email)
@@ -261,9 +300,9 @@ export async function history(dir, { from, to }) {
   if (email) args.push(`--author=${email}`)
 
   const [log, list, remote] = await Promise.all([
-    run(GIT(), args, LOG_OPTS).catch(() => ''), // a repository without a single commit
+    run(gitPath(), args, LOG_OPTS).catch(() => ''), // a repository without a single commit
     run(
-      GIT(),
+      gitPath(),
       ['--no-optional-locks', '-C', dir, 'rev-list', `--max-count=${MAX_UNPUSHED}`, '--branches', '--not', '--remotes'],
       OPTS
     )
@@ -286,7 +325,7 @@ export async function history(dir, { from, to }) {
 export async function dirtyFiles(dir) {
   if (!available()) return []
   if (!fs.existsSync(path.join(dir, '.git'))) return []
-  return run(GIT(), ['--no-optional-locks', '-C', dir, 'status', '--porcelain=v2', '-z'], OPTS)
+  return run(gitPath(), ['--no-optional-locks', '-C', dir, 'status', '--porcelain=v2', '-z'], OPTS)
     .then((out) => parseChanged(out).slice(0, MAX_DIRTY))
     .catch(() => [])
 }

package/server/idle.js

@@ -2,8 +2,8 @@
  * Which terminals have been sitting there long enough to be worth giving back.
  *
  * A session left open costs memory whether or not anybody is looking at it: the `claude` process,
- * the MCP servers it started, the browsers those opened. `Close` on a card has always been the
- * cure — it stops the session and shuts its window, leaves the card exactly where it is, and
+ * the MCP servers it started, the browsers those opened. `Close` on a post-it has always been the
+ * cure — it stops the session and shuts its window, leaves the story exactly where it is, and
  * `Resume` picks the conversation up where it was. This is that same gesture, remembered for you.
  *
  * Only the deciding lives here. Nothing in this file kills anything, opens anything or reads a
@@ -13,7 +13,7 @@
 const HOUR = 3600000
 
 /**
- * The cards whose terminal should go, most of the rules being about what to leave alone.
+ * The stories whose terminal should go, most of the rules being about what to leave alone.
  *
  * Yellow only — `IDLE`, the ball in your court. Not because the others are less forgotten but
  * because of what closing them would destroy: a question and a finished plan are drawn by the
@@ -22,15 +22,15 @@ const HOUR = 3600000
  * Code reports as `shell` is a shell you dropped into, which may well have a command of yours
  * running in it — k0 does not know what, so k0 does not touch it.
  */
-export function dueForClose({ cards, live, hours, now = Date.now() }) {
+export function dueForClose({ stories, live, hours, now = Date.now() }) {
   if (!(hours > 0)) return [] // switched off, and nothing to think about
   const deadline = now - hours * HOUR
-  return cards.filter((card) => {
-    if (card.completed_at || !card.session_id || !card.session_alive) return false
-    if (card.status !== 'IDLE') return false
-    const session = live.get(card.session_id)
+  return stories.filter((story) => {
+    if (story.completed_at || !story.session_id || !story.session_alive) return false
+    if (story.status !== 'IDLE') return false
+    const session = live.get(story.session_id)
     if (!session || session.status !== 'idle') return false
-    return lastSignOfLife(card, session) <= deadline
+    return lastSignOfLife(story, session) <= deadline
   })
 }
 
@@ -48,9 +48,11 @@ export function dueForClose({ cards, live, hours, now = Date.now() }) {
  * changes state and are not a heartbeat — a session that had been busy for twenty-three minutes
  * was carrying timestamps twenty-three minutes old — so they say what they appear to say.
  *
- * `updated_at` matters for the case none of the others cover: resuming a card leaves the status at
- * `IDLE`, so no new event is written and `status_since` stays as old as it was.
+ * `updated_at` matters for the case none of the others cover: resuming a story leaves the status
+ * at `IDLE`, so no new event is written and `status_since` stays as old as it was. It is also why
+ * a session changing status still touches the story's `updated_at` now that the two live in
+ * different tables — see `applyDerivedStatus` in db.js.
  */
-export function lastSignOfLife(card, session) {
-  return Math.max(card.updated_at || 0, card.status_since || 0, session.updatedAt || 0, session.statusUpdatedAt || 0)
+export function lastSignOfLife(story, session) {
+  return Math.max(story.updated_at || 0, story.status_since || 0, session.updatedAt || 0, session.statusUpdatedAt || 0)
 }