k0-board 0.1.2 → 0.2.0

package/server/changelog.js

@@ -0,0 +1,242 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import * as db from './db.js'
+import * as git from './git.js'
+import { listProjects, projectName } from './projects.js'
+
+// ── What you have been doing ─────────────────────────────────────────────────
+// The board says what is happening now. This says what happened, which is a different
+// question and needs a different source: git already keeps that diary, perfectly, and has
+// been keeping it since long before k0 existed.
+//
+// So nothing here is stored. There is no table, no nightly run, no index to keep in step with
+// reality — the facts are read from git and from `session_event` when somebody asks for them.
+// A cache would be wrong more often than it helped anyway: "today" changes while you are
+// reading it, and "this week" contains today.
+//
+// This module gathers. It writes no prose and calls no model: that is `writer.js`.
+
+const DAY = 24 * 60 * 60 * 1000
+const LOOKBACK = 30 * DAY // how far back "the last day you worked" is willing to look
+const CONCURRENCY = 4 // git processes at once: enough to be quick, few enough to stay polite
+const CHANGELOG_HEAD = 64 * 1024 // `[Unreleased]` lives at the top; the rest is history
+
+export const PERIODS = ['today', 'yesterday', 'week', 'month']
+
+const startOfDay = (t) => {
+  const d = new Date(t)
+  d.setHours(0, 0, 0, 0)
+  return d.getTime()
+}
+
+/**
+ * The four windows, in local time, because a day is a day where the person is — not where the
+ * server thinks it is. `week` and `month` roll backwards from today rather than snapping to a
+ * calendar Monday or a first of the month: on the 2nd, a calendar month would be two days.
+ *
+ * `last` is not here: which day that is depends on the data, so it is decided in `facts()`.
+ */
+export function windowFor(period, now = Date.now()) {
+  const today = startOfDay(now)
+  const tomorrow = today + DAY
+  if (period === 'today') return { period, from: today, to: tomorrow }
+  if (period === 'yesterday') return { period, from: today - DAY, to: today }
+  if (period === 'week') return { period, from: today - 6 * DAY, to: tomorrow }
+  if (period === 'month') return { period, from: today - 29 * DAY, to: tomorrow }
+  return null
+}
+
+/**
+ * The most recent day that has anything in it — the one the page opens on.
+ *
+ * Not "yesterday": on a Monday yesterday is Sunday, and a page that opens empty after every
+ * weekend teaches you not to open it. This is the same idea `web/recency.js` already uses to
+ * decide which columns are still warm — anchored to the work rather than to the clock.
+ */
+export function lastActiveDay(stamps, now = Date.now()) {
+  let best = null
+  for (const t of stamps) {
+    if (!Number.isFinite(t) || t > now) continue
+    if (best === null || t > best) best = t
+  }
+  return best === null ? null : startOfDay(best)
+}
+
+/**
+ * The `[Unreleased]` lines of a Keep a Changelog file: written down, not yet released.
+ * Everything from that heading to the next one at the same level or higher.
+ */
+export function unreleasedSection(md) {
+  const lines = String(md ?? '').split('\n')
+  const start = lines.findIndex((l) => /^#{1,3}\s*\[?unreleased\]?/i.test(l))
+  if (start === -1) return null
+  const depth = (/^(#+)/.exec(lines[start]) || [, '##'])[1].length
+  const out = []
+  for (let i = start + 1; i < lines.length; i++) {
+    const m = /^(#+)\s/.exec(lines[i])
+    if (m && m[1].length <= depth) break
+    const line = lines[i].trim()
+    if (line) out.push(line)
+  }
+  return out.length ? out : null
+}
+
+/**
+ * Does this repository belong in the summary at all?
+ *
+ * This is the rule that keeps the page honest. A repository that has been dirty since March
+ * and that you have not opened since is not news, and a summary that repeats it every single
+ * morning is a summary you stop reading. Something has to have happened IN the window — a
+ * commit, a file saved, a card moved — and only then is it worth saying what is still
+ * outstanding there.
+ */
+export function isActive(repo) {
+  return !!(repo && (repo.commits.length || repo.dirty.length || repo.cards.length))
+}
+
+/** Keeps only what falls inside a window, and drops the repositories left with nothing. */
+export function narrow(repos, from, to) {
+  const inside = (t) => Number.isFinite(t) && t >= from && t < to
+  return repos
+    .map((r) => ({
+      ...r,
+      commits: r.commits.filter((c) => inside(Date.parse(c.at))),
+      dirty: r.dirty.filter((f) => inside(f.at)),
+      cards: r.cards.filter((c) => inside(c.touched)),
+    }))
+    .filter(isActive)
+}
+
+/** Runs the work a few at a time: dozens of repositories must not become dozens of processes. */
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length)
+  let next = 0
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    for (let i = next++; i < items.length; i = next++) out[i] = await fn(items[i], i)
+  })
+  await Promise.all(workers)
+  return out
+}
+
+function unreleasedOf(dir) {
+  const file = path.join(dir, 'CHANGELOG.md')
+  try {
+    const fd = fs.openSync(file, 'r')
+    try {
+      const buf = Buffer.alloc(CHANGELOG_HEAD)
+      const read = fs.readSync(fd, buf, 0, CHANGELOG_HEAD, 0)
+      return unreleasedSection(buf.subarray(0, read).toString('utf8'))
+    } finally {
+      fs.closeSync(fd)
+    }
+  } catch {
+    return null // no changelog is the normal case, not a problem to report
+  }
+}
+
+/** When each hanging file was last saved. A path that has vanished under us is simply skipped. */
+function stampDirty(dir, paths) {
+  const out = []
+  for (const rel of paths) {
+    try {
+      out.push({ path: rel, at: fs.statSync(path.join(dir, rel)).mtimeMs })
+    } catch {
+      /* gone between the listing and the stat */
+    }
+  }
+  return out
+}
+
+async function gather(from, to) {
+  const projects = listProjects().filter((p) => fs.existsSync(path.join(p.path, '.git')))
+  const cards = db.eventsBetween(from, to)
+  const byRepo = new Map()
+  for (const c of cards) {
+    if (!byRepo.has(c.project_path)) byRepo.set(c.project_path, [])
+    byRepo.get(c.project_path).push(c)
+  }
+
+  const repos = await mapLimit(projects, CONCURRENCY, async (p) => {
+    const [h, dirty] = await Promise.all([git.history(p.path, { from, to }), git.dirtyFiles(p.path)])
+    if (!h) return null
+    return {
+      name: projectName(p.path),
+      path: p.path,
+      remote: h.remote,
+      unpushedTotal: h.unpushedTotal,
+      commits: h.commits.map((c) => ({
+        sha: c.sha.slice(0, 7),
+        at: c.at,
+        subject: c.subject,
+        body: c.body,
+        online: c.online,
+      })),
+      dirty: stampDirty(p.path, dirty),
+      dirtyTotal: dirty.length,
+      unreleased: unreleasedOf(p.path),
+      cards: (byRepo.get(p.path) ?? []).map((c) => ({
+        title: c.title,
+        description: c.description || '',
+        status: c.status,
+        touched: c.touched,
+        done: c.status === 'COMPLETED',
+      })),
+    }
+  })
+  return repos.filter(Boolean)
+}
+
+/** The one-line arithmetic the page and the writer both need, worked out once. */
+export function totals(repos) {
+  let commits = 0
+  let online = 0
+  let local = 0
+  let dirty = 0
+  let cardsOpen = 0
+  let cardsDone = 0
+  for (const r of repos) {
+    commits += r.commits.length
+    for (const c of r.commits) {
+      if (c.online === true) online++
+      else if (c.online === false) local++
+    }
+    dirty += r.dirty.length
+    for (const c of r.cards) {
+      if (c.done) cardsDone++
+      else cardsOpen++
+    }
+  }
+  return { repositories: repos.length, commits, online, local, dirty, cardsOpen, cardsDone }
+}
+
+/**
+ * Everything the page and the writer work from. Reads git and the board; touches nothing.
+ *
+ * `last` costs the same as any other period even though it does not know its own window yet:
+ * one pass over the lookback answers both "which day was the last one" and "what happened on
+ * it", because a month of `git log` is the same single process as a day of it.
+ */
+export async function facts(period, now = Date.now()) {
+  const wanted = windowFor(period, now)
+  const scan = wanted ?? { period: 'last', from: startOfDay(now) - LOOKBACK, to: startOfDay(now) + DAY }
+  const gathered = await gather(scan.from, scan.to)
+
+  let { from, to } = scan
+  let resolved = scan.period
+  if (!wanted) {
+    const stamps = []
+    for (const r of gathered) {
+      for (const c of r.commits) stamps.push(Date.parse(c.at))
+      for (const f of r.dirty) stamps.push(f.at)
+      for (const c of r.cards) stamps.push(c.touched)
+    }
+    const day = lastActiveDay(stamps, now)
+    // Nothing at all in the last month: rather than an arbitrary day, show today and say so.
+    from = day ?? startOfDay(now)
+    to = from + DAY
+    resolved = 'last'
+  }
+
+  const repos = narrow(gathered, from, to).sort((a, b) => b.commits.length - a.commits.length || a.name.localeCompare(b.name))
+  return { period: resolved, from, to, repos, totals: totals(repos) }
+}

