@voidlabs.gg/voidshift-agents 0.4.2 → 0.4.4

package/dist/runner.js

@@ -2,11 +2,13 @@ import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { LABELS, PLAN_HEADING, buildPrompt, findingsFor, fixTarget, isStatusLabel, latestPlan, parseDevResult, parseVerdict, planBody, qaPassed, stageLabels, verdictBlock, } from "./workflow.js";
-import { STEPS, agentsDir, hasWork, isProducer } from "./config.js";
+import { STEPS, agentsDir, hasWork, isCardTrigger, isProducer } from "./config.js";
+import { lastDue, parseCron } from "./cron.js";
 import { runAgent, stopAgents } from "./engine.js";
 import { commitsAhead, defaultBranch, ensureDraftPr, ensureWorktree, headSha, markReady, push, resetWorktree, waitForChecks, waitForPrHead } from "./git.js";
+import { noTracker } from "./tracker.js";
 import { recall, vaultPath } from "./memory.js";
-import { bootTime, clearCurrent, isPaused, ours, readCurrent, readPending, writeCurrent, writePending, writeRun } from "./state.js";
+import { bootTime, clearCurrent, isPaused, ours, readCurrent, readPending, writeCurrent, writePending, writeRun, readCronState, writeCronState } from "./state.js";
 const packDir = fileURLToPath(new URL('../pack/', import.meta.url));
 const skill = (name) => readFileSync(join(packDir, name, 'SKILL.md'), 'utf8');
 const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
@@ -18,7 +20,7 @@ function withLabels(card, drop, add) {
 const UNATTENDED = `# Running unattended
 
 You are one step in a workflow. Nobody can answer questions and the
-Linear connection is not available: the card and any plan are included above.
+tracker connection is not available: the card and any plan are included above.
 Do not write plan files; return your output as your final message. Make the
 call the code supports and state it.`;
 // Agents keep the memory vault the way you do: durable learnings become notes.
@@ -41,20 +43,23 @@ const isVerdict = (s) => STEPS[s].output === 'verdict';
 // step that produces something, Plan or Dev, and the workflow continues from
 // there, until everything passes or the loop cap parks the card.
 export async function runCard(card, trigger, workflowName, workflow, project, rc, opts = {}) {
-    const { linear, config, log } = rc;
+    const { config, log } = rc;
+    // A scheduled run has no card, so it has nothing to write back to.
+    const linear = isCardTrigger(trigger) ? rc.trackers(trigger.source) : noTracker;
+    const label = isCardTrigger(trigger) ? trigger.label : '';
     const runDir = join(agentsDir(rc.configDir), 'runs', card.identifier, stamp());
     mkdirSync(runDir, { recursive: true });
     const say = (line) => log(`${card.identifier} ${line}`);
     const steps = workflow.steps;
     const startedAt = new Date().toISOString();
-    const record = { card: card.identifier, title: card.title, url: card.url, workflow: workflowName, trigger: trigger.label, steps: [], outcome: 'running', startedAt };
+    const record = { card: card.identifier, title: card.title, url: card.url || undefined, workflow: workflowName, trigger: label || (trigger.source === 'cron' ? trigger.schedule : ''), source: trigger.source, steps: [], outcome: 'running', startedAt };
     active = { record, runDir };
     const save = () => writeRun(runDir, record);
     save();
     let loops = 0;
     // The lock tells status and cancel what is running.
-    const mark = (step) => writeCurrent(rc.configDir, { pid: process.pid, card: card.identifier, title: card.title, workflow: workflowName, step, round: loops, startedAt, runDir });
-    // Written before the first Linear call, so a cancel always knows the card.
+    const mark = (step) => writeCurrent(rc.configDir, { pid: process.pid, card: card.identifier, title: card.title, workflow: workflowName, step, round: loops, startedAt, runDir, source: trigger.source });
+    // Written before the first tracker call, so a cancel always knows the card.
     mark('Starting');
     const begin = (step) => {
         const rec = { step, label: STEPS[step].label, startedAt: new Date().toISOString() };
@@ -84,8 +89,8 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     const setRound = (n) => {
         loops = n;
     };
-    const stage = (name, round) => linear.setLabels(card, stageLabels(card.labels, trigger.label, name, round));
-    // Linear hears from the runner twice: the plan once it has passed review,
+    const stage = (name, round) => linear.setLabels(card, stageLabels(card.labels, label, name, round));
+    // The tracker hears from the runner twice: the plan once it has passed review,
     // and one final comment. Findings stay here until the final one.
     let lastFindings = '';
     let planToPost = null;
@@ -97,19 +102,21 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     };
     async function park(reason) {
         say(`parked: ${reason}`);
-        const comment = `**Parked:** ${reason}${lastFindings ? `\n\n${lastFindings}` : ''}\n\nFix the cause, then add \`${trigger.label}\` again to retry.`;
+        const comment = `**Parked:** ${reason}${lastFindings ? `\n\n${lastFindings}` : ''}\n\nFix the cause, then add \`${label}\` again to retry.`;
         const add = [LABELS.parked, ...(loops ? [LABELS.version(loops)] : [])];
         let commented = false;
         try {
             await postPlan();
             await linear.comment(card, comment);
             commented = true;
-            await linear.setLabels(card, stageLabels(card.labels, trigger.label, LABELS.parked, loops || undefined));
+            await linear.setLabels(card, stageLabels(card.labels, label, LABELS.parked, loops || undefined));
         }
         catch (err) {
-            say(`could not reach Linear to park it (${err.message}). Will retry next minute.`);
+            if (!isCardTrigger(trigger))
+                return done('parked', reason);
+            say(`could not reach ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} to park it (${err.message}). Will retry next minute.`);
             // An empty comment is skipped on retry, so it is not posted twice.
-            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [trigger.label], add, dropStatus: true }]);
+            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: true, source: trigger.source }]);
         }
         return done('parked', reason);
     }
