@oakgreencc/cambium 0.0.15 → 0.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -29,6 +29,7 @@ cambium status
29
29
  | `cambium run task --issue <n> [--repo <owner/name>]` | Claim one open `q:task` issue, run its worker in the foreground, then make the same transition the daemon would. |
30
30
  | `cambium run <graph> --issue <n> [--repo <owner/name>] [--follow]` | `engine: "graph"` only (`task` is the one graph today). Advance one issue through the graph runtime in the foreground: a `q:task` issue without a lease starts with a foreground worker; anything else resumes where its marker rests. Stops at the first wait that is not ready; `--follow` re-reads and polls every `tickSeconds` until the graph ends. |
31
31
  | `cambium install [--dry-run]` | Write the launchd agent (`KeepAlive`, `RunAtLoad`) for `start --config <this config>`; `--dry-run` prints it. It does not call `launchctl`; it prints the command. |
32
+ | `cambium update [--check] [--version <v>]` | Install the latest version (or `<v>`, even an older one) from npm into this global install, then SIGTERM the launchd agent so it finishes its tick and KeepAlive starts the new version. `--check` only reports. No config file needed. See [Self-update](#self-update). |
32
33
 
33
34
  Every command takes `--config <file>`; the default is `$CAMBIUM_CONFIG`, then `~/.cambium/config.json`.
34
35
 
@@ -111,7 +112,8 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
111
112
  },
112
113
  "logs": { "keepPerIssue": 20, "daemonMaxBytes": 10485760 },
113
114
  "graft": { "command": "graft", "app": null, "botLogin": null },
114
- "worker": { "command": "claude", "args": [], "graftApp": null, "fetch": true, "env": {} }
115
+ "worker": { "command": "claude", "args": [], "graftApp": null, "fetch": true, "env": {} },
116
+ "update": { "auto": false, "checkMinutes": 360 }
115
117
  }
116
118
  ```
117
119
 
@@ -152,6 +154,14 @@ How a repo's worktrees are made is the repo's call: a `"cambium"` key in its roo
152
154
 
153
155
  The key decides which commands run on this host, so list `package.json` as protected (CODEOWNERS) in the target repo, next to its `"graft"` policy.
154
156
 
157
+ ## Self-update
158
+
159
+ cambium updates itself only when it is a **global npm install** (`<prefix>/lib/node_modules/@oakgreencc/cambium`, e.g. nvm's or Homebrew's prefix), and only into that same prefix, so the launchd agent's node and bin paths stay valid. A source checkout (`pnpm start`), an `npm link` or a copy inside another package's `node_modules` is left to whoever installed it. npm is the one next to the running Node, else `npm` on `PATH`; the version is the registry's `latest` dist-tag.
160
+
161
+ - **`cambium update`** installs, then `launchctl kill TERM gui/<uid>/com.oakgreencc.cambium`: the daemon finishes its tick and exits, and KeepAlive starts the new version. Workers keep running and are re-adopted. When the agent is not loaded it only installs.
162
+ - **`"update": { "auto": true }`** (off by default; reloaded with the config) makes the daemon check every `update.checkMinutes` (default 360, at least 5) between ticks. On a newer version it installs it, logs `updating cambium a → b`, and ends its loop; the process exits and launchd starts the new one. Only when it is the launchd agent (`XPC_SERVICE_NAME=com.oakgreencc.cambium`), since nothing else would bring it back; otherwise, or when it is not a global install, it logs why once and skips. A failed check or install is a warning and is retried at the next check. The last check time is `update.lastCheck` in the SQLite `control` table.
163
+ - The plist is never rewritten, so env added by hand (e.g. `OTEL_*`) survives an update. To pick up a plist change, `oakgreen reload cambium`.
164
+
155
165
  ## Heartbeat (`state.json`)
156
166
 
157
167
  Written at the end of every tick to `paths.heartbeat` (default `~/.cambium/state.json`), whole and renamed into place, so a reader never sees a partial file. canopy reads it. `version` changes only on an incompatible change. All times are ISO 8601 UTC strings; durations are milliseconds.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.15",
3
+ "version": "0.0.16",
4
4
  "description": "The scheduler daemon: reads the q:* queues from GitHub every tick, runs headless claude workers in their own worktrees up to a cap, and makes every queue transition itself.",
5
5
  "license": "AGPL-3.0-only",
6
6
  "type": "module",
package/src/cli.mjs CHANGED
@@ -15,8 +15,9 @@ import { openStore } from './store.mjs'
15
15
  import { finish, newCtx, startTask } from './tick.mjs'
16
16
  import { runIssue } from './graph-engine.mjs'
17
17
  import { createTelemetry } from './tracing.mjs'
18
+ import { defaultExec, realUpdater, runUpdate, VERSION } from './update.mjs'
18
19
 
19
- export const VERSION = '0.0.0'
20
+ export { VERSION }
20
21
 
21
22
  export const HELP = `cambium ${VERSION} — the scheduler daemon
