k0-board 0.1.1 → 0.2.0

package/server/git.js

@@ -1,6 +1,9 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { run, which } from '../platform/shared/run.js'
+// The same reading of `status --porcelain=v2 -z` the viewer already does. One parser for one
+// output format: two would drift, and the day they disagreed nobody would notice.
+import { parseChanged } from './files.js'
 
 // ── Git ───────────────────────────────────────────────────────────────────────
 // The only place that talks to git. It exists to answer one question: is what is in here
@@ -155,3 +158,135 @@ export async function head(dir) {
     .then((out) => out.trim() || null)
     .catch(() => null)
 }
+
+// ── The history ───────────────────────────────────────────────────────────────
+// Everything above answers "is what is in here safe right now". What follows answers a
+// different question — "what did I do, and did it get out" — and it is the only part that
+// reads the commits themselves instead of counting them.
+//
+// Still no fetch. `--not --remotes` compares against the remote references this machine
+// already holds, and those are written by the push itself: for "did it leave here" that is
+// exact, and it costs nothing.
+
+const LOG_OPTS = { timeout: 15000, maxBuffer: 1 << 24 } // a month of a busy repository
+const MAX_LOG = 400 // past that nobody reads the list, and the count already tells the story
+const MAX_DIRTY = 60
+
+// Two separators git will never find inside a commit message, so a subject with a quote in it
+// or a body with a tab still comes out in one piece.
+const FIELD = '\x1f'
+const RECORD = '\x1e'
+const FORMAT = `%H${FIELD}%aI${FIELD}%s${FIELD}%b${RECORD}`
+
+/**
+ * The commits out of `log --format=…`, newest first, in the order git gave them.
+ * An empty body is not a failure: most commits here are a single line and nothing else.
+ */
+export function parseLog(out) {
+  const commits = []
+  for (const record of String(out ?? '').split(RECORD)) {
+    const r = record.replace(/^\s+/, '')
+    if (!r) continue
+    const [sha, at, subject, body] = r.split(FIELD)
+    if (!sha || !subject) continue
+    commits.push({ sha, at, subject, body: stripTrailers(body) })
+  }
+  return commits
+}
+
+// The lines at the foot of a commit that are addressed to git and to nobody else. On a machine
+// where the commits are written with help there is one of these on almost every commit, and
+// left in they are the bulk of what gets read: a signature repeated four hundred times says
+// nothing about what anybody did.
+const TRAILER = /^(co-authored-by|signed-off-by|claude-session|reviewed-by|acked-by|change-id):\s/i
+const GENERATED = /^(🤖\s*)?generated with \[/i
+
+/** The part of a commit message a person wrote for another person. */
+export function stripTrailers(body) {
+  const kept = []
+  for (const line of String(body ?? '').split('\n')) {
+    const l = line.trim()
+    if (TRAILER.test(l) || GENERATED.test(l)) continue
+    // The bare session link that follows the signature, on a line of its own.
+    if (/^https:\/\/claude\.ai\/code\/session_\S+$/.test(l)) continue
+    kept.push(line)
+  }
+  return kept.join('\n').trim()
+}
+
+/**
+ * The email git commits with in this directory, wanted for one thing only: as the argument of
+ * `--author`, so that a repository shared with other people still tells you about YOUR day.
+ *
+ * It must never travel further than that argument — not into an answer, not onto disk. It is a
+ * personal detail that is not k0's to keep, and `test/clean.test.mjs` is in the build to catch
+ * exactly that kind of leak.
+ */
+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)
+    .then((out) => out.trim())
+    .catch(() => '')
+  authors.set(dir, email)
+  return email
+}
+
+/**
+ * What you committed inside a window, and whether each one is out.
+ *
+ * `--branches` rather than `HEAD`, for a reason this repository runs into every day: a
+ * worktree is a branch of the same repository, so work done in one is invisible from HEAD
+ * alone. `--no-merges` is the other half of it — closing a worktree leaves a merge commit
+ * that repeats what its own commits already said, and counting both shows every piece of work
+ * twice.
+ */
+export async function history(dir, { from, to }) {
+  if (!available()) return null
+  if (!fs.existsSync(path.join(dir, '.git'))) return null
+
+  const email = await authorEmail(dir)
+  const args = [
+    '--no-optional-locks',
+    '-C',
+    dir,
+    'log',
+    '--branches',
+    '--no-merges',
+    `--max-count=${MAX_LOG}`,
+    `--since=${new Date(from).toISOString()}`,
+    `--until=${new Date(to).toISOString()}`,
+    `--format=${FORMAT}`,
+  ]
+  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(
+      GIT(),
+      ['--no-optional-locks', '-C', dir, 'rev-list', `--max-count=${MAX_UNPUSHED}`, '--branches', '--not', '--remotes'],
+      OPTS
+    )
+      .then((out) => out.split('\n').filter(Boolean))
+      .catch(() => []),
+    hasRemote(dir),
+  ])
+
+  // With no remote there is nowhere for anything to have gone, so nothing here is "waiting to
+  // be pushed": it is simply here. Saying otherwise would turn every local experiment into a
+  // list of things you had forgotten to do.
+  const unpushed = new Set(remote ? list : [])
+  const commits = parseLog(log).map((c) => ({ ...c, online: remote ? !unpushed.has(c.sha) : null }))
+  // The total counts the ones from before the window too: a commit made on Tuesday and still
+  // sitting here on Friday is exactly the kind of thing you opened this page to be told.
+  return { commits, remote, unpushedTotal: remote ? unpushed.size : 0 }
+}
+
+/** The files left hanging in the working tree, by path, relative to the repository. */
+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)
+    .then((out) => parseChanged(out).slice(0, MAX_DIRTY))
+    .catch(() => [])
+}