@@ -119,7 +126,8 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         const from = opts.from ? steps.indexOf(opts.from) : 0;
         if (from < 0)
             throw new Park(`Workflow ${workflowName} has no ${STEPS[opts.from].label} step.`);
-        let plan = latestPlan(await linear.comments(card.identifier));
+        // A scheduled run has no card to plan on, so its task is the plan unless a Plan step writes one.
+        let plan = isCardTrigger(trigger) ? latestPlan(await linear.comments(card.identifier)) : card.description ?? null;
         const firstPlan = steps.indexOf('vs-plan', from);
         const needsPlan = steps.findIndex((s, n) => n >= from && (s === 'vs-dev' || s === 'vs-plan-review'));
         if (!plan && needsPlan >= 0 && (firstPlan < 0 || firstPlan > needsPlan)) {
@@ -207,7 +215,7 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 if (target < 0) {
                     await postPlan();
                     await linear.comment(card, `**Changes needed.**\n\n${notes}`);
-                    await linear.setLabels(card, stageLabels(card.labels, trigger.label, LABELS.changes, round));
+                    await linear.setLabels(card, stageLabels(card.labels, label, LABELS.changes, round));
                     say('changes requested');
                     return done('changes');
                 }
@@ -278,7 +286,7 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             markReady(worktree, card.branchName);
             moved = await linear.moveTo(card, config.reviewState);
         }
-        await linear.setLabels(card, stageLabels(card.labels, trigger.label, LABELS.verified, loops || undefined));
+        await linear.setLabels(card, stageLabels(card.labels, label, LABELS.verified, loops || undefined));
         await linear.comment(card, `**All checks passed.**${prUrl ? ` PR ready: ${prUrl}` : ''}${hasWork(workflow) && !moved ? `\n\n(No "${config.reviewState}" state on this team, so the card was not moved.)` : ''}`);
         say('verified');
         return done('verified');
@@ -292,34 +300,107 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         active = null;
     }
 }
