@oakgreencc/cambium 0.0.15 → 0.0.17

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
 
@@ -48,13 +49,14 @@ A requeue is `q:task` with attempt + 1, or, once `maxAttempts` are spent, `q:hum
48
49
 
49
50
  ## State on GitHub
50
51
 
51
- | Label | Meaning |
52
- | --------------------------------------------------- | ------------------------------------------------------------------------------ |
53
- | `q:intake`, `q:task`, `q:human`, `q:promote` | The queue. At most one per open issue. |
54
- | `running` | A worker holds the lease (with `q:task`). |
55
- | `why:budget`, `why:triage` (also `why:reject`, …) | Why it is in `q:human` (`why:triage`: sent there by triage, see below). |
56
- | _no `q:` label_, cambium comment, open `agent/*` PR | Submitted: in the Release Queue, which is the PR's merge-queue state. |
57
- | `priority:critical` … `priority:low` | Scheduling order (configurable). Unlabelled sorts after every listed priority. |
52
+ | Label | Meaning |
53
+ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
54
+ | `q:intake`, `q:task`, `q:human`, `q:promote` | The queue. At most one per open issue. |
55
+ | `q:promote` on a closed issue | Merged into `release.from`, not yet in `release.to` ([Awaiting promotion](#awaiting-promotion)). |
56
+ | `running` | A worker holds the lease (with `q:task`). |
57
+ | `why:budget`, `why:triage` (also `why:reject`, …) | Why it is in `q:human` (`why:triage`: sent there by triage, see below). |
58
+ | _no `q:` label_, cambium comment, open `agent/*` PR | Submitted: in the Release Queue, which is the PR's merge-queue state. |
59
+ | `priority:critical` … `priority:low` | Scheduling order (configurable). Unlabelled sorts after every listed priority. |
58
60
 
59
61
  Only cambium moves these labels; workers have `graft issue label` and `graft issue edit` denied.
60
62
 
@@ -111,7 +113,8 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
111
113
  },
112
114
  "logs": { "keepPerIssue": 20, "daemonMaxBytes": 10485760 },
113
115
  "graft": { "command": "graft", "app": null, "botLogin": null },
114
- "worker": { "command": "claude", "args": [], "graftApp": null, "fetch": true, "env": {} }
116
+ "worker": { "command": "claude", "args": [], "graftApp": null, "fetch": true, "env": {} },
117
+ "update": { "auto": false, "checkMinutes": 360 }
115
118
  }
116
119
  ```
117
120
 
@@ -152,6 +155,14 @@ How a repo's worktrees are made is the repo's call: a `"cambium"` key in its roo
152
155
 
153
156
  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
157
 
158
+ ## Self-update
159
+
160
+ 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.
161
+
162
+ - **`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.
163
+ - **`"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.
164
+ - 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`.
165
+
155
166
  ## Heartbeat (`state.json`)
156
167
 
157
168
  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.
@@ -179,7 +190,7 @@ Written at the end of every tick to `paths.heartbeat` (default `~/.cambium/state
179
190
  "intake": 0,
180
191
  "task": 3,
181
192
  "human": 1,
182
- "promote": 0, // open issues per q: label
193
+ "promote": 0, // open issues per q: label; promote also counts closed issues awaiting promotion
183
194
  "running": 2, // open issues labelled `running`
184
195
  "review": 1, // open agent/* PRs
185
196
  "workers": 2 // tracked worker processes on this host
@@ -372,6 +383,16 @@ Generated by `toMermaid`; a test keeps these copies current.
372
383
  | `promoted` | release-promote | step | Merged: marker done, `q:promote` off. |
373
384
  | `abandoned` | release-promote | step | Closed unmerged: marker done, `q:promote` off. A `q:promote` PR closed or merged before it was approved goes here (or to `promoted`) too. |
374
385
 
386
+ ### Awaiting promotion
387
+
388
+ With `"engine": "graph"`, for every repo whose `release.from` ≠ `release.to` (whether `release.enabled` or not), the end of Watch (`src/promotion.mjs`) tracks merged work that is not yet promoted:
389
+
390
+ - **On merge.** A merged agent PR among the PRs on `from` not yet in `to` (the comparison's `merged`) puts `q:promote` on each closed, cambium-owned issue it closes; close-out still closes the issue.
391
+ - **On promotion.** A closed `q:promote` issue whose PR (the marker's `pr`, else a merged PR closing it) is no longer ahead of `to` loses `q:promote`. Skipped while `to` is missing or `from` is more than 100 commits ahead, since the comparison lists only the last 100.
392
+ - **Read.** For such a repo the snapshot always asks for the comparison and for the closed issues labelled `q:promote`; the release graphs still run only when `enabled`.
393
+
394
+ canopy's Promote lane lists these issues. A repo with `from` = `to` (e.g. releasing from `main` itself) has nothing to await, and the legacy engine does not track it.
395
+
375
396
  - **No timeouts.** Neither graph has one; the daily `cleanup` is the only 24 h rule.
376
397
  - **Read.** With a repo's release on, the snapshot query also asks (in the same query) for the open PRs from `from` to `to`, the PRs labelled `q:promote`, and `to`'s comparison with `from` (`aheadBy`, and the merged PRs on the last 100 commits ahead).
377
398
  - **Legacy.** `engine: "legacy"` keeps the stub.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.15",
3
+ "version": "0.0.17",
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/github.mjs CHANGED
@@ -71,6 +71,7 @@ export const SNAPSHOT_QUERY = `query($owner: String!, $name: String!, $labels: [
71
71
  merged: pullRequests(states: MERGED, first: 30, orderBy: { field: UPDATED_AT, direction: DESC }) { nodes { ${PR_FIELDS} } }
72
72
  promoteRef: pullRequests(headRefName: $from, baseRefName: $to, states: OPEN, first: 10) @include(if: $release) { nodes { ...P } }
73
73
  promoteLabelled: pullRequests(labels: ["${Q.promote}"], first: 10, orderBy: { field: UPDATED_AT, direction: DESC }) @include(if: $release) { nodes { ...P } }
74
+ awaiting: issues(labels: ["${Q.promote}"], states: CLOSED, first: 100, orderBy: { field: UPDATED_AT, direction: DESC }) @include(if: $release) { nodes { ...I } }
74
75
  toRef: ref(qualifiedName: $to) @include(if: $release) {
75
76
  compare(headRef: $from) {
76
77
  aheadBy
@@ -183,7 +184,7 @@ export function normalize(data, { botLogin = null, release = null } = {}) {
183
184
  }
184
185
  return n.number
185
186
  }
186
- for (const n of repo.issues?.nodes ?? []) addIssue(n)
187
+ for (const n of [...(repo.issues?.nodes ?? []), ...(repo.awaiting?.nodes ?? [])]) addIssue(n)
187
188
  /** @type {PullRequest[]} */