package/server/guard.js

@@ -0,0 +1,31 @@
+// ── Who is allowed to talk to this server ────────────────────────────────────
+// k0 listens on the loopback interface only, which keeps the rest of the network out. What it
+// does not keep out is a web page open in your browser: any site can make requests to
+// 127.0.0.1, and this API opens terminals and starts sessions.
+//
+// Two checks close that door.
+//
+// The `Host` header must be one we recognise. A page cannot forge it, and requiring it stops
+// DNS rebinding — the trick where a hostile domain resolves to 127.0.0.1 so the browser thinks
+// it is talking to its own site.
+//
+// The `Origin` header, when there is one, must be ours. Browsers attach it to every
+// cross-origin request and to every same-origin POST, so a hostile page is always identified.
+// Things that are not browsers — the menu bar icon, curl, the import skill — send none, and
+// they are let through: they are already running as you, on your machine, and a header would
+// not tell us anything a hostile process could not also write.
+//
+// It lives in a file of its own so that it can be read, and tested, without starting a server:
+// this is the whole of the promise made in SECURITY.md, and it is four lines long.
+
+/** The names this machine answers to. Anything else is somebody else's idea of where we are. */
+const NAMES = ['127.0.0.1', 'localhost', 'k0.localhost', '[::1]']
+
+/** Whether a request may be answered, given its headers and the port we are listening on. */
+export function allowed(headers, port) {
+  const host = String(headers.host || '')
+  if (!NAMES.some((name) => host === `${name}:${port}`)) return false
+  const origin = headers.origin
+  if (origin && !NAMES.some((name) => origin === `http://${name}:${port}`)) return false
+  return true
+}

package/server/index.js

@@ -3,8 +3,9 @@ import fs from 'node:fs'
 import path from 'node:path'
 import crypto from 'node:crypto'
 import * as db from './db.js'
+import { allowed } from './guard.js'
 import { ROOT } from './paths.js'