22
23
 
@@ -31,6 +32,9 @@ export const HELP = `cambium ${VERSION} — the scheduler daemon
31
32
  engine "graph": advance the issue in the foreground to the first wait
32
33
  that is not ready; --follow keeps polling until the graph ends
33
34
  cambium install [--dry-run] write the launchd agent (KeepAlive); --dry-run prints it
35
+ cambium update [--check] [--version <v>]
36
+ install the latest (or <v>) from npm into this global install, then
37
+ restart the launchd agent onto it; --check only reports
34
38
 
35
39
  Common: --config <file> (default $CAMBIUM_CONFIG, then ~/.cambium/config.json)`
36
40
 
@@ -69,6 +73,9 @@ async function withTelemetry(deps, io, fn) {
69
73
  * signal?: AbortSignal,
70
74
  * now?: () => number,
71
75
  * sleep?: (ms: number) => Promise<void>,
76
+ * updater?: import('./update.mjs').Updater,
77
+ * exec?: import('./update.mjs').Exec,
78
+ * uid?: number,
72
79
  * }} IO
73
80
  */
74
81
 
@@ -83,6 +90,22 @@ export async function main(argv, io) {
83
90
  io.out(VERSION)
84
91
  return 0
85
92
  }
93
+ if (verb === 'update') {
94
+ try {
95
+ const r = await runUpdate(
96
+ { check: has(rest, '--check'), version: flag(rest, '--version') },
97
+ {
98
+ updater: io.updater ?? realUpdater(),
99
+ exec: io.exec ?? defaultExec,
100
+ uid: io.uid ?? process.getuid?.() ?? 0,
101
+ out: io.out,
102
+ },
103
+ )
104
+ return r.ok ? 0 : fail(io, /** @type {string} */ (r.error))
105
+ } catch (err) {
106
+ return fail(io, `update: ${/** @type {Error} */ (err)?.message ?? err}`)
107
+ }
108
+ }
86
109
  const cfgPath = configPath(flag(rest, '--config'), io.env)
87
110
  const config = loadConfig(cfgPath)
88
111
  const depsFor = io.deps ?? ((c) => realDeps(c, { echo: io.out }))
@@ -93,7 +116,12 @@ export async function main(argv, io) {
93
116
  const deps = depsFor(config)
94
117
  acquireLock(deps.store, deps.procs, deps.pid ?? process.pid)
95
118
  await withTelemetry(deps, io, () =>
96
- runDaemon(deps, { signal: io.signal, once: has(rest, '--once'), reload: () => loadConfig(cfgPath) }),
119
+ runDaemon(deps, {
120
+ signal: io.signal,
121
+ once: has(rest, '--once'),
122
+ reload: () => loadConfig(cfgPath),
123
+ env: io.env,
124
+ }),
97
125
  )
98
126
  return 0
99
127
  }
package/src/config.mjs CHANGED
@@ -28,6 +28,7 @@ import { join, resolve } from 'node:path'
28
28
  * logs: { keepPerIssue: number, daemonMaxBytes: number },
29
29
  * graft: { command: string, app: string | null, botLogin: string | null },
30
30
  * worker: { command: string, args: string[], graftApp: string | null, fetch: boolean, env: Record<string, string> },
31
+ * update: { auto: boolean, checkMinutes: number },
31
32
  * }} Config
32
33
  */
33
34
 
@@ -57,6 +58,7 @@ export function defaults(home = DEFAULT_HOME) {
57
58
  logs: { keepPerIssue: 20, daemonMaxBytes: 10 * 1024 * 1024 },
58
59
  graft: { command: 'graft', app: null, botLogin: null },
59
60
  worker: { command: 'claude', args: [], graftApp: null, fetch: true, env: {} },
61
+ update: { auto: false, checkMinutes: 360 },
60
62
  }
61
63
  }
62
64
 
@@ -111,6 +113,8 @@ export function resolveConfig(raw = {}) {
111
113
  Object.values(wenv).some((v) => typeof v !== 'string')
112
114
  )
113
115
  throw new Error('config: worker.env must be an object of string values')
