rvlib-shipkit 0.38.1 → 1.0.0

package/src/scaffold/jsonc-spans.ts

@@ -0,0 +1,113 @@
+// a JSONC parser that remembers WHERE every value sits, so a fixer can edit
+// one value of a hand-written file (vscode's tasks.json carries comments and
+// trailing commas) and leave every other byte exactly as its author wrote it.
+
+export type Node =
+    | { kind: 'object'; start: number; end: number; props: { key: string; keyStart: number; value: Node }[] }
+    | { kind: 'array'; start: number; end: number; items: Node[] }
+    | { kind: 'scalar'; start: number; end: number; value: unknown }
+
+/** the tree of `text`, or throws on a malformed document. `end` is exclusive */
+export function parseSpans(text: string): Node {
+    let i = 0
+    const skip = (): void => {
+        for (;;) {
+            while (i < text.length && /\s/.test(text[i]!)) i++
+            if (text.startsWith('//', i)) { while (i < text.length && text[i] !== '\n') i++; continue }
+            if (text.startsWith('/*', i)) { const e = text.indexOf('*/', i + 2); i = e < 0 ? text.length : e + 2; continue }
+            return
+        }
+    }
+    const fail = (what: string): never => { throw new Error(`jsonc: ${what} at offset ${i}`) }
+    const str = (): string => {
+        const start = i
+        i++
+        while (i < text.length && text[i] !== '"') i += text[i] === '\\' ? 2 : 1
+        if (i >= text.length) fail('unterminated string')
+        i++
+        return JSON.parse(text.slice(start, i)) as string
+    }
+    const value = (): Node => {
+        skip()
+        const start = i
+        const c = text[i]
+        if (c === '{') {
+            i++
+            const props: { key: string; keyStart: number; value: Node }[] = []
+            for (;;) {
+                skip()
+                if (text[i] === '}') { i++; return { kind: 'object', start, end: i, props } }
+                if (text[i] !== '"') fail('expected a key')
+                const keyStart = i
+                const key = str()
+                skip()
+                if (text[i] !== ':') fail('expected a colon')
+                i++
+                props.push({ key, keyStart, value: value() })
+                skip()
+                if (text[i] === ',') i++
+            }
+        }
+        if (c === '[') {
+            i++
+            const items: Node[] = []
+            for (;;) {
+                skip()
+                if (text[i] === ']') { i++; return { kind: 'array', start, end: i, items } }
+                items.push(value())
+                skip()
+                if (text[i] === ',') i++
+            }
+        }
+        if (c === '"') {
+            const v = str()
+            return { kind: 'scalar', start, end: i, value: v }
+        }
+        const m = /^(?:true|false|null|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(text.slice(i))
+        if (m == null) return fail('unexpected character')
+        i += m[0].length
+        return { kind: 'scalar', start, end: i, value: JSON.parse(m[0]) }
+    }
+    const root = value()
+    skip()
+    if (i < text.length) fail('trailing content')
+    return root
+}
+
+/** the plain value of a node, comments and positions dropped */
+export function plain(text: string, n: Node): unknown {
+    if (n.kind === 'scalar') return n.value
+    if (n.kind === 'array') return n.items.map((x) => plain(text, x))
+    return Object.fromEntries(n.props.map((p) => [p.key, plain(text, p.value)]))
+}
+
+/** the whitespace a line starts with, for the line holding offset `at` */
+export function indentAt(text: string, at: number): string {
+    const lineStart = text.lastIndexOf('\n', at - 1) + 1
+    return /^[ \t]*/.exec(text.slice(lineStart))![0]
+}
+
+/** the text span that removes item `idx` of an array cleanly: its own line
+ *  when it sits alone on it, and the comma that joined it to a neighbour */
+export function removalSpan(text: string, arr: Extract<Node, { kind: 'array' }>, idx: number): [number, number] {
+    const item = arr.items[idx]!
+    const next = arr.items[idx + 1]
+    if (next != null) {
+        let j = item.end
+        while (j < text.length && /[ \t]/.test(text[j]!)) j++
+        if (text[j] === ',') j++
+        const lineStart = text.lastIndexOf('\n', item.start - 1) + 1
+        const eol = text.indexOf('\n', j)
+        // whole lines when the item owns them, so a comment above the next
+        // item stays with it
+        if (text.slice(lineStart, item.start).trim() === '' && eol >= 0 && text.slice(j, eol).trim() === '') return [lineStart, eol + 1]
+        while (j < text.length && /[ \t]/.test(text[j]!)) j++
+        return [item.start, j]
+    }
+    const prev = arr.items[idx - 1]
+    if (prev != null) {
+        // the last one: drop the comma after the previous item, keep what closes the array
+        return [prev.end, item.end]
+    }
+    return [item.start, item.end]
+}

package/src/scaffold/project-scaffold.ts

@@ -13,6 +13,7 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
 import { defaultHubPort } from '../serve/hub-port.ts'
+import { hubProblemMatcher } from '../problems/problem-line.ts'
 
 const FILES = join(import.meta.dir, 'files')
 
@@ -122,23 +123,21 @@ export type ErgonomicsOpts = {
  *  is the opposite: with no `folderOpen` task nothing starts at all, so there
  *  is no existing answer to overrule.
  *
- *  What lands INSIDE it is DERIVED, never assumed. `build/vscode-tasks.md` owns
- *  this artifact and its method is per-project analysis, so the only subtasks
- *  written here are the ones true of every wired repo (the hub, whose script
- *  `init` writes) plus a TSC watcher when this repo actually has a project for
- *  one. A canned watcher pointed at a solution tsconfig (`files: []` plus
- *  `references`) type checks ZERO files and reports a clean problems pane
- *  forever, which is worse than no task. Every other watcher a stack earns
- *  (a dev server, css, tests) stays the analysis step the owner page describes,
+ *  What lands INSIDE it is only what is true of every wired repo: the hub,
+ *  whose script `init` writes, carrying the problem matcher that turns every
+ *  check's findings into the problems pane. There is no type checker task, the
+ *  hub runs `typecheck` like any other check. Every watcher a stack earns (a
+ *  dev server, css) stays the analysis step `build/vscode-tasks.md` describes,
  *  and the caller says so out loud.
  *
  *  Create-only: an adopted repo often carries a `.vscode/` from whatever it was
- *  forked from, and that one wins byte for byte. Returns the paths it wrote. */
+ *  forked from, and that one wins byte for byte (rule SK017 then repairs its
+ *  hub task in place). Returns the paths it wrote. */
 export function editorErgonomics(root: string, opts: ErgonomicsOpts): string[] {
     // a symlinked .vscode is a dotfiles pattern pointing at a SHARED dir, and
     // writing through it lands files outside the repo being wired
     if (isLink(join(root, '.vscode'))) return []
-    const body = tasksTemplate({ NAME: opts.name, PORT: String(opts.port) }, typecheckableProject(root))
+    const body = tasksTemplate({ NAME: opts.name, PORT: String(opts.port) })
     return put(root, '.vscode/tasks.json', body) ? ['.vscode/tasks.json'] : []
 }
 
@@ -150,35 +149,11 @@ const isLink = (path: string): boolean => {
     }
 }
 
-/** the tasks template with the TSC subtask REMOVED when this repo has no
- *  project it would check. One template, one subtraction: forking the file
- *  would put two copies of the house task shape in the tree. */
-export function tasksTemplate(vars: Record<string, string>, withTsc: boolean): string {
-    const body = template('vscode-tasks.json', vars)
-    if (withTsc) return body
-    const parsed = JSON.parse(body.replace(/^\s*\/\/.*$/gm, '')) as { version: string; tasks: Array<Record<string, unknown>> }
-    parsed.tasks = parsed.tasks.filter((t) => t['label'] !== TSC_LABEL)
-    for (const t of parsed.tasks) {
-        const deps = t['dependsOn']
-        if (Array.isArray(deps)) t['dependsOn'] = deps.filter((d) => d !== TSC_LABEL)
-    }
-    return JSON.stringify(parsed, null, 3) + '\n'
-}
-
-const TSC_LABEL = '👁  TSC'
-
-/** whether `tsc --project tsconfig.json` here would check anything at all. A
- *  solution config (`files: []` plus `references`) needs `--build`, which the
- *  house watcher does not pass, and answers zero files without it. */
-export function typecheckableProject(root: string): boolean {
-    try {
-        const raw = readFileSync(join(root, 'tsconfig.json'), 'utf8')
-        const cfg = JSON.parse(raw.replace(/^\s*\/\/.*$/gm, '')) as { files?: unknown[]; include?: unknown[]; references?: unknown[] }
-        if ((cfg.references ?? []).length === 0) return true
-        return (cfg.files ?? []).length > 0 || (cfg.include ?? []).length > 0
-    } catch {
-        return false
-    }
+/** the tasks template, the hub's problem matcher rendered in from the one
+ *  module the hub prints through, so the two can never disagree */
+export function tasksTemplate(vars: Record<string, string>): string {
+    return template('vscode-tasks.json', vars).replace(/^(\s*)(.*)\{\{HUB_PROBLEM_MATCHER\}\}/m, (_all, indent: string, head: string) =>
+        `${indent}${head}${JSON.stringify(hubProblemMatcher(), null, 3).split('\n').join(`\n${indent}`)}`)
 }
 
 export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
@@ -200,8 +175,6 @@ export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
 
     write('src/index.ts', 'export {}\n')
     write('tsconfig.json', template('tsconfig.json', vars))
-    // tasks AFTER the tsconfig, so the TSC subtask is derived from the project
-    // this run just wrote rather than from the empty dir it found
     ;(editorErgonomics(root, { name: opts.name, port }).length > 0 ? written : skipped).push('.vscode/tasks.json')
     // settings.json only here: it turns eslint off and hands formatting to an
     // oxc extension, which is a decision only the repo's creator gets to make
@@ -223,7 +196,7 @@ export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
     write('agent/changelog.md', template('agent-changelog.md', vars))
     // gitignored by policy, so it never ships: it exists so an agent hitting
     // friction with the toolchain finds the place to write it down
-    write('.rv-reflections/README.md', REFLECTIONS_README)
+    write('.shipkit/reflections/README.md', REFLECTIONS_README)
 
     addScripts(root, written, p)
     addIgnoreLines(root, written)
@@ -247,7 +220,7 @@ function grantSummary(): string {
     }
 }
 
-const REFLECTIONS_README = `# .rv-reflections
+const REFLECTIONS_README = `# .shipkit/reflections
 
 One file per friction with the shared toolchain: \`YYYYMMDD-<slug>.md\`.
 What broke, which page or lib, what you expected. Gitignored on purpose,

package/src/scan.ts

@@ -0,0 +1,98 @@
+// A SHARED SCAN: work several checks need (every wiki page parsed, the root
+// package.json), done once per runner pass and handed to each check that asks
+// through `c.use(scan)`. The scan reads through its own context, and every
+// read it makes is recorded into EVERY check that used it, so a cached answer
+// built on a scan busts when anything the scan read moves.
+//
+// The NAME is the scan's identity inside a pass: two scans with one name share
+// one value. A factory that takes an argument (mdPages below) puts the argument
+// in the name and hands back one scan object per argument.
+import type { ScanCtx } from './core/check-ctx.ts'
+
+export type Scan<T> = {
+    /** unique per pass: the memo key */
+    readonly name: string
+    readonly run: (c: ScanCtx) => T | Promise<T>
+}
+
+/** THE way to declare a scan. It reads through `c` (read, json, exists,
+ *  list, use) and reports nothing: a finding belongs to the check that asked. */
+export function defineScan<T>(name: string, run: (c: ScanCtx) => T | Promise<T>): Scan<T> {
+    if (name.trim() === '') throw new Error('defineScan: a scan needs a name, it is the memo key of the pass')
+    return { name, run }
+}
+
+// ── built-in scans ───────────────────────────────────────────────────────
+
+/** one markdown page, parsed */
+export type MdPage = {
+    /** repo-relative */
+    path: string
+    /** the leading `---` block as flat `key: value` pairs. Nested yaml is out
+     *  of scope: a value keeps the text after the first colon, trimmed */
+    frontmatter: Record<string, string>
+    /** the text after the frontmatter */
+    body: string
+    /** every markdown link target in the body, as written, anchors dropped.
+     *  External (scheme or `//`), mailto and same-page anchors are left out */
+    links: string[]
+}
+
+const FRONT = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/
+const LINK = /\[[^\]]*\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g
+
+export function parseMdPage(path: string, text: string): MdPage {
+    const m = FRONT.exec(text)
+    const frontmatter: Record<string, string> = {}
+    if (m != null)
+        for (const line of m[1]!.split(/\r?\n/)) {
+            const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+            if (kv != null) frontmatter[kv[1]!] = kv[2]!.trim()
+        }
+    const body = m == null ? text : text.slice(m[0].length)
+    const links: string[] = []
+    for (const l of body.matchAll(LINK)) {
+        const target = l[1]!.split('#')[0]!
+        if (target === '' || /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('//')) continue
+        links.push(target)
+    }
+    return { path, frontmatter, body, links }
+}
+
+const pagesByDir = new Map<string, Scan<MdPage[]>>()
+
+/** every `*.md` git sees under `dir` (repo-relative, `.` for the whole repo),
+ *  parsed, sorted by path */
+export function mdPages(dir: string): Scan<MdPage[]> {
+    const d = dir.replace(/\/+$/, '').replace(/^\.\//, '')
+    let s = pagesByDir.get(d)
+    if (s == null) {
+        const glob = d === '' || d === '.' ? '**/*.md' : `${d}/**/*.md`
+        s = defineScan(`mdPages:${d === '' ? '.' : d}`, (c) => c.list(glob).map((p) => parseMdPage(p, c.read(p) ?? '')))
+        pagesByDir.set(d, s)
+    }
+    return s
+}
+
+/** the fields of a package.json the built-in checks read */
+export type PackageJson = {
+    name?: string
+    version?: string
+    private?: boolean
+    license?: string
+    scripts?: Record<string, string>
+    dependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+    peerDependencies?: Record<string, string>
+    optionalDependencies?: Record<string, string>
+    publishConfig?: unknown
+    [k: string]: unknown
+}
+
+const rootPackageJson = defineScan<PackageJson | null>('packageJson', (c) => c.json<PackageJson>('package.json'))
+
+/** the repo root package.json, parsed. null when there is none, and an
+ *  unparseable one throws naming the file */
+export function packageJson(): Scan<PackageJson | null> {
+    return rootPackageJson
+}

package/src/serve/gate-trigger.ts

@@ -0,0 +1,148 @@
+// when the hub runs the quick gate on its own: once at start, then after the
+// tracked files have been quiet for QUIET_MS. The trigger only STARTS ordinary
+// gate runs. Every answer comes out of the one runner, measured or replayed
+// from the ledger like any other run, so nothing here owns a verdict: a missed
+// file event costs a stale problems pane until the next save, never a green.
+//
+// never two runs at once: a request during a run queues exactly one more, run
+// after it ends, however many saves landed meanwhile.
+import { watch, type FSWatcher } from 'fs'
+import { GENERATED_IGNORE_LINES } from '../rules/untrack-generated.ts'
+import { gitBin } from '../core/git-bin.ts'
+import { LAYOUT } from '../core/layout.ts'
+
+export const QUIET_MS = 2000
+
+export type Timers = {
+    set: (fn: () => void, ms: number) => unknown
+    clear: (handle: unknown) => void
+}
+
+const realTimers: Timers = {
+    set: (fn, ms) => setTimeout(fn, ms),
+    clear: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
+}
+
+export class GateTrigger {
+    private timer: unknown = null
+    private running: Promise<void> | null = null
+    private pending = false
+    private readonly timers: Timers
+    private readonly quietMs: number
+
+    constructor(private readonly o: { run: () => Promise<unknown>; quietMs?: number; timers?: Timers; onError?: (e: Error) => void }) {
+        this.timers = o.timers ?? realTimers
+        this.quietMs = o.quietMs ?? QUIET_MS
+    }
+
+    /** a tracked file moved: the run starts once nothing has moved for the
+     *  quiet window, so a save burst is one run */
+    touched(): void {
+        if (this.timer != null) this.timers.clear(this.timer)
+        this.timer = this.timers.set(() => {
+            this.timer = null
+            this.request()
+        }, this.quietMs)
+    }
+
+    /** run now, or once more after the run in flight */
+    request(): void {
+        if (this.running != null) { this.pending = true; return }
+        this.running = (async () => {
+            do {
+                this.pending = false
+                try { await this.o.run() } catch (e) { this.o.onError?.(e instanceof Error ? e : new Error(String(e))) }
+            } while (this.pending)
+        })().finally(() => { this.running = null })
+    }
+
+    /** resolves when no run is in flight or queued */
+    async idle(): Promise<void> {
+        while (this.running != null) await this.running
+    }
+
+    stop(): void {
+        if (this.timer != null) this.timers.clear(this.timer)
+        this.timer = null
+    }
+}
+
+/** every path a run of the gate or the hub itself writes, whatever the repo
+ *  ignores: the status files, the per run logs under the scratch dir, an atomic write's
+ *  temp file, the comfy state the hub writes at boot. A save there is the
+ *  machine's own, and triggering on it would schedule the next run forever */
+export const GATE_WRITES: readonly string[] = [
+    ...GENERATED_IGNORE_LINES.filter((l) => !l.startsWith('#')),
+    `${LAYOUT.tmp}/`,
+    '.*.tmp-*',
+    '.comfy-ts/',
+]
+
+const globRe = (glob: string): RegExp => new RegExp(`^${glob.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')}$`)
+const WRITE_RULES = GATE_WRITES.map((g) => (g.endsWith('/') ? { dir: g, re: null } : { dir: null, re: globRe(g) }))
+
+/** true for a path the gate writes (GATE_WRITES), matched on its basename for
+ *  a file pattern and on its prefix for a directory. A folder the gate creates
+ *  on the way (`.shipkit` for `.shipkit/tmp/`) is one of its writes too: an
+ *  owner file inside it fires its own event */
+export function isGateWrite(rel: string): boolean {
+    const base = rel.split('/').at(-1) ?? rel
+    return WRITE_RULES.some((r) => (r.dir != null ? r.dir.startsWith(`${rel}/`) || rel.startsWith(r.dir) : r.re!.test(base)))
+}
+
+/** which of these repo-relative paths git ignores. A tracked file is never
+ *  reported, whatever the ignore rules say */
+export async function gitIgnored(root: string, paths: string[]): Promise<Set<string>> {
+    if (paths.length === 0) return new Set()
+    try {
+        const p = Bun.spawn([gitBin(), 'check-ignore', '--stdin', '-z'], { cwd: root, stdin: 'pipe', stdout: 'pipe', stderr: 'ignore' })
+        p.stdin.write(paths.join('\0') + '\0')
+        await p.stdin.end()
+        const out = await new Response(p.stdout).text()
+        await p.exited
+        return new Set(out.split('\0').filter((s) => s !== ''))
+    } catch {
+        return new Set()
+    }
+}
+
+/** calls onChange whenever a file the owner edits moves under root: tracked,
+ *  or untracked and not ignored. What the gate itself writes (GATE_WRITES,
+ *  the ledger in .git) never counts, ignored or not, so a run never triggers
+ *  the next one */
+export function watchTracked(root: string, onChange: () => void, o: { ignored?: (paths: string[]) => Promise<Set<string>>; onError?: (e: Error) => void } = {}): { close: () => void; error: string | null } {
+    const ignored = o.ignored ?? ((paths: string[]) => gitIgnored(root, paths))
+    const pending = new Set<string>()
+    let flushing = false
+    const flush = async (): Promise<void> => {
+        if (flushing) return
+        flushing = true
+        try {
+            while (pending.size > 0) {
+                const batch = [...pending]
+                pending.clear()
+                const skip = await ignored(batch)
+                if (batch.some((p) => !skip.has(p))) onChange()
+            }
+        } finally {
+            flushing = false
+        }
+    }
+    let w: FSWatcher | null = null
+    let error: string | null = null
+    try {
+        w = watch(root, { recursive: true }, (_event, name) => {
+            if (name == null) return onChange()
+            const rel = String(name).replace(/\\/g, '/')
+            if (rel === '.git' || rel.startsWith('.git/') || rel.split('/').includes('node_modules') || isGateWrite(rel)) return
+            pending.add(rel)
+            void flush()
+        })
+        // a watcher that dies mid session (the tree was removed, a limit hit)
+        // says so, rather than crashing the hub or going quiet
+        w.on('error', (e) => o.onError?.(e instanceof Error ? e : new Error(String(e))))
+    } catch (e) {
+        error = e instanceof Error ? e.message : String(e)
+    }
+    return { close: () => w?.close(), error }
+}

package/src/serve/health-schedule.ts

@@ -0,0 +1,102 @@
+// THE HEALTH PASS TIMER. While the hub serves, the whole health pass runs once
+// a day, and once at startup when the last whole pass on record is older than
+// that. One timer for the repo, no per check schedule: a check's own `ttl` is
+// its cadence, and this pass is only the heartbeat that replays an answer
+// still fresh and re-measures one that expired.
+//
+// The run is the hub's own in process runner, the same path as the button, so
+// its rows land in the same run record. "When was the last pass" is read off
+// that record, which is what makes a `shipkit check` in a terminal count too.
+
+/** how often the health pass runs while the hub serves */
+export const HEALTH_EVERY_MS = 24 * 60 * 60 * 1000
+
+/** how often the timer looks. The pass itself is daily, this only bounds how
+ *  late after its due time it starts */
+export const SCHEDULE_LOOK_MS = 5 * 60 * 1000
+
+export type ScheduleState = {
+    everyMs: number
+    /** when the last whole health pass on record started, null = none */
+    lastPassAt: number | null
+    /** when the next one starts: now when it is overdue */
+    nextAt: number
+    /** the timer's own pass is running right now */
+    running: boolean
+}
+
+export type ScheduleDeps = {
+    now: () => number
+    /** the last whole health pass on record, whoever ran it */
+    lastPassAt: () => number | null
+    /** another run in this process is going: the timer never stacks on it */
+    busy: () => boolean
+    /** the pass itself */
+    run: () => Promise<void>
+    everyMs?: number
+}
+
+export type TickResult = 'ran' | 'fresh' | 'busy'
+
+export class HealthSchedule {
+    readonly everyMs: number
+    running = false
+    /** when this timer last STARTED a pass. A pass that dies before it writes
+     *  a record would otherwise be due again at the very next look */
+    private attemptedAt: number | null = null
+    private timer: ReturnType<typeof setInterval> | null = null
+
+    constructor(private readonly d: ScheduleDeps) {
+        this.everyMs = d.everyMs ?? HEALTH_EVERY_MS
+    }
+
+    /** the newest of the record and this timer's own last attempt */
+    private lastAt(): number | null {
+        const rec = this.d.lastPassAt()
+        if (rec == null) return this.attemptedAt
+        return this.attemptedAt == null ? rec : Math.max(rec, this.attemptedAt)
+    }
+
+    due(): boolean {
+        const last = this.lastAt()
+        return last == null || this.d.now() - last >= this.everyMs
+    }
+
+    state(): ScheduleState {
+        const now = this.d.now()
+        const last = this.lastAt()
+        return {
+            everyMs: this.everyMs,
+            lastPassAt: this.d.lastPassAt(),
+            nextAt: last == null ? now : Math.max(now, last + this.everyMs),
+            running: this.running,
+        }
+    }
+
+    /** one look: run the pass when it is due and nothing else is running */
+    async tick(): Promise<TickResult> {
+        if (this.running || this.d.busy()) return 'busy'
+        if (!this.due()) return 'fresh'
+        this.running = true
+        this.attemptedAt = this.d.now()
+        try {
+            await this.d.run()
+        } finally {
+            this.running = false
+        }
+        return 'ran'
+    }
+
+    /** look now, then every SCHEDULE_LOOK_MS. A second start is a no-op */
+    start(onError: (e: Error) => void, lookMs = SCHEDULE_LOOK_MS): void {
+        if (this.timer != null) return
+        const look = (): void => void this.tick().catch((e: Error) => onError(e))
+        look()
+        this.timer = setInterval(look, lookMs)
+    }
+
+    stop(): void {
+        if (this.timer != null) clearInterval(this.timer)
+        this.timer = null
+    }
+}