package/server/db.js

@@ -52,6 +52,18 @@ db.exec(`
     "key"   TEXT PRIMARY KEY,
     "value" TEXT NOT NULL
   );
+
+  -- The dev server k0 started for a repository, and is therefore responsible for. It is
+  -- deliberately not a record of what is RUNNING — that is read from the machine every few
+  -- seconds and nothing here could be trusted to keep up with it. It is a record of intent:
+  -- a row means "k0 started this and it is meant to be up", which is what tells a server that
+  -- fell over apart from one that was switched off. Stopping deletes the row.
+  CREATE TABLE IF NOT EXISTS dev_server (
+    project_path TEXT PRIMARY KEY,
+    pid          INTEGER NOT NULL,
+    command      TEXT NOT NULL,
+    started_at   INTEGER NOT NULL
+  );
 `)
 
 // Additive migrations: the column may be missing from a database created before it existed.
@@ -230,6 +242,28 @@ export function deleteCard(id) {
   db.prepare('DELETE FROM card WHERE id = ?').run(id)
 }
 
+/**
+ * The cards that moved inside a window, one row each, with where they got to.
+ *
+ * `session_event` has been keeping this diary since the beginning — a row every time a card
+ * really changes status, and none when nothing happens — and until now the only thing anybody
+ * ever asked it was how old the current status is. This is the first question that reads it as
+ * what it is: a history.
+ *
+ * `touched` is when the card last moved inside the window, not when it moved last: a card
+ * finished on Tuesday belongs to Tuesday even if it was reopened on Friday.
+ */
+export function eventsBetween(from, to) {
+  return db.prepare(`
+    SELECT c.id, c.title, c.description, c.project_path, c.status, c.completed_at,
+           MAX(e.at) AS touched, COUNT(e.id) AS moves
+    FROM session_event e JOIN card c ON c.id = e.card_id
+    WHERE e.at >= ? AND e.at < ?
+    GROUP BY c.id
+    ORDER BY touched DESC
+  `).all(from, to)
+}
+
 // ── The switches that remember ───────────────────────────────────────────────
 /** The caller decides what a missing row means: this returns `fallback`. */
 export function getPref(key, fallback = null) {
@@ -249,6 +283,30 @@ export function dropPref(key) {
   db.prepare('DELETE FROM pref WHERE "key" = ?').run(key)
 }
 
+// ── The dev servers k0 started ───────────────────────────────────────────────
+// See the comment on the table: a row is intent, not observation.
+
+export function listDevServers() {
+  return db.prepare('SELECT project_path, pid, command, started_at FROM dev_server').all()
+}
+
+export function getDevServer(projectPath) {
+  return db.prepare('SELECT project_path, pid, command, started_at FROM dev_server WHERE project_path = ?')
+    .get(projectPath) ?? null
+}
+
+export function setDevServer(projectPath, { pid, command, startedAt }) {
+  db.prepare(`
+    INSERT INTO dev_server (project_path, pid, command, started_at) VALUES (?, ?, ?, ?)
+    ON CONFLICT(project_path) DO UPDATE SET
+      pid = excluded.pid, command = excluded.command, started_at = excluded.started_at
+  `).run(projectPath, pid, command, startedAt)
+}
+
+export function clearDevServer(projectPath) {
+  db.prepare('DELETE FROM dev_server WHERE project_path = ?').run(projectPath)
+}
+
 /**
  * Letting go of the file. It matters in exactly one place — a test that wants to delete the
  * database it was pointed at — and it matters on exactly one platform: POSIX lets a file be

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
+}