-import { readLiveSessions, deriveStatus, forgetSession, renameSession } from './watcher.js'
+import { readLiveSessions, deriveStatus, forgetSession, renameSession, busy } from './watcher.js'
 import {
   launch,
   focusWindow,
@@ -18,9 +19,12 @@ import * as mode from './mode.js'
 import { listProjects, onDisk, projectName } from './projects.js'
 import { scanSessions } from './sessions.js'
 import * as git from './git.js'
+import * as changelog from './changelog.js'
+import * as writer from './writer.js'
 import * as files from './files.js'
 import * as pdf from './pdf.js'
 import * as machine from './machine.js'
+import * as servers from './servers.js'
 import { report as platformReport } from '../platform/index.js'
 // The same front-matter reader the viewer uses: the PDF has to be called what the page is
 // called, and two different readings of the same header would give two different names.
@@ -68,37 +72,6 @@ function tick() {
 let lastBoard = 0
 setInterval(tick, 1000)
 
-// ── Who is allowed to talk to this server ────────────────────────────────────
-// k0 listens on the loopback interface only, which keeps the rest of the network out. What it
-// does not keep out is a web page open in your browser: any site can make requests to
-// 127.0.0.1, and this API opens terminals and starts sessions.
-//
-// Two checks close that door.
-//
-// The `Host` header must be one we recognise. A page cannot forge it, and requiring it stops
-// DNS rebinding — the trick where a hostile domain resolves to 127.0.0.1 so the browser thinks
-// it is talking to its own site.
-//
-// The `Origin` header, when there is one, must be ours. Browsers attach it to every
-// cross-origin request and to every same-origin POST, so a hostile page is always identified.
-// Things that are not browsers — the menu bar icon, curl, the import skill — send none, and
-// they are let through: they are already running as you, on your machine, and a header would
-// not tell us anything a hostile process could not also write.
-const ALLOWED_HOSTS = new Set(
-  ['127.0.0.1', 'localhost', 'k0.localhost', '[::1]'].map((h) => `${h}:${PORT}`)
-)
-const ALLOWED_ORIGINS = new Set(
-  ['127.0.0.1', 'localhost', 'k0.localhost', '[::1]'].map((h) => `http://${h}:${PORT}`)
-)
-
-function allowed(req) {
-  const host = String(req.headers.host || '')
-  if (!ALLOWED_HOSTS.has(host)) return false
-  const origin = req.headers.origin
-  if (origin && !ALLOWED_ORIGINS.has(origin)) return false
-  return true
-}
-
 // ── API ──────────────────────────────────────────────────────────────────────
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -170,6 +143,9 @@ function board() {
     load: machine.loadOf(live.get(c.session_id)?.pid),
   }))
   const paths = [...new Set(cards.map((c) => c.project_path))]
+  // And the same for the dev servers: looking at the board is what makes k0 ask the machine
+  // who is listening, and it asks only about the repositories in front of you.
+  servers.touch(paths)
 
   // Live sessions no card claims: they weigh the same, and if the computer is struggling it is
   // fair to know there are three of them open outside here.