116
+ if (typeof config.update.auto !== 'boolean') throw new Error('config: update.auto must be true or false')
117
+ if (!(Number(config.update.checkMinutes) >= 5)) throw new Error('config: update.checkMinutes must be at least 5')
114
118
  if (config.engine !== 'legacy' && config.engine !== 'graph')
115
119
  throw new Error(`config: engine must be "legacy" or "graph", got ${JSON.stringify(config.engine)}`)
116
120
  return config
package/src/daemon.mjs CHANGED
@@ -6,6 +6,7 @@ import { applyReload } from './config.mjs'
6
6
  import { graftGitHub } from './github.mjs'
7
7
  import { openStore } from './store.mjs'
8
8
  import { tick } from './tick.mjs'
9
+ import { autoUpdate, realUpdater } from './update.mjs'
9
10
  import { processSpawner, realProcs } from './workers.mjs'
10
11
 
11
12
  /** @param {string} path @param {unknown} state */
@@ -80,6 +81,7 @@ export function realDeps(config, { echo } = {}) {
80
81
  heartbeat: (state) => writeHeartbeat(config.paths.heartbeat, state),
81
82
  daemonStartedAt: Date.now(),
82
83
  pid: process.pid,
84
+ updater: realUpdater(),
83
85
  }
84
86
  }
85
87
 