-// The first card waiting on any workflow's triggers, in workflow order.
-// With a workflow name, only that workflow is considered.
-export async function nextJob(rc, only, workflowName) {
-    const pinned = only ? await rc.linear.card(only) : null;
-    for (const [name, workflow] of Object.entries(rc.config.workflows)) {
-        if (workflowName && name !== workflowName)
-            continue;
-        for (const trigger of workflow.triggers) {
-            const cards = pinned ? [pinned] : await rc.linear.myCardsWithLabel(trigger.label);
-            // A pinned card may have lost its label (a parked card re-run by hand), so match by team.
-            const card = cards.find((c) => c.teamKey === trigger.team && (pinned || c.labels.includes(trigger.label)));
-            if (card)
-                return { card, trigger, workflow: name };
+// A scheduled run's stand-in for a card: the task, on a branch of its own.
+export function cronCard(workflow, task, at) {
+    const stamp = at.toISOString().slice(0, 16).replace(/[-:T]/g, '');
+    const slug = workflow.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'cron';
+    return {
+        id: '',
+        identifier: `${slug.replace(/-/g, '').toUpperCase()}-${stamp}`,
+        title: task.split('\n')[0].slice(0, 80),
+        description: task,
+        url: '',
+        branchName: `vs/${slug}-${stamp}`,
+        teamId: '',
+        teamKey: '',
+        labels: [],
+    };
+}
+const cronKey = (workflow, schedule) => `${workflow} ${schedule}`;
+// The first job waiting on any workflow's triggers, in workflow order: a card
+// carrying a trigger label, or a schedule that came due since it last fired.
+// A schedule seen for the first time starts counting from now. With a card,
+// only that card is considered; with a workflow name, only that workflow, and
+// `force` fires its schedule now.
+export async function nextJob(rc, only, workflowName, opts = {}) {
+    const now = opts.now ?? new Date();
+    const workflows = Object.entries(rc.config.workflows).filter(([name]) => !workflowName || name === workflowName);
+    let pinned = null;
+    if (only) {
+        const team = only.split('-')[0].toUpperCase();
+        const sources = [...new Set(workflows.flatMap(([, w]) => w.triggers.filter(isCardTrigger).filter((t) => t.team === team).map((t) => t.source)))];
+        for (const source of sources) {
+            try {
+                pinned = { card: await rc.trackers(source).card(only), source };
+                break;
+            }
+            catch (err) {
+                if (source === sources.at(-1))
+                    throw err;
+            }
         }
+        if (!pinned)
+            return null;
+    }
+    const cron = readCronState(rc.configDir);
+    let cronChanged = false;
+    try {
+        for (const [name, workflow] of workflows) {
+            for (const trigger of workflow.triggers) {
+                if (!isCardTrigger(trigger)) {
+                    const schedule = only ? null : parseCron(trigger.schedule);
+                    if (!schedule)
+                        continue;
+                    const key = cronKey(name, trigger.schedule);
+                    const last = cron[key];
+                    const due = opts.force ? now : last ? lastDue(schedule, new Date(last), now) : null;
+                    if (!last || due) {
+                        cron[key] = now.toISOString();
+                        cronChanged = true;
+                    }
+                    if (due)
+                        return { card: cronCard(name, trigger.task, due), trigger, workflow: name };
+                    continue;
+                }
+                // A pinned card may have lost its label (a parked card re-run by hand), so match by team.
+                if (pinned) {
+                    if (pinned.source === trigger.source && pinned.card.teamKey === trigger.team)
+                        return { card: pinned.card, trigger, workflow: name };
+                    continue;
+                }
+                let cards;
+                try {
+                    cards = await rc.trackers(trigger.source).myCardsWithLabel(trigger.label, trigger.team);
+                }
+                catch (err) {
+                    // One tracker being down or unset must not stop the others.
+                    rc.log(`Could not check ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} for ${trigger.team} + ${trigger.label} (${err.message}). Trying again next minute.`);
+                    continue;
+                }
+                const card = cards.find((c) => c.teamKey === trigger.team && c.labels.includes(trigger.label));
+                if (card)
+                    return { card, trigger, workflow: name };
+            }
+        }
+        return null;
+    }
+    finally {
+        if (cronChanged)
+            writeCronState(rc.configDir, cron);
     }
-    return null;
 }
-// Retries Linear writes that failed while parking. Never throws.
+// Retries tracker writes that failed while parking. Never throws.
 async function flushPending(rc) {
     const left = [];
     for (const p of readPending(rc.configDir)) {
         try {
-            const card = await rc.linear.card(p.card);
+            const tracker = rc.trackers(p.source ?? 'linear');
+            const card = await tracker.card(p.card);
             if (p.comment) {
-                await rc.linear.comment(card, p.comment);
+                await tracker.comment(card, p.comment);
                 p.comment = '';
             }
-            await rc.linear.setLabels(card, withLabels(card, (l) => p.drop.includes(l) || (!!p.dropStatus && isStatusLabel(l)), p.add));
+            await tracker.setLabels(card, withLabels(card, (l) => p.drop.includes(l) || (!!p.dropStatus && isStatusLabel(l)), p.add));
         }
         catch {
             left.push(p);
@@ -332,27 +413,27 @@ async function flushPending(rc) {
         // nothing more to do
     }
 }
-// Takes the working label off a cancelled card and says so. When Linear
+// Takes the working label off a cancelled card and says so. When the tracker
 // cannot be reached the same change is queued for the next tick.
-export async function cancelCard(linear, configDir, cardId, label) {
+export async function cancelCard(tracker, configDir, cardId, label, source = 'linear') {
     const comment = `**Cancelled.** Add \`${label}\` again to restart.`;
     try {
-        const card = await linear.card(cardId);
-        await linear.setLabels(card, withLabels(card, isStatusLabel, []));
-        await linear.comment(card, comment);
+        const card = await tracker.card(cardId);
+        await tracker.setLabels(card, withLabels(card, isStatusLabel, []));
+        await tracker.comment(card, comment);
         return true;
     }
     catch {
-        queueCancel(configDir, cardId, comment);
+        queueCancel(configDir, cardId, comment, source);
         return false;
     }
 }
-function queueCancel(configDir, cardId, comment) {
+function queueCancel(configDir, cardId, comment, source = 'linear') {
     const pending = readPending(configDir);
     if (pending.some((p) => p.card === cardId && p.comment === comment))
         return;
     try {
-        writePending(configDir, [...pending, { card: cardId, comment, drop: [], add: [], dropStatus: true }]);
+        writePending(configDir, [...pending, { card: cardId, comment, drop: [], add: [], dropStatus: true, source }]);
     }
     catch {
         // nothing more to do
@@ -385,13 +466,15 @@ export async function tick(rc, only, opts = {}) {
                 // the run folder is gone
             }
         }
-        if (running) {
+        if (running && running.record.source !== 'cron') {
             const { card, trigger } = running.record;
+            const source = running.record.source ?? 'linear';
             const timeout = new Promise((resolve) => setTimeout(() => resolve(false), 5000).unref());
-            const finished = await Promise.race([cancelCard(rc.linear, rc.configDir, card, trigger), timeout]);
+            const work = (async () => cancelCard(rc.trackers(source), rc.configDir, card, trigger, source))().catch(() => false);
+            const finished = await Promise.race([work, timeout]);
             // Did not finish in time: leave the work for the next tick.
             if (!finished)
-                queueCancel(rc.configDir, card, `**Cancelled.** Add \`${trigger}\` again to restart.`);
+                queueCancel(rc.configDir, card, `**Cancelled.** Add \`${trigger}\` again to restart.`, source);
         }
         clearCurrent(rc.configDir);
         process.exit(143);
@@ -404,10 +487,10 @@ export async function tick(rc, only, opts = {}) {
             return 0;
         let job;
         try {
-            job = await nextJob(rc, only, opts.workflow);
+            job = await nextJob(rc, only, opts.workflow, { force: !!opts.workflow && !only });
         }
         catch (err) {
-            rc.log(`Could not check Linear (${err.message}). Trying again next minute.`);
+            rc.log(`Could not read ${only} (${err.message}).`);
             return 1;
         }
         if (!job) {

package/dist/secrets.d.ts

@@ -0,0 +1,9 @@
+export declare const looksLikeLinearKey: (key: string) => boolean;
+export declare const secretsPath: (configDir: string) => string;
+export declare const keyStore: (platform?: NodeJS.Platform) => "your macOS Keychain" | "a file only you can read";
+export declare function readSecretsFile(path: string): Record<string, string>;
+export declare function writeSecretsFile(path: string, values: Record<string, string>): void;
+export declare function readSecret(configDir: string, name: string, platform?: NodeJS.Platform): string | null;
+export declare function storeSecret(configDir: string, name: string, value: string, platform?: NodeJS.Platform): boolean;
+export declare const readLinearKey: (configDir: string) => string | null;
+export declare const storeLinearKey: (configDir: string, key: string) => boolean;

package/dist/secrets.js

@@ -0,0 +1,55 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { dirname, join } from 'node:path';
+import { agentsDir } from "./config.js";
+// Keys live in the macOS Keychain, or on other platforms in a file only this
+// user can read, in the agents config folder.
+const KEY_SHAPE = /^lin_api_[A-Za-z0-9]+$/;
+// Values the Keychain is handed on stdin; anything that could break out of
+// the `security -i` command line is refused.
+const SAFE_VALUE = /^[A-Za-z0-9_\-.:/+=]+$/;
+export const looksLikeLinearKey = (key) => KEY_SHAPE.test(key);
+export const secretsPath = (configDir) => join(agentsDir(configDir), 'secrets.json');
+// Where keys are kept on this machine, for messages.
+export const keyStore = (platform = process.platform) => platform === 'darwin' ? 'your macOS Keychain' : 'a file only you can read';
+// The secrets file, refused when anyone but its owner can read it.
+export function readSecretsFile(path) {
+    if (!existsSync(path))
+        return {};
+    const mode = statSync(path).mode & 0o777;
+    if (mode & 0o077)
+        throw new Error(`${path} can be read by other users (mode ${mode.toString(8)}). Run chmod 600 on it.`);
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+// Written to a temporary file with mode 0600, then renamed into place, so the
+// file is never readable by others, not even for a moment.
+export function writeSecretsFile(path, values) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(values, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+}
+const service = (name) => `voidshift-${name}`;
+export function readSecret(configDir, name, platform = process.platform) {
+    if (platform === 'darwin') {
+        const r = spawnSync('/usr/bin/security', ['find-generic-password', '-s', service(name), '-w'], { encoding: 'utf8' });
+        return (r.status === 0 ? r.stdout.trim() : '') || null;
+    }
+    return readSecretsFile(secretsPath(configDir))[name] || null;
+}
+export function storeSecret(configDir, name, value, platform = process.platform) {
+    if (!SAFE_VALUE.test(value) || !/^[a-z-]+$/.test(name))
+        return false;
+    if (platform === 'darwin') {
+        // On stdin through `security -i`, so the value never appears in a process list.
+        const command = `add-generic-password -U -s ${service(name)} -a ${userInfo().username} -w ${value}\n`;
+        return spawnSync('/usr/bin/security', ['-i'], { input: command, encoding: 'utf8' }).status === 0;
+    }
+    const path = secretsPath(configDir);
+    writeSecretsFile(path, { ...readSecretsFile(path), [name]: value });
+    return true;
+}
+export const readLinearKey = (configDir) => readSecret(configDir, 'linear');
+export const storeLinearKey = (configDir, key) => looksLikeLinearKey(key) && storeSecret(configDir, 'linear', key);

package/dist/service.d.ts

@@ -0,0 +1,9 @@
+import type { Check } from './types.ts';
+export interface RunnerService {
+    loaded(): boolean;
+    start(home: string, program: string[], logPath: string): boolean;
+    stop(home: string): void;
+    programArgs(home: string): string[] | null;
+    checks(): Check[];
+}
+export declare const runnerService: (platform?: NodeJS.Platform) => RunnerService;

package/dist/service.js

@@ -0,0 +1,18 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as launchd from "./launchd.js";
+import * as systemd from "./systemd.js";
+const mac = {
+    loaded: launchd.runnerLoaded,
+    start: launchd.startRunner,
+    stop: launchd.stopRunner,
+    programArgs: (home) => (existsSync(launchd.plistPath(home)) ? launchd.parsePlistArgs(readFileSync(launchd.plistPath(home), 'utf8')) : null),
+    checks: () => [],
+};
+const linux = {
+    loaded: systemd.runnerLoaded,
+    start: (home, program, logPath) => systemd.startRunner(home, program, launchd.runnerEnv(), logPath),
+    stop: systemd.stopRunner,
+    programArgs: systemd.programArgs,
+    checks: () => [systemd.lingerCheck()],
+};
+export const runnerService = (platform = process.platform) => (platform === 'darwin' ? mac : linux);

package/dist/state.d.ts

@@ -1,4 +1,4 @@
-import { type StepId } from './config.ts';
+import { type StepId, type Trigger } from './config.ts';
 export interface Current {
     pid: number;
     card?: string;
@@ -8,6 +8,7 @@ export interface Current {
     round?: number;
     startedAt?: string;
     runDir?: string;
+    source?: Trigger['source'];
 }
 export declare const lockPath: (configDir: string) => string;
 export declare function readCurrent(configDir: string): Current | null;
@@ -25,6 +26,7 @@ export interface Pending {
     drop: string[];
     add: string[];
     dropStatus?: boolean;
+    source?: 'linear' | 'voidtrack';
 }
 export declare function readPending(configDir: string): Pending[];
 export declare function writePending(configDir: string, pending: Pending[]): void;
@@ -44,6 +46,7 @@ export interface RunRecord {
     url?: string;
     workflow: string;
     trigger: string;
+    source?: Trigger['source'];
     steps: StepRecord[];
     outcome: Outcome;
     reason?: string;
@@ -61,3 +64,5 @@ export interface RunEntry {
     logs: string[];
 }
 export declare function listRuns(configDir: string, card?: string): RunEntry[];
+export declare function readCronState(configDir: string): Record<string, string>;
+export declare function writeCronState(configDir: string, state: Record<string, string>): void;

package/dist/state.js

@@ -105,3 +105,18 @@ export function listRuns(configDir, card) {
     }
     return out.sort((a, b) => (a.stamp < b.stamp ? 1 : -1));
 }
+// When each schedule last fired, by workflow and schedule, so a restart or a
+// busy runner never fires one twice.
+const cronPath = (configDir) => join(agentsDir(configDir), 'cron.json');
+export function readCronState(configDir) {
+    try {
+        return JSON.parse(readFileSync(cronPath(configDir), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeCronState(configDir, state) {
+    mkdirSync(agentsDir(configDir), { recursive: true });
+    writeFileSync(cronPath(configDir), JSON.stringify(state, null, 2) + '\n');
+}

package/dist/systemd.d.ts

@@ -0,0 +1,14 @@
+import type { Check } from './types.ts';
+export declare const UNIT = "voidshift-agents";
+export declare const servicePath: (home: string) => string;
+export declare const timerPath: (home: string) => string;
+export declare function quote(s: string): string;
+export declare function unquote(s: string): string;
+export declare function serviceUnit(program: string[], env: Record<string, string>, logPath: string): string;
+export declare const timerUnit: () => string;
+export declare function parseExecStart(unit: string): string[];
+export declare const runnerLoaded: () => boolean;
+export declare function startRunner(home: string, program: string[], env: Record<string, string>, logPath: string): boolean;
+export declare function stopRunner(home: string): void;
+export declare function programArgs(home: string): string[] | null;
+export declare function lingerCheck(): Check;

package/dist/systemd.js

@@ -0,0 +1,85 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { dirname, join } from 'node:path';
+// The runner on Linux: a systemd user service that runs one check, and a
+// timer that starts it a minute after the last one finished.
+export const UNIT = 'voidshift-agents';
+const unitDir = (home) => join(process.env.XDG_CONFIG_HOME ?? join(home, '.config'), 'systemd', 'user');
+export const servicePath = (home) => join(unitDir(home), `${UNIT}.service`);
+export const timerPath = (home) => join(unitDir(home), `${UNIT}.timer`);
+// `systemctl --user` needs the user's runtime dir, which a `sudo -iu` or `su`
+// shell does not set.
+function systemctl(args) {
+    const env = { ...process.env, XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR ?? `/run/user/${userInfo().uid}` };
+    const r = spawnSync('systemctl', ['--user', ...args], { encoding: 'utf8', env });
+    return { ok: r.status === 0, stdout: (r.stdout ?? '').trim() };
+}
+// One word of a unit file line: quoted, with the characters systemd expands
+// escaped.
+export function quote(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%').replace(/\$/g, '$$$$')}"`;
+}
+export function unquote(s) {
+    return s.replace(/\$\$/g, '$').replace(/%%/g, '%').replace(/\\(.)/g, '$1');
+}
+export function serviceUnit(program, env, logPath) {
+    const vars = Object.entries(env).map(([k, v]) => `Environment=${quote(`${k}=${v}`)}`);
+    return `[Unit]
+Description=VoidShift agents runner, one check for cards to work on
+
+[Service]
+Type=oneshot
+ExecStart=${program.map(quote).join(' ')}
+${vars.join('\n')}
+StandardOutput=append:${logPath}
+StandardError=append:${logPath}
+TimeoutStartSec=infinity
+`;
+}
+export const timerUnit = () => `[Unit]
+Description=Starts the VoidShift agents runner every minute
+
+[Timer]
+OnActiveSec=5s
+OnUnitInactiveSec=60s
+AccuracySec=1s
+
+[Install]
+WantedBy=timers.target
+`;
+// The words of a service unit's ExecStart line.
+export function parseExecStart(unit) {
+    const line = /^ExecStart=(.*)$/m.exec(unit)?.[1] ?? '';
+    return [...line.matchAll(/"((?:\\.|[^"\\])*)"|(\S+)/g)].map((m) => (m[1] !== undefined ? unquote(m[1]) : m[2]));
+}
+export const runnerLoaded = () => systemctl(['is-active', '--quiet', `${UNIT}.timer`]).ok;
+export function startRunner(home, program, env, logPath) {
+    mkdirSync(unitDir(home), { recursive: true });
+    mkdirSync(dirname(logPath), { recursive: true });
+    writeFileSync(servicePath(home), serviceUnit(program, env, logPath));
+    writeFileSync(timerPath(home), timerUnit());
+    if (!systemctl(['daemon-reload']).ok)
+        return false;
+    systemctl(['restart', `${UNIT}.timer`]);
+    return systemctl(['enable', '--now', `${UNIT}.timer`]).ok;
+}
+export function stopRunner(home) {
+    systemctl(['disable', '--now', `${UNIT}.timer`]);
+    systemctl(['stop', `${UNIT}.service`]);
+    rmSync(servicePath(home), { force: true });
+    rmSync(timerPath(home), { force: true });
+    systemctl(['daemon-reload']);
+}
+export function programArgs(home) {
+    return existsSync(servicePath(home)) ? parseExecStart(readFileSync(servicePath(home), 'utf8')) : null;
+}
+// Without lingering, systemd stops the user's timers when they log out and
+// does not start them after a reboot.
+export function lingerCheck() {
+    const user = userInfo().username;
+    const r = spawnSync('loginctl', ['show-user', user, '--property=Linger', '--value'], { encoding: 'utf8' });
+    return r.status === 0 && r.stdout.trim() === 'yes'
+        ? { name: 'runner after logout', status: 'ok', detail: 'lingering is on, the runner keeps going after logout and reboot' }
+        : { name: 'runner after logout', status: 'warn', detail: 'lingering is off, the runner stops when you log out', fix: `sudo loginctl enable-linger ${user}` };
+}

package/dist/tracker.d.ts

@@ -0,0 +1,24 @@
+import type { Tracker as Kind } from './config.ts';
+import type { Card } from './linear.ts';
+export interface Tracker {
+    viewer(): Promise<{
+        id: string;
+        name: string;
+    }>;
+    myCardsWithLabel(label: string, team: string): Promise<Card[]>;
+    card(identifier: string): Promise<Card>;
+    comments(identifier: string): Promise<{
+        body: string;
+        createdAt: string;
+    }[]>;
+    comment(card: Card, body: string): Promise<void>;
+    setLabels(card: Card, next: string[]): Promise<void>;
+    moveTo(card: Card, stateName: string): Promise<boolean>;
+}
+export declare const TRACKERS: Record<Kind, {
+    name: string;
+    keyHint: string;
+}>;
+export type Trackers = (kind: Kind) => Tracker;
+export declare function trackersFor(configDir: string): Trackers;
+export declare const noTracker: Tracker;

package/dist/tracker.js

@@ -0,0 +1,36 @@
+import { createLinear } from "./linear.js";
+import { readSecret } from "./secrets.js";
+import { createVoidTrack } from "./voidtrack.js";
+export const TRACKERS = {
+    linear: { name: 'Linear', keyHint: 'Linear > Settings > Security & access > API keys' },
+    voidtrack: { name: 'VoidTrack', keyHint: 'VoidTrack > Settings > API keys' },
+};
+export function trackersFor(configDir) {
+    const open = new Map();
+    return (kind) => {
+        let t = open.get(kind);
+        if (!t) {
+            const key = readSecret(configDir, kind);
+            if (!key)
+                throw new Error(`No ${TRACKERS[kind].name} API key. Run vsf agents key${kind === 'linear' ? '' : ` --${kind}`}`);
+            t = kind === 'voidtrack' ? createVoidTrack(key) : createLinear(key);
+            open.set(kind, t);
+        }
+        return t;
+    };
+}
+// Stands in for a tracker on a scheduled run, which has no card: reads find
+// nothing and writes go nowhere.
+export const noTracker = {
+    viewer: async () => ({ id: '', name: '' }),
+    myCardsWithLabel: async () => [],
+    card: async (id) => {
+        throw new Error(`a scheduled run has no card ${id}`);
+    },
+    comments: async () => [],
+    comment: async () => { },
+    setLabels: async (card, next) => {
+        card.labels = next;
+    },
+    moveTo: async () => false,
+};

package/dist/voidtrack.d.ts

@@ -0,0 +1,18 @@
+import type { Card } from './linear.ts';
+export declare const branchFor: (identifier: string) => string;
+export declare function mapIssue(i: any, web: string): Card;
+export declare function createVoidTrack(apiKey: string, fetcher?: typeof fetch): {
+    viewer(): Promise<{
+        id: string;
+        name: string;
+    }>;
+    myCardsWithLabel(label: string, team: string): Promise<Card[]>;
+    card(identifier: string): Promise<Card>;
+    comments(identifier: string): Promise<{
+        body: string;
+        createdAt: string;
+    }[]>;
+    comment(card: Card, body: string): Promise<void>;
+    setLabels(card: Card, next: string[]): Promise<void>;
+    moveTo(card: Card, stateName: string): Promise<boolean>;
+};