k0-board 0.3.0 → 0.5.0

package/server/writer.js

@@ -15,7 +15,7 @@ import { ROOT } from './paths.js'
 // it the facts and gets prose back, the same arrangement `/k0-import` has always had, except
 // this one is invisible: no terminal opens and nothing lands on the board. `sessions.js`
 // already drops `claude -p` runs when it looks for sessions to import, so these cannot come
-// back later as cards.
+// back later as stories.
 
 // `K0_CLAUDE` names the executable outright. It exists for two reasons: a test must never be
 // able to reach the real Claude Code by accident, and an installation that keeps it somewhere
@@ -32,54 +32,125 @@ const CLAUDE = () => {
   ])
 }
 
-const SKILL = path.join(ROOT, '.claude', 'skills', 'k0-changelog', 'SKILL.md')
+const skillFile = (skill) => path.join(ROOT, '.claude', 'skills', skill, 'SKILL.md')
 const TIMEOUT = 3 * 60 * 1000
 const MAX_OUTPUT = 1 << 20
 
+// A skill name goes onto a command line as `/<name>`, so it is not allowed to be anything the
+// caller feels like. Nothing here takes one from a request today, and the guard is what keeps that
+// true after somebody adds an endpoint that does.
+const NAMED = /^[a-z0-9][a-z0-9-]{0,63}$/
+
 /**
  * Whether the write-up can happen at all and, if not, why — in a sentence meant for the page
  * rather than for a log. An adapter never pretends, and neither does this: the facts are shown
  * either way, with the missing half explained instead of quietly absent.
  */
