k0-board 0.5.0 → 0.6.0

package/bin/k0-board.js

@@ -471,6 +471,8 @@ async function doctor() {
   else if (state.running) warn('the service is running but the server is not answering')
   else warn('not running — `k0-board install` or `k0-board start`')
 
+  await cloudReport()
+
   step('What this machine can do')
   const rows = [
     ['open terminals', capabilities.terminal.pasteWithoutSending || capabilities.terminal.readScreen],
@@ -514,6 +516,49 @@ async function doctor() {
   }
 }
 
+// ── k0 Cloud ─────────────────────────────────────────────────────────────────
+/**
+ * Signing in happens in the browser, on the board: that is where GitHub or Google send you back
+ * to. So this opens the board, which shows the way in when nobody is signed in yet, and says
+ * where things stand when somebody is.
+ */
+async function login() {
+  if (!(await alive())) {
+    fail('k0 is not running — `k0-board install` or `k0-board start` first')
+    process.exit(1)
+  }
+  const s = await api('/api/cloud')
+  if (!s.enabled) return warn('k0 Cloud is switched off on this machine (K0_CLOUD=off)')
+  if (s.linked && s.approved) return ok(`signed in as ${s.email || s.name}`)
+  if (s.linked) return note(`signed in as ${s.email || s.name}, waiting to be let in — the board notices by itself`)
+  const url = await openBoard()
+  say(`Sign in on the board: ${url}`)
+}
+
+async function logout() {
+  if (!(await alive())) {
+    fail('k0 is not running')
+    process.exit(1)
+  }
+  await api('/api/cloud/logout', {})
+  ok('signed out — the board stays on this machine, and stops syncing')
+}
+
+async function cloudReport() {
+  step('k0 Cloud')
+  if (!(await alive())) return warn('the server is not running, so there is nothing to ask')
+  const s = await api('/api/cloud').catch(() => null)
+  if (!s) return warn('the server did not say')
+  if (!s.enabled) return warn('switched off on this machine (K0_CLOUD=off)')
+  if (!s.linked) return warn('nobody is signed in — `k0-board login`')
+  ok(`signed in as ${s.email || s.name}`)
+  ;(s.approved ? ok : warn)(s.approved ? 'let in' : 'waiting to be let in')
+  if (s.needs_move) warn('the board on this machine has not been moved to the account yet — the board offers it')
+  ;(s.online === false ? warn : ok)(s.online === false ? 'k0 Cloud cannot be reached right now' : 'k0 Cloud answers')
+  if (s.pending) note(`${s.pending} change${s.pending === 1 ? '' : 's'} waiting to go up`)
+  if (s.sync_error) warn(s.sync_error)
+}
+
 // ── the rest ─────────────────────────────────────────────────────────────────
 async function restart() {
   await service.restart()
@@ -547,6 +592,8 @@ ${bold('k0-board')} — a board of sticky notes that drives your Claude Code ses
   ${bold('k0-board restart')}     restart the service
   ${bold('k0-board status')}      is it running?
   ${bold('k0-board doctor')}      what this machine can and cannot do, and why
+  ${bold('k0-board login')}       sign in to k0 Cloud with GitHub or Google (on the board)
+  ${bold('k0-board logout')}      sign out; the board stays on this machine
 
 Options
   ${bold('--yes')}            do not ask, assume yes
@@ -556,7 +603,7 @@ Options
 `)
 }
 
-const commands = { install, uninstall, start, restart, status, doctor, 'shift-enter': shiftEnter }
+const commands = { install, uninstall, start, restart, status, doctor, login, logout, 'shift-enter': shiftEnter }
 
 if (flag('help') || flag('h') || command === 'help') {
   usage()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k0-board",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A board of sticky notes that drives your Claude Code sessions",
   "keywords": [
     "claude-code",
@@ -16,7 +16,7 @@
     "type": "git",
     "url": "git+https://github.com/alessio-ragni/k0-board.git"
   },
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "author": "Alessio Ragni (https://alessioragni.com)",
   "type": "module",
   "bin": {

package/server/cloud.js

@@ -0,0 +1,355 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { HOME } from './paths.js'
+
+// ── k0 Cloud ─────────────────────────────────────────────────────────────────
+// The only file in k0 that talks to the cloud. Everything that leaves this machine for it —
+// signing in, the next K number, the rows of the board — goes through the few functions below,
+// so what k0 sends and where can be read in one place. The other door out is `update.js`, which
+// asks npm once a day what the newest version is. There is no third.
+//
+// The cloud is Supabase: its own sign-in (GitHub or Google, nothing else) and its own database,
+// reached over plain HTTPS with Node's `fetch`. No client library: k0 has no dependencies, and
+// the handful of calls it needs are each a few lines.
+//
+// The address and the key below are public on purpose. The key is Supabase's "publishable" one:
+// it identifies the project and grants nothing by itself; what a signed-in person may read or
+// write is decided by the database's own row-level rules, and an account that has not been let in
+// may read and write nothing at all. The secret keys never appear in this repository.
+
+const DEFAULT_URL = 'https://pegjzrbsogextluajmjm.supabase.co'
+const DEFAULT_KEY = 'sb_publishable_Q-kGvSLvbsxiFikQxO1UEA_QiDsCamH'
+
+/** `K0_CLOUD=off` is for working on k0 itself, and for the tests: no cloud, no sign-in, no socket. */
+export const enabled = () => process.env.K0_CLOUD !== 'off'
+const base = () => (process.env.K0_CLOUD_URL || DEFAULT_URL).replace(/\/+$/, '')
+const apiKey = () => process.env.K0_CLOUD_KEY || DEFAULT_KEY
+
+/** Where the sign-in is kept: beside the database, readable by you and nobody else. */
+export const FILE = process.env.K0_CLOUD_FILE || path.join(HOME, 'cloud.json')
+
+/** The two ways in. A third is a decision, not a line of code. */
+export const PROVIDERS = ['github', 'google']
+
+const TIMEOUT = 8000
+const KEY_TIMEOUT = 2500
+
+// `fetch` is replaceable so a test can play the cloud without a socket — the same seam `update.js`
+// has, for the same reason.
+let fetcher = (...args) => globalThis.fetch(...args)
+export function useFetch(f) {
+  fetcher = f || ((...args) => globalThis.fetch(...args))
+}
+
+// ── What is kept on disk ─────────────────────────────────────────────────────
+
+let saved = null
+let savedAt = 0
+
+const mtime = () => {
+  try {
+    return fs.statSync(FILE).mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+// Read again whenever the file changes, so a sign-in finished by another k0 process — the command
+// line, a second server started by hand — is seen here without a restart.
+function load() {
+  if (saved && mtime() === savedAt) return saved
+  try {
+    saved = JSON.parse(fs.readFileSync(FILE, 'utf8'))
+  } catch {
+    saved = {}
+  }
+  savedAt = mtime()
+  if (!saved.machine) {
+    saved.machine = crypto.randomUUID()
+    store()
+  }
+  return saved
+}
+
+function store() {
+  try {
+    fs.mkdirSync(path.dirname(FILE), { recursive: true })
+    fs.writeFileSync(FILE, JSON.stringify(saved, null, 2), { mode: 0o600 })
+    // `mode` only applies when the file is created; one written before this line existed keeps
+    // whatever it had, so it is said again.
+    fs.chmodSync(FILE, 0o600)
+    savedAt = mtime()
+  } catch {
+    // A sign-in that cannot be written down is one that has to be done again next start. That is
+    // an annoyance, not a reason for the board to stop.
+  }
+}
+
+/** For the tests: forget what was read, so the next call reads the file again. */
+export function reset() {
+  saved = null
+  online = null
+  lastError = null
+  pending = null
+}
+
+export const machine = () => load().machine
+
+// ── Being online ─────────────────────────────────────────────────────────────
+
+let online = null
+let lastError = null
+
+function heard(ok, error = null) {
+  online = ok
+  lastError = ok ? null : error
+}
+
+async function request(method, url, { body = null, token = null, timeout = TIMEOUT, prefer = null } = {}) {
+  const headers = { apikey: apiKey(), accept: 'application/json' }
+  if (body != null) headers['content-type'] = 'application/json'
+  if (token) headers.authorization = `Bearer ${token}`
+  if (prefer) headers.prefer = prefer
+  let res
+  try {
+    res = await fetcher(url, {
+      method,
+      headers,
+      body: body == null ? undefined : JSON.stringify(body),
+      redirect: 'error',
+      signal: AbortSignal.timeout(timeout),
+    })
+  } catch (err) {
+    heard(false, 'k0 Cloud cannot be reached.')
+    const e = new Error('offline')
+    e.offline = true
+    e.cause = err
+    throw e
+  }
+  heard(true)
+  const text = await res.text()
+  let data = null
+  try {
+    data = text ? JSON.parse(text) : null
+  } catch {
+    data = text
+  }
+  if (!res.ok) {
+    const e = new Error((data && (data.message || data.msg || data.error_description || data.error)) || `HTTP ${res.status}`)
+    e.status = res.status
+    e.data = data
+    throw e
+  }
+  return data
+}
+
+// ── Signing in ───────────────────────────────────────────────────────────────
+// The browser does the signing in, on Supabase's page and then GitHub's or Google's; k0 never sees
+// a password. What comes back to k0 is a one-time code on its own address, and k0 trades it for
+// a session using the secret half of a pair it made before sending the browser off (PKCE): a code
+// that leaked on the way back is worth nothing to anybody who does not also hold that half.
+
+/** The sign-in started last, waiting for its code. One at a time; an older one is forgotten. */
+let pending = null
+
+const b64url = (buf) => Buffer.from(buf).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+
+/** The address to send the browser to. `redirect` is k0's own callback page on this machine. */
+export function loginUrl(provider, redirect) {
+  if (!PROVIDERS.includes(provider)) throw new Error(`Sign in with ${PROVIDERS.join(' or ')}.`)
+  const verifier = b64url(crypto.randomBytes(48))
+  const challenge = b64url(crypto.createHash('sha256').update(verifier).digest())
+  pending = { verifier, at: Date.now() }
+  const q = new URLSearchParams({
+    provider,
+    redirect_to: redirect,
+    code_challenge: challenge,
+    code_challenge_method: 's256',
+  })
+  return `${base()}/auth/v1/authorize?${q}`
+}
+
+/** The code came back. Trade it for a session, and find out who this is and whether they are in. */
+export async function finishLogin(code) {
+  if (!pending || Date.now() - pending.at > 15 * 60_000) throw new Error('This sign-in has expired. Start it again from the board.')
+  const verifier = pending.verifier
+  pending = null
+  const data = await request('POST', `${base()}/auth/v1/token?grant_type=pkce`, {
+    body: { auth_code: String(code), code_verifier: verifier },
+  })
+  keep(data)
+  await refreshMe()
+  return status()
+}
+
+function keep(data) {
+  const s = load()
+  s.session = {
+    access_token: data.access_token,
+    refresh_token: data.refresh_token,
+    expires_at: Number(data.expires_at) || Math.floor(Date.now() / 1000) + Number(data.expires_in || 3600),
+  }
+  store()
+}
+
+/** A token good for at least another minute, refreshed first when it is about to run out. */
+async function token() {
+  const s = load()
+  if (!s.session?.refresh_token) return null
+  if (s.session.access_token && s.session.expires_at * 1000 - Date.now() > 60_000) return s.session.access_token
+  try {
+    const data = await request('POST', `${base()}/auth/v1/token?grant_type=refresh_token`, {
+      body: { refresh_token: s.session.refresh_token },
+    })
+    keep(data)
+    return data.access_token
+  } catch (err) {
+    // Offline is not signed out: the board carries on and asks again later. A refusal is — the
+    // session was revoked or has expired for good, and the only way back is to sign in again.
+    if (!err.offline && err.status >= 400 && err.status < 500) forget()
+    throw err
+  }
+}
+
+async function authed(method, pathname, opts = {}) {
+  const t = await token()
+  if (!t) {
+    const e = new Error('Not signed in.')
+    e.status = 401
+    throw e
+  }
+  return request(method, `${base()}${pathname}`, { ...opts, token: t })
+}
+
+function forget() {
+  const s = load()
+  delete s.session
+  delete s.me
+  delete s.pulled
+  store()
+}
+
+/** Who this is, whether they have been let in, and where their rows go. */
+export async function refreshMe() {
+  const me = await authed('POST', '/rest/v1/rpc/k0_me', { body: {} })
+  const s = load()
+  s.me = me || null
+  store()
+  return s.me
+}
+
+export async function logout() {
+  const s = load()
+  const t = s.session?.access_token
+  forget()
+  if (t) {
+    try {
+      await request('POST', `${base()}/auth/v1/logout`, { token: t, body: {} })
+    } catch {
+      // Signed out here is signed out. The cloud lets the token expire on its own.
+    }
+  }
+  return status()
+}
+
+// ── What the board shows about it ────────────────────────────────────────────
+
+export const linked = () => enabled() && !!load().session?.refresh_token
+export const me = () => (linked() ? load().me || null : null)
+export const approved = () => !!me()?.approved
+export const workspace = () => me()?.workspace || null
+
+export function status() {
+  const m = me()
+  return {
+    enabled: enabled(),
+    linked: linked(),
+    email: m?.email ?? null,
+    name: m?.name ?? null,
+    avatar_url: m?.avatar_url ?? null,
+    approved: !!m?.approved,
+    is_admin: !!m?.is_admin,
+    online,
+    error: lastError,
+  }
+}
+
+/** Which ways in are switched on in the cloud. Asked rarely: it changes when somebody sets one up. */
+let providersSeen = null
+export async function providers() {
+  if (providersSeen && Date.now() - providersSeen.at < 10 * 60_000) return providersSeen.list
+  try {
+    const data = await request('GET', `${base()}/auth/v1/settings`)
+    const list = PROVIDERS.filter((p) => data?.external?.[p])
+    providersSeen = { list, at: Date.now() }
+    return list
+  } catch {
+    return providersSeen?.list ?? null
+  }
+}
+
+// ── The next number ──────────────────────────────────────────────────────────
+
+/**
+ * The next K number for this account, or null when it cannot be had right now — not signed in,
+ * not let in, or no answer within a couple of seconds. Null is not an error: the story is made
+ * with a provisional key and the sync gives it its real one later.
+ */
+export async function nextKey() {
+  if (!linked() || !approved() || !workspace()) return null
+  try {
+    const n = await authed('POST', '/rest/v1/rpc/k0_next_key', { body: { ws: workspace() }, timeout: KEY_TIMEOUT })
+    return Number.isInteger(n) && n > 0 ? n : null
+  } catch {
+    return null
+  }
+}
+
+/** Moves the cloud's counter past numbers this machine already holds. */
+export async function reserveKeys(upto) {
+  return authed('POST', '/rest/v1/rpc/k0_reserve_keys', { body: { ws: workspace(), upto } })
+}
+
+// ── Rows ─────────────────────────────────────────────────────────────────────
+
+/** Sends rows. Each is `{ kind, uid, data, deleted, changed_at }`. */
+export async function push(rows) {
+  if (!rows.length) return 0
+  const ws = workspace()
+  const body = rows.map((r) => ({
+    workspace_id: ws,
+    kind: r.kind,
+    uid: r.uid,
+    data: r.data ?? {},
+    deleted: !!r.deleted,
+    changed_at: r.changed_at ?? Date.now(),
+    machine: machine(),
+  }))
+  await authed('POST', '/rest/v1/records?on_conflict=workspace_id,kind,uid', {
+    body,
+    prefer: 'resolution=merge-duplicates,return=minimal',
+  })
+  return body.length
+}
+
+/** What other machines wrote since `since`, oldest first. */
+export async function pull(since = 0, limit = 500) {
+  const q = new URLSearchParams({
+    select: 'kind,uid,data,deleted,changed_at,seq',
+    workspace_id: `eq.${workspace()}`,
+    seq: `gt.${Number(since) || 0}`,
+    machine: `neq.${machine()}`,
+    order: 'seq.asc',
+    limit: String(limit),
+  })
+  return (await authed('GET', `/rest/v1/records?${q}`)) || []
+}
+
+/** How far this machine has read. Kept with the sign-in, because it means nothing without it. */
+export const pulledTo = () => Number(load().pulled) || 0
+export function setPulledTo(seq) {
+  const s = load()
+  s.pulled = Number(seq) || 0
+  store()
+}