188
189
  const prs = []
189
190
  for (const p of [...(repo.open?.nodes ?? []), ...(repo.merged?.nodes ?? [])]) {
@@ -255,7 +256,9 @@ export function graftGitHub({ config, exec: run = exec }) {
255
256
  async read(slug) {
256
257
  const [owner, name] = slug.split('/')
257
258
  const r = config.repos.find((x) => x.slug === slug)?.release
258
- const release = r?.enabled && r.from !== r.to ? { from: r.from, to: r.to } : null
259
+ // Read whenever there is a promotion (`from` ≠ `to`), on or off: the `q:promote` issues need the comparison
260
+ // (promotion.mjs); the release graphs check `enabled` themselves.
261
+ const release = r && r.from !== r.to ? { from: r.from, to: r.to } : null
259
262
  const branches = release ?? { from: '', to: '' }
260
263
  const vars = JSON.stringify({ owner, name, labels: QUEUE_LABELS, release: Boolean(release), ...branches })
261
264
  const data = await json(graft(slug, ['graphql', SNAPSHOT_QUERY, '--vars', vars]))
@@ -24,6 +24,7 @@ import { each, newCtx, staleLeases, taskCandidates, watched, watchPairs } from '
24
24
  import { move, Q } from './labels.mjs'
25
25
  import { markerTrace, turnTracer } from './tracing.mjs'
26
26
  import { DISPATCH_STEPS } from './dispatch-engine.mjs'
27
+ import { trackPromotion } from './promotion.mjs'
27
28
 
28
29
  /**
29
30
  * @typedef {import('./tick.mjs').Deps} Deps
@@ -233,7 +234,7 @@ const inOrder =
233
234
  /** @type {import('./tick.mjs').Engine} */
234
235
  export const GRAPH_ENGINE = {
235
236
  reconcile: inOrder(reconcile, DISPATCH_STEPS.reconcile),
236
- watch,
237
+ watch: inOrder(watch, trackPromotion),
237
238
  sweep: inOrder(sweep, DISPATCH_STEPS.sweep),
238
239
  scheduleTasks,
239
240
  scheduleDispatch: DISPATCH_STEPS.schedule,
@@ -0,0 +1,80 @@
1
+ // @ts-check
2
+ /**
3
+ * Merged, not yet promoted (`engine: "graph"`): for a repo whose `release.from` ≠ `release.to`, an issue whose
4
+ * agent PR merged into `from` carries `q:promote` (the issue stays closed) until that PR is no longer ahead of
5
+ * `to`. Runs at the end of Watch, after close-out, whether or not the repo's daily release is on.
6
+ *
7
+ * - **Label.** A merged agent PR among `release.merged` (the PRs on `from` not yet in `to`) → each closed,
8
+ * cambium-owned issue it closes gains `q:promote` (and leaves every other queue).
9
+ * - **Unlabel.** A closed issue with `q:promote` whose PR (the marker's `pr`, else a merged PR closing it) is no
10
+ * longer among `release.merged` → `q:promote` off. Skipped while `to` is missing or `from` is more than 100
11
+ * commits ahead (the comparison lists only the last 100, so an older PR would look promoted).
12
+ */
13
+ import { key, setLabels } from './issue-state.mjs'
14
+ import { move, Q } from './labels.mjs'
15
+ import { each } from './tick.mjs'
16
+
17
+ /** How many commits ahead the snapshot's comparison lists (github.mjs `commits(last: 100)`). */
18
+ export const COMPARE_WINDOW = 100
19
+
20
+ /**
21
+ * The issue → PR pairs to label and the issues to unlabel, for one repo's snapshot. Pure.
22
+ * @param {import('./github.mjs').Snapshot} snap
23
+ * @returns {{ label: import('./github.mjs').Issue[], unlabel: import('./github.mjs').Issue[] }}
24
+ */
25
+ export function promotionMoves(snap) {
26
+ const release = snap.release
27
+ /** @type {{ label: import('./github.mjs').Issue[], unlabel: import('./github.mjs').Issue[] }} */
28
+ const out = { label: [], unlabel: [] }
29
+ if (!release || release.aheadBy === null) return out
30
+ const ahead = new Set(release.merged.map((p) => p.number))
31
+ /** @type {Map<number, number>} issue → the merged agent PR that closes it */
32
+ const mergedFor = new Map()
33
+ for (const pr of snap.prs) if (pr.state === 'MERGED') for (const n of pr.closes) mergedFor.set(n, pr.number)
34
+ const seen = new Set()
35
+ for (const [n, pr] of mergedFor) {
36
+ const issue = snap.issues.get(n)
37
+ if (!issue?.stateComment || issue.state !== 'CLOSED' || issue.labels.includes(Q.promote)) continue
38
+ if (ahead.has(pr) && !seen.has(n)) {
39
+ seen.add(n)
40
+ out.label.push(issue)
41
+ }
42
+ }
43
+ if (release.aheadBy > COMPARE_WINDOW) return out
44
+ for (const issue of snap.issues.values()) {
45
+ if (issue.state !== 'CLOSED' || !issue.labels.includes(Q.promote)) continue
46
+ const pr = issue.stateComment?.marker.pr ?? mergedFor.get(issue.number) ?? null
47
+ if (pr !== null && !ahead.has(pr)) out.unlabel.push(issue)
48
+ }
49
+ return out
50
+ }
51
+
52
+ /** @param {import('./tick.mjs').Deps} deps @param {import('./tick.mjs').Ctx} ctx */
53
+ export async function trackPromotion(deps, ctx) {
54
+ for (const [slug, snap] of ctx.snaps) {
55
+ const { label, unlabel } = promotionMoves(snap)
56
+ const to = snap.release?.to
57
+ await each(
58
+ deps,
59
+ label,
60
+ async (issue) => {
61
+ await setLabels(deps, slug, issue, move(issue.labels, Q.promote))
62
+ ctx.touched.add(key(slug, issue.number))
63
+ deps.log('info', `merged into \`${snap.release?.from}\`; waiting for promotion to \`${to}\``, {
64
+ repo: slug,
65
+ issue: issue.number,
66
+ })
67
+ },
68
+ (issue) => ({ repo: slug, issue: issue.number }),
69
+ )
70
+ await each(
71
+ deps,
72
+ unlabel,
73
+ async (issue) => {
74
+ await setLabels(deps, slug, issue, { add: [], remove: [Q.promote] })
75
+ deps.log('info', `promoted to \`${to}\``, { repo: slug, issue: issue.number })
76
+ },
77
+ (issue) => ({ repo: slug, issue: issue.number }),
78
+ )
79
+ }
80
+ }
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
@@ -609,7 +610,11 @@ async function release(deps, ctx) {
609
610
  function countsOf(snap) {
610
611
  const c = { intake: 0, task: 0, human: 0, promote: 0, running: 0, review: 0 }
611
612
  for (const issue of snap.issues.values()) {
612
- if (issue.state !== 'OPEN') continue
613
+ if (issue.state !== 'OPEN') {
614
+ // Closed and merged, waiting for promotion (promotion.mjs).
615
+ if (issue.labels.includes(Q.promote)) c.promote++
616
+ continue
617
+ }
613
618
  const q = queueOf(issue.labels)
614
619
  if (q === Q.intake) c.intake++
615
620
  else if (q === Q.task) c.task++
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
+ }