@@ -180,7 +156,14 @@ function board() {
     // The columns are the projects with at least one card — and that still exist: a card is
     // kept alive by its directory (see `onDisk` in projects.js).
     columns: paths
-      .map((p) => ({ path: p, name: projectName(p), git: publicGit(git.stateOf(p)) }))
+      .map((p) => ({
+        path: p,
+        name: projectName(p),
+        git: publicGit(git.stateOf(p)),
+        // Null where the repository has no way to start a server: then there is no globe at
+        // all, rather than one that would do nothing.
+        server: servers.stateOf(p),
+      }))
       .sort((a, b) => a.name.localeCompare(b.name)),
     cards,
     // The repositories for the last column, the one you go through to reach the files of a
@@ -309,6 +292,50 @@ function site(req, res, seg) {
 // is a much smaller loss than that, so the header is gone.
 const SANDBOX = 'sandbox'
 
+// ── The recap of a window ────────────────────────────────────────────────────
+// Held for a minute, and not as a saved result: the page asks for the facts, then asks for the
+// write-up to start, then asks every second whether it is done. Reading every repository's git
+// history once a second to answer "not yet" would be absurd. Nothing is written down, and a
+// minute later the same question is asked of git again from scratch.
+const RECAP_TTL = 60000
+let recap = null
+
+async function recapFor(raw, { fresh = true } = {}) {
+  const period = changelog.PERIODS.includes(raw) ? raw : 'last'
+  // The page asks about the write-up once a second until it is done, and a model can take
+  // longer than a minute: those questions must reuse whatever window is already open, or a
+  // slow answer would mean a full sweep of every repository's git, every second, while waiting.
+  if (recap && recap.period === period && (!fresh || Date.now() - recap.at < RECAP_TTL)) return recap
+  const data = await changelog.facts(period)
+  recap = {
+    period,
+    at: Date.now(),
+    // The window is part of the name: at midnight "yesterday" becomes a different day, and a
+    // summary written for the old one must not be handed over as if it were the new one.
+    key: `${data.period}:${data.from}:${data.to}`,
+    public: data,
+    payload: JSON.stringify(
+      {
+        period: data.period,
+        from: new Date(data.from).toISOString(),
+        to: new Date(data.to).toISOString(),
+        totals: data.totals,
+        repositories: data.repos.map((r) => ({
+          name: r.name,
+          commits: r.commits.map(({ at, subject, body, online }) => ({ at, subject, body, online })),
+          unpushed_total: r.unpushedTotal,
+          uncommitted_files: r.dirty.map((f) => f.path),
+          unreleased_changelog: r.unreleased,
+          cards: r.cards,
+        })),
+      },
+      null,
+      2
+    ),
+  }
+  return recap
+}
+
 async function api(req, res, url) {
   const seg = url.pathname.split('/').filter(Boolean) // ['api', 'card', '3', 'start']
   const [, resource, idRaw, action] = seg
@@ -318,6 +345,20 @@ async function api(req, res, url) {
   if (resource === 'status' && req.method === 'GET') return send(res, 200, status())
   if (resource === 'projects' && req.method === 'GET') return send(res, 200, listProjects())
 
+  // ── What you have been doing ───────────────────────────────────────────────
+  // Two halves, deliberately apart. The facts come back straight away and the page can already
+  // show them; the write-up takes a model half a minute, so it is started and then asked
+  // about, the same once-a-second poll the board and the viewer already live on.
+  if (resource === 'changelog' && !idRaw && req.method === 'GET') {
+    const data = await recapFor(url.searchParams.get('period'))
+    return send(res, 200, { ...data.public, writer: writer.capability() })
+  }
+  if (resource === 'changelog' && idRaw === 'write') {
+    const data = await recapFor(url.searchParams.get('period'), { fresh: false })
+    if (req.method === 'POST') return send(res, 200, writer.write(data.key, data.payload))
+    if (req.method === 'GET') return send(res, 200, writer.state(data.key))
+  }
+
   // ── The four modes ─────────────────────────────────────────────────────────
   // One control, with two handles: the row of buttons on the board and the four entries in the
   // menu bar. The text in terminals that are already open changes STRAIGHT AWAY, not only in
@@ -333,6 +374,25 @@ async function api(req, res, url) {
     return send(res, 200, { mode: mode.current(), lid: mode.lid(), reason: mode.reason() })
   }
 
+  // ── The dev server of a repository ─────────────────────────────────────────
+  // The globe in the column heading. One address for the three gestures, because they are the
+  // same gesture with different endings — and `restart` really is stop-then-start, not a third
+  // path through the same code.
+  //
+  // The repository is not taken on trust. It arrives from the page as a plain path and it is a
+  // path k0 is about to RUN something in, so it goes through the same allowlist the file viewer
+  // uses: a directory k0 already knows as a project, or nothing at all.
+  if (resource === 'server' && req.method === 'POST') {
+    const b = await readBody(req)
+    const repo = rootOf(b.path)
+    if (!repo) return send(res, 404, { error: 'k0 does not know that repository.' })
+    const action = b.action
+    if (action === 'start') return send(res, 200, await servers.start(repo))
+    if (action === 'stop') return send(res, 200, await servers.stop(repo))
+    if (action === 'restart') return send(res, 200, await servers.restart(repo))
+    return send(res, 400, { error: 'That is not something a server can be asked to do.' })
+  }
+
   // The screen changed under the windows: a monitor plugged in or unplugged, a different
   // resolution. This puts them all back in the middle of what is there now, as they were the
   // day they were born. The menu bar icon calls it, being the one piece of k0 that sees that
@@ -552,6 +612,21 @@ async function api(req, res, url) {
       return send(res, 200, await focusWindow(card.terminal_window_id))
     }
 
+    // Closing the terminal without closing the work: the same two moves as Done — stop the
+    // session, shut its window — and none of the marking. The card stays where it is, with the
+    // status it had, and Resume picks the conversation up where it was.
+    if (req.method === 'POST' && action === 'close') {
+      if (!card.session_id) return send(res, 400, { error: 'This card has no session' })
+      // The board is up to a second behind, so a card that was idle when it was clicked may have
+      // started thinking since. Nothing that is working gets stopped from here.
+      if (busy(card.status)) return send(res, 409, { error: 'It is working: let it finish' })
+      const pid = readLiveSessions().get(card.session_id)?.pid
+      const out = await closeTerminal({ winId: card.terminal_window_id, pid })
+      db.setTerminalWindow(id, null) // that window is gone; Resume opens a new one
+      tick() // so the answer already carries the closed card, without waiting for the loop
+      return send(res, 200, { ...out, card: db.getCard(id) })
+    }
+
     if (req.method === 'POST' && (action === 'start' || action === 'resume')) {
       const resuming = action === 'resume' && card.session_id
       const sessionId = resuming ? card.session_id : crypto.randomUUID()
@@ -589,13 +664,23 @@ function serveStatic(res, pathname) {
     res.writeHead(404).end('Not found')
     return
   }
-  res.writeHead(200, { 'content-type': MIME[path.extname(file)] || 'application/octet-stream' })
+  // Nothing here is cached, and that is deliberate. These files have no version in their names
+  // and nothing rebuilds them, so with no instruction at all the browser decides for itself how
+  // long to keep them — and a tab left open all day keeps the stylesheet it loaded that morning.
+  // That turns "change a file, reload the page" into a promise k0 does not keep, and it does the
+  // same after an update: the new app on disk, the old interface on screen. They are a few
+  // kilobytes over loopback; there is nothing to save here and a whole class of confusion to
+  // avoid.
+  res.writeHead(200, {
+    'content-type': MIME[path.extname(file)] || 'application/octet-stream',
+    'cache-control': 'no-cache, no-store, must-revalidate',
+  })
   fs.createReadStream(file).pipe(res)
 }
 
 http
   .createServer(async (req, res) => {
-    if (!allowed(req)) {
+    if (!allowed(req.headers, PORT)) {
       res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })
       res.end('k0 only answers to its own address on this machine.')
       return
@@ -631,6 +716,8 @@ process.on('exit', mode.stopNow)
 for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
   process.on(signal, () => {
     mode.stopNow()
+    // A summary being written when the server goes down has nobody left to give it to.
+    writer.stop()
     process.exit(0)
   })
 }

package/server/machine.js

@@ -123,6 +123,15 @@ async function cycle() {
 setInterval(cycle, TTL).unref()
 
 // ── What is known right now ───────────────────────────────────────────────────
+/**
+ * The process table as it was last sampled, for whoever needs to walk it rather than weigh it —
+ * today that is `servers.js`, which follows a dev server down to whichever of its children is
+ * actually holding the port. Null until the first cycle has run: the caller decides what a
+ * missing sample means, and re-reading the table here to fill the gap would undo the whole
+ * point of only sampling while somebody is looking.
+ */
+export const tree = () => (snap ? { procs: snap.procs, kids: snap.kids } : null)
+
 /**
  * What a session weighs: its whole subtree. `top` is the three biggest processes inside it,
  * and that is the answer to "why is this terminal eating so much".