-export function capability() {
+export function capability(skill) {
+  if (!NAMED.test(String(skill ?? ''))) return { can: false, why: `${skill} is not the name of a skill.` }
   if (!CLAUDE()) {
     return { can: false, why: 'Claude Code is not on this machine, so there is nobody here to write the summary.' }
   }
-  if (!fs.existsSync(SKILL)) {
-    return { can: false, why: 'The k0-changelog skill is missing from this copy of k0.' }
+  if (!fs.existsSync(skillFile(skill))) {
+    return { can: false, why: `The ${skill} skill is missing from this copy of k0.` }
   }
   return { can: true, why: null }
 }
 
-// One at a time: a second window of the same page must not start a second model. Each run gets
-// a number, and only the run that is still the current one is allowed to record anything —
-// otherwise a run abandoned halfway would come back later and overwrite the answer somebody is
-// already reading.
-let job = null
+// One job per key, and the key is whatever the page that asked is waiting on: the ChangeLog's
+// window, or What's New in one language at one level. Two pages can be writing at once — they
+// were not able to before, and they have to be, because one of them opens on top of the other.
+//
+// Within a key it is still one at a time: a second window of the same page must not start a
+// second model. Each run gets a number, and only the run that is still the current one for its
+// key may record anything — otherwise a run abandoned halfway would come back later and
+// overwrite the answer somebody is already reading.
+const jobs = new Map()
 let runs = 0
 
-/** Starts the write-up for a window, unless that window is already running or already done. */
-export function write(key, payload) {
-  if (job && job.key === key && (job.running || job.text)) return state(key)
+// A finished job holds its whole page in memory, and a key is a window or a language: leave them
+// all in and a tab left open for a week keeps every summary it ever asked for. A Map hands them
+// back in the order they were made, so the oldest finished one goes first; anything still running
+// stays, whatever else has to.
+const MAX_JOBS = 8
+
+/** Room for the job about to be made — one more than is there, unless this key is already held. */
+function makeRoom(incoming) {
+  const ceiling = jobs.has(incoming) ? MAX_JOBS : MAX_JOBS - 1
+  for (const [key, job] of jobs) {
+    if (jobs.size <= ceiling) return
+    if (!job.running) jobs.delete(key)
+  }
+}
 
-  const can = capability()
-  if (!can.can) {
-    job = { id: ++runs, key, running: false, text: null, error: can.why, child: null }
-    return state(key)
+// Three at a time, and the machine they think on is the user's own — the one they are also trying
+// to work on. Two pages open at once is the real case; three is already generous.
+const MAX_RUNNING = 3
+
+const running = () => {
+  let n = 0
+  for (const job of jobs.values()) if (job.running) n++
+  return n
+}
+
+/**
+ * Room for one more model to think in: the oldest run still going gives up its place.
+ *
+ * Not a summary snatched away from somebody. Two pages write, and each of them watches one key at
+ * a time — switching the period on the ChangeLog stops reading the run it started and asks for
+ * another, in the same second. So a fourth run means three keys have already been walked away
+ * from, and the oldest of them is the one nobody is waiting for.
+ *
+ * Refusing instead is what the page cannot do anything with, and it is what this used to do: click
+ * through Today, Yesterday and Week and the fourth click printed "ask again when one of them is
+ * done" to somebody who had only pressed a button. The job is dropped before the child is killed,
+ * so its own `close` finds nothing under its key and writes no error over a key that has moved on.
+ */
+function retireOldest() {
+  for (const [key, job] of jobs) {
+    if (!job.running) continue
+    jobs.delete(key)
+    job.child?.kill('SIGTERM')
+    return true
   }
+  return false
+}
+
+// A run that never started, remembered under its key as though it had finished badly. The page
+// asks once and then polls, so a refusal nobody wrote down would leave it waiting for ever.
+const refuse = (key, why) => {
+  jobs.set(key, { id: ++runs, key, running: false, text: null, error: why, child: null })
+  return state(key)
+}
+
+/**
+ * Starts `claude -p /<skill>` for a key, unless that key is already running or already done.
+ * The payload goes in on standard input; what comes back is read with `state(key)`.
+ *
+ * A run belongs to its key and to nothing else: it never touches another key's job, so the
+ * ChangeLog cannot cancel What's New by being asked for a second time.
+ */
+export function run(skill, key, payload) {
+  const held = jobs.get(key)
+  if (held && (held.running || held.text)) return state(key)
+  makeRoom(key)
+
+  const can = capability(skill)
+  if (!can.can) return refuse(key, can.why)
+  while (running() >= MAX_RUNNING) if (!retireOldest()) break
 
-  if (job?.child) job.child.kill('SIGTERM')
   const id = ++runs
-  const child = spawn(CLAUDE(), ['-p', '/k0-changelog', '--output-format', 'text'], {
+  const child = spawn(CLAUDE(), ['-p', `/${skill}`, '--output-format', 'text'], {
     cwd: ROOT, // where the project skill lives, whether k0 runs installed or from a checkout
     stdio: ['pipe', 'pipe', 'pipe'],
   })
-  job = { id, key, running: true, text: null, error: null, child }
+  jobs.set(key, { id, key, running: true, text: null, error: null, child })
 
   /** Records the end of THIS run, once. A run that has already ended cannot end again. */
   const finish = (patch) => {
-    if (job?.id !== id || !job.running) return
-    job = { ...job, ...patch, running: false, child: null }
+    const mine = jobs.get(key)
+    if (mine?.id !== id || !mine.running) return
+    jobs.set(key, { ...mine, ...patch, running: false, child: null })
   }
 
   let out = ''
@@ -115,14 +186,15 @@ export function write(key, payload) {
   return state(key)
 }
 
-/** What the page is waiting for. A window nobody has asked about is simply not running. */
+/** What the page is waiting for. A key nobody has asked about is simply not running. */
 export function state(key) {
-  if (!job || job.key !== key) return { running: false, text: null, error: null }
+  const job = jobs.get(key)
+  if (!job) return { running: false, text: null, error: null }
   return { running: !!job.running, text: job.text ?? null, error: job.error ?? null }
 }
 
 /** Called on the way out, so a model left mid-sentence does not outlive the server. */
 export function stop() {
-  if (job?.child) job.child.kill('SIGTERM')
-  job = null
+  for (const job of jobs.values()) if (job.child) job.child.kill('SIGTERM')
+  jobs.clear()
 }

package/web/awake.js

@@ -0,0 +1,62 @@
+// How many rounds in a row have to say "nothing moved" before the page stops asking so often.
+// Five is about ten seconds of a still board, which is long enough that nobody is watching it
+// happen and short enough that the slow pace is rarely the one you arrive back to.
+const QUIET = 5
+
+/**
+ * A job that repeats only while somebody can see the page, and only as often as it is worth.
+ *
+ * Every page here polls: the board asks for the whole board, the file viewer asks git what
+ * changed. None of them ever asked whether anyone was looking, so a tab left open in another
+ * window went on asking for days. That is worse than it sounds, because asking is itself the
+ * signal: `/api/board` is what tells the server somebody is watching, and the server uses that to
+ * decide whether to sample the machine, walk the process table and ask git about every repository.
+ * One forgotten tab kept all of it running, for nothing.
+ *
+ * And a job may now say that nothing moved, by answering `false`. After a few such rounds the
+ * page drops to `resting`, and the first round that moves anything — or your coming back to the
+ * tab — puts it straight back. A job that says nothing at all is taken to have moved something,
+ * which is the safe way round: a page that does not know cannot be the one that goes quiet.
+ *
+ * Coming back runs the job at once — the first look at a tab you left yesterday must not show
+ * yesterday. The first start is left alone: pages that want a reading before the first interval
+ * already take it themselves.
+ *
+ * Gives back the way to stop it for good, which nothing needs yet and costs one line to offer.
+ */
+export function whileVisible(job, every, resting = every) {
+  let timer = null
+  let quiet = 0
+
+  const stop = () => {
+    if (timer) clearTimeout(timer)
+    timer = null
+  }
+
+  const arm = (ms) => {
+    stop()
+    timer = setTimeout(round, ms)
+  }
+
+  async function round() {
+    let moved = true
+    try {
+      moved = await job()
+    } catch {
+      /* the job fell over: it has told us nothing, so keep the working pace and try again */
+    }
+    quiet = moved === false ? quiet + 1 : 0
+    arm(quiet >= QUIET ? resting : every)
+  }
+
+  document.addEventListener('visibilitychange', () => {
+    if (document.hidden) return stop()
+    quiet = 0
+    round()
+  })
+
+  // A page opened in a background tab is hidden from the first frame: it should not start either.
+  if (!document.hidden) arm(every)
+
+  return stop
+}

package/web/base.css

@@ -109,6 +109,10 @@ dialog .x {
 dialog .x svg { width: 17px; height: 17px; display: block; }
 dialog .x:hover { background: #f0ede3; color: var(--ink); border: none; }
 dialog label { display: block; margin-bottom: 18px; font-size: .82rem; font-weight: 600; color: var(--muted); }
+/* `display: block` beats the browser's `[hidden]`, the same trap the marks on the top bar fall
+   into. A dialog can have a field that only exists sometimes — the epic, which is nothing at all
+   with the backlog switched off — and without this it would stand there whatever the answer was. */
+dialog label[hidden] { display: none; }
 dialog label small { display: block; margin-top: 5px; font-weight: 400; }
 dialog input, dialog textarea {
   display: block;