@@ -101,12 +103,14 @@ export function acquireLock(store, procs, pid) {
101
103
  * @param {import('./tick.mjs').Deps} deps
102
104
  * @param {{
103
105
  * signal?: AbortSignal, wait?: (ms: number, signal?: AbortSignal) => Promise<unknown>, once?: boolean,
104
- * reload?: () => import('./config.mjs').Config,
106
+ * reload?: () => import('./config.mjs').Config, env?: Record<string, string | undefined>,
105
107
  * }} [opts]
108
+ * After each tick, with `update.auto`, {@link autoUpdate} may install a newer cambium; the loop then ends so
109
+ * the process exits and launchd starts the new version.
106
110
  */
107
111
  export async function runDaemon(
108
112
  deps,
109
- { signal, wait = (ms, s) => sleep(ms, undefined, { signal: s }), once = false, reload } = {},
113
+ { signal, wait = (ms, s) => sleep(ms, undefined, { signal: s }), once = false, reload, env = process.env } = {},
110
114
  ) {
111
115
  let n = 0
112
116
  /** @type {string | null} */
@@ -136,6 +140,10 @@ export async function runDaemon(
136
140
  }
137
141
  // Every span is ended within its tick; export them now rather than when the batch fills.
138
142
  await deps.telemetry?.flush().catch((err) => deps.log('warn', `telemetry flush: ${err?.message ?? err}`))
143
+ if (deps.updater && !signal?.aborted) {
144
+ const installed = await autoUpdate(deps, { updater: deps.updater, env, now: deps.clock.now() })
145
+ if (installed) break
146
+ }
139
147
  if (once) break
140
148
  try {
141
149
  await wait(deps.config.tickSeconds * 1000, signal)
package/src/tick.mjs CHANGED
@@ -36,6 +36,7 @@ import { DISPATCH_NOT_BUILT, dispatchNotBuilt } from './phases/dispatch.mjs'
36
36
  * release?: import('./phases/release.mjs').Release,
37
37
  * tickNumber?: number,
38
38
  * telemetry?: import('./tracing.mjs').Telemetry,
39
+ * updater?: import('./update.mjs').Updater,
39
40
  * daemonStartedAt?: number,
40
41
  * pid?: number,
41
42
  * }} Deps
package/src/update.mjs ADDED
@@ -0,0 +1,185 @@
1
+ // @ts-check
2
+ /**
3
+ * Self-update. cambium updates itself only when it is a global npm install (`<prefix>/lib/node_modules/
4
+ * @oakgreencc/cambium`), into that same prefix, so the launchd agent's paths stay valid. A source checkout, a
5
+ * workspace link or a copy inside another package's node_modules is left to whoever installed it.
6
+ *
7
+ * - `cambium update` installs the latest version, then has the launchd agent restart onto it (SIGTERM; it
8
+ * finishes its tick, exits, and KeepAlive starts it again).
9
+ * - With `update.auto`, the daemon checks every `update.checkMinutes`; on a newer version it installs it and
10
+ * exits between ticks, and launchd's KeepAlive starts it again on the new code. Only under launchd: anywhere
11
+ * else nothing would bring it back.
12
+ */
13
+ import { execFile } from 'node:child_process'
14
+ import { existsSync, readFileSync, realpathSync } from 'node:fs'
15
+ import { dirname, join } from 'node:path'
16
+ import { fileURLToPath } from 'node:url'
17
+ import { LABEL } from './launchd.mjs'
18
+
19
+ export const PACKAGE = '@oakgreencc/cambium'
20
+ export const REGISTRY = 'https://registry.npmjs.org'
21
+ const MIN = 60_000
22
+
23
+ const PKG_DIR = fileURLToPath(new URL('..', import.meta.url))
24
+
25
+ /** The version of this copy of cambium, from its package.json. */
26
+ export const VERSION = /** @type {string} */ (JSON.parse(readFileSync(join(PKG_DIR, 'package.json'), 'utf8')).version)
27
+
28
+ /**
29
+ * @typedef {{ code: number, stdout: string, stderr: string }} ExecResult
30
+ * @typedef {(cmd: string, args: string[]) => Promise<ExecResult>} Exec
31
+ * @typedef {{
32
+ * current: string,
33
+ * installOf: () => { prefix: string, dir: string } | null,
34
+ * latest: () => Promise<string>,
35
+ * install: (prefix: string, version: string) => Promise<void>,
36
+ * }} Updater
37
+ */
38
+
39
+ /** @type {Exec} */
40
+ export const defaultExec = (cmd, args) =>
41
+ new Promise((resolve) => {
42
+ execFile(cmd, args, { maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
43
+ const code = err ? (typeof err.code === 'number' ? err.code : 1) : 0
44
+ resolve({ code, stdout: String(stdout), stderr: String(stderr || (err && !err.code ? err.message : '')) })
45
+ })
46
+ })
47
+
48
+ /**
49
+ * Where this cambium is installed, when it is a global npm install: the npm prefix and the package directory.
50
+ * @param {string} [dir] the package directory (default: this one, symlinks resolved)
51
+ */
52
+ export function installOf(dir = PKG_DIR) {
53
+ let real = dir
54
+ try {
55
+ real = realpathSync(dir)
56
+ } catch {}
57
+ const m = /^(.*)\/lib\/node_modules\/@oakgreencc\/cambium\/?$/.exec(real)
58
+ return m ? { prefix: m[1], dir: real } : null
59
+ }
60
+
61
+ /** `a` is a later x.y.z than `b` (pre-release tags are ignored). @param {string} a @param {string} b */
62
+ export function newer(a, b) {
63
+ const parts = (/** @type {string} */ v) => String(v).split('-')[0].split('.').map(Number)
64
+ const [x, y] = [parts(a), parts(b)]
65
+ for (let i = 0; i < 3; i++) {
66
+ const d = (x[i] || 0) - (y[i] || 0)
67
+ if (d) return d > 0
68
+ }
69
+ return false
70
+ }
71
+
72
+ /**
73
+ * The `latest` dist-tag from the registry.
74
+ * @param {{ fetch?: typeof globalThis.fetch, registry?: string }} [o]
75
+ */
76
+ export async function latestVersion({ fetch = globalThis.fetch, registry = REGISTRY } = {}) {
77
+ const res = await fetch(`${registry}/${PACKAGE.replace('/', '%2f')}/latest`, {
78
+ headers: { accept: 'application/json' },
79
+ })
80
+ if (!res.ok) throw new Error(`registry answered ${res.status} for ${PACKAGE}`)
81
+ const v = /** @type {any} */ (await res.json())?.version
82
+ if (typeof v !== 'string' || !/^\d+\.\d+\.\d+/.test(v)) throw new Error(`registry gave no version for ${PACKAGE}`)
83
+ return v
84
+ }
85
+
86
+ /** npm next to this Node (nvm, Homebrew and the official installer put it there), else npm on PATH. */
87
+ export function npmBin(node = process.execPath) {
88
+ const beside = join(dirname(node), 'npm')
89
+ return existsSync(beside) ? beside : 'npm'
90
+ }
91
+
92
+ /**
93
+ * `npm install -g --prefix <prefix> @oakgreencc/cambium@<version>`; throws with npm's output on failure.
94
+ * @param {Exec} exec @param {string} prefix @param {string} version
95
+ */
96
+ export async function npmInstall(exec, prefix, version) {
97
+ const r = await exec(npmBin(), ['install', '--global', '--prefix', prefix, `${PACKAGE}@${version}`])
98
+ if (r.code !== 0) throw new Error(`npm install ${PACKAGE}@${version} failed: ${(r.stderr || r.stdout).trim()}`)
99
+ }
100
+
101
+ /** The real updater. @param {{ exec?: Exec, fetch?: typeof globalThis.fetch }} [o] @returns {Updater} */
102
+ export function realUpdater({ exec = defaultExec, fetch } = {}) {
103
+ return {
104
+ current: VERSION,
105
+ installOf: () => installOf(),
106
+ latest: () => latestVersion({ fetch }),
107
+ install: (prefix, version) => npmInstall(exec, prefix, version),
108
+ }
109
+ }
110
+
111
+ /** Is this process the launchd agent (KeepAlive brings it back after an exit)? @param {Record<string, string | undefined>} env */
112
+ export const underLaunchd = (env) => env.XPC_SERVICE_NAME === LABEL
113
+
114
+ /**
115
+ * The daemon's between-ticks check. Returns the version it installed (the caller then exits so launchd restarts
116
+ * it), or null. Never throws: a failed check or install is logged and retried at the next `checkMinutes`.
117
+ *
118
+ * @param {import('./tick.mjs').Deps} deps
119
+ * @param {{ updater: Updater, env: Record<string, string | undefined>, now: number }} o
120
+ * @returns {Promise<string | null>}
121
+ */
122
+ export async function autoUpdate(deps, { updater, env, now }) {
123
+ const { auto, checkMinutes } = deps.config.update
124
+ if (!auto) return null
125
+ const last = Number(deps.store.get('update.lastCheck')) || 0
126
+ if (now - last < checkMinutes * MIN) return null
127
+ deps.store.set('update.lastCheck', String(now))
128
+ const skip = (/** @type {string} */ why) => {
129
+ if (deps.store.get('update.skipped') !== why) deps.log('warn', `auto-update skipped: ${why}`)
130
+ deps.store.set('update.skipped', why)
131
+ return null
132
+ }
133
+ if (!underLaunchd(env)) return skip('not running as the launchd agent, so nothing would restart it')
134
+ const where = updater.installOf()
135
+ if (!where) return skip('not a global npm install; update it the way it was installed')
136
+ try {
137
+ const latest = await updater.latest()
138
+ if (!newer(latest, updater.current)) return null
139
+ deps.log('info', `updating cambium ${updater.current} → ${latest} in ${where.prefix}`)
140
+ await updater.install(where.prefix, latest)
141
+ deps.log('info', `cambium ${latest} installed; exiting so launchd starts the new version`)
142
+ return latest
143
+ } catch (err) {
144
+ deps.log('warn', `auto-update: ${/** @type {Error} */ (err)?.message ?? err}`)
145
+ return null
146
+ }
147
+ }
148
+
149
+ /**
150
+ * `cambium update [--check] [--version <v>]`: report or install, then restart the launchd agent when it runs.
151
+ *
152
+ * @param {{ check: boolean, version?: string }} opts
153
+ * @param {{ updater: Updater, exec: Exec, uid: number, out: (s: string) => void }} io
154
+ * @returns {Promise<{ ok: boolean, error?: string }>}
155
+ */
156
+ export async function runUpdate({ check, version }, { updater, exec, uid, out }) {
157
+ const target = version ?? (await updater.latest())
158
+ if (!newer(target, updater.current) && !version) {
159
+ out(`cambium ${updater.current} is up to date`)
160
+ return { ok: true }
161
+ }
162
+ if (check) {
163
+ out(`cambium ${updater.current} → ${target} available; run \`cambium update\``)
164
+ return { ok: true }
165
+ }
166
+ const where = updater.installOf()
167
+ if (!where)
168
+ return {
169
+ ok: false,
170
+ error: `this cambium is not a global npm install (${PACKAGE} under <prefix>/lib/node_modules); update it the way it was installed`,
171
+ }
172
+ out(`installing ${PACKAGE}@${target} into ${where.prefix}…`)
173
+ await updater.install(where.prefix, target)
174
+ out(`installed cambium ${target}`)
175
+ const service = `gui/${uid}/${LABEL}`
176
+ if ((await exec('launchctl', ['print', service])).code !== 0) {
177
+ out('the launchd agent is not loaded; start cambium yourself to run the new version')
178
+ return { ok: true }
179
+ }
180
+ // SIGTERM, not `kickstart -k`: the daemon finishes its current tick, exits, and KeepAlive starts the new version.
181
+ const r = await exec('launchctl', ['kill', 'TERM', service])
182
+ if (r.code !== 0) return { ok: false, error: `launchctl kill TERM ${service}: ${(r.stderr || r.stdout).trim()}` }
183
+ out(`stopping ${LABEL} after its current tick; launchd starts ${target} (workers keep running and are re-adopted)`)
184
+ return { ok: true }
185
+ }