@devvoid/voidshift-awake 0.2.0 → 0.3.0

package/README.md

@@ -1,14 +1,18 @@
 # VoidShift
 
-One CLI for the Void dev tools. Install it once, run `voidshift`, pick the
-tools you want, and it sets each one up with good defaults you can change.
+One CLI for the Void dev tools. Install it once, run `vsf` (short for
+`voidshift`), pick the tools you want, and it sets each one up with good
+defaults you can change. Everything setup does can be seen and changed later
+from the command line.
 
 > Early release. macOS only for now; Windows and Linux are next.
 
 ```sh
 npm i -g @devvoid/voidshift
-voidshift              # pick tools and set them up
-voidshift --defaults   # take every default, ask only what has none
+vsf setup              # pick tools and set them up
+vsf setup --defaults   # take every default, ask only what has none
+vsf                    # what every tool is doing (first run: setup)
+vsf help               # every command; vsf <tool> help for a tool's
 ```
 
 ## Tools
@@ -22,9 +26,10 @@ voidshift --defaults   # take every default, ask only what has none
 ### awake
 
 ```sh
-voidshift awake on [--until 7am | --for 6h] [--battery 20]
-voidshift awake status
-voidshift awake off
+vsf awake on [--until 7am | --for 6h] [--battery 20]
+vsf awake status
+vsf awake logs [-f]     # what the watchdog decided
+vsf awake off
 ```
 
 Setup asks for your Mac password once to add a rule that allows only
@@ -58,9 +63,18 @@ your checkout is never touched, and labels the card as it goes (`vs-dev-v1`,
 `vs-qa-v1`, then `vs-qa-verified` or `vs-parked` with a comment saying why).
 
 ```sh
-voidshift agents status        # workflows, projects, runner
-voidshift agents run ENG-123   # run one card now, in this terminal
-voidshift agents start | stop  # the background runner
+vsf agents status                  # runner, the card in progress, parked cards
+vsf agents run ENG-123 [--from qa] # run one card now, in this terminal
+vsf agents start | stop | restart  # the background runner (stop cancels the card)
+vsf agents pause | resume          # pick up no new cards for a while
+vsf agents cancel | retry ENG-123  # stop a card, or queue a parked one again
+vsf agents runs | show ENG-123     # what happened, step by step
+vsf agents logs [ENG-123] [-f]     # the runner log, or a card's step logs
+vsf agents workflows               # workflows in the order they match
+vsf agents workflow add|edit|show|rename|move|rm
+vsf agents projects | project add|edit|show|rename|rm
+vsf agents homes | link DIR        # where the agents are installed
+vsf agents clean                   # old worktrees and run logs
 ```
 
 ### memory
@@ -73,8 +87,11 @@ decisions and their why, dead ends, things that are not obvious from the code.
 Background agents read it for each card and save what they learn.
 
 ```sh
-voidshift memory status          # the vault and where recall is on
-voidshift memory search WORDS    # notes recall would bring up
+vsf memory status          # the vault and where recall is on
+vsf memory search WORDS    # notes recall would bring up
+vsf memory try "a prompt"  # exactly what recall would add to that prompt
+vsf memory check           # notes missing from INDEX.md, broken links
+vsf memory on | off        # turn recall on or off
 ```
 
 Setup creates a vault at `~/memory` or uses one you already have. Codex asks you
@@ -91,9 +108,15 @@ to trust the recall hook once: run `/hooks` in Codex.
 - **Your config** lives in `~/.config/voidshift`.
 
 ```sh
-voidshift doctor   # check everything is set up, and whether an update is out
-voidshift update   # update VoidShift and every tool you added
-voidshift tools    # list tools
+vsf doctor                     # check everything is set up, and whether an update is out
+vsf config [tool]              # every saved setting
+vsf config set KEY VALUE       # e.g. vsf config set agents.models.dev opus
+vsf config edit [tool]         # edit settings in $EDITOR, checked before saving
+vsf update                     # update VoidShift and every tool you added
+vsf tools                      # list tools
+
+Read commands take `--json`. Workflow and project names can be shortened to
+any unique start, e.g. `tether` for `tether-relay-build`.
 ```
 
 ## Development

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export type AwakeConfig = {
+    battery: number;
+    heat: boolean;
+    revertOnReboot: boolean;
+};
+export declare function validateConfig(value: Record<string, unknown>): string[];
+export declare function readConfig(configDir: string): AwakeConfig;
+export declare function writeConfig(configDir: string, value: Record<string, unknown>): string[];

package/dist/config.js

@@ -0,0 +1,32 @@
+import { DEFAULT_BATTERY_FLOOR, readState, writeState } from "./state.js";
+const KEYS = ['battery', 'heat', 'revertOnReboot'];
+// Returns the problems with a proposed config change; empty means it is fine.
+export function validateConfig(value) {
+    const problems = [];
+    for (const [key, v] of Object.entries(value)) {
+        if (!KEYS.includes(key))
+            problems.push(`Unknown setting "${key}". Known: ${KEYS.join(', ')}.`);
+        else if (key === 'battery' && !(typeof v === 'number' && Number.isInteger(v) && v >= 5 && v <= 95)) {
+            problems.push('battery must be a whole number from 5 to 95.');
+        }
+        else if (key !== 'battery' && typeof v !== 'boolean')
+            problems.push(`${key} must be true or false.`);
+    }
+    return problems;
+}
+export function readConfig(configDir) {
+    const s = readState(configDir);
+    return { battery: s.batteryFloor, heat: s.heat !== false, revertOnReboot: s.revertOnReboot !== false };
+}
+export function writeConfig(configDir, value) {
+    const problems = validateConfig(value);
+    if (problems.length)
+        return problems;
+    const state = readState(configDir);
+    // The written value is the whole config: a missing key goes back to its default.
+    state.batteryFloor = value.battery ?? DEFAULT_BATTERY_FLOOR;
+    state.heat = value.heat;
+    state.revertOnReboot = value.revertOnReboot;
+    writeState(configDir, state);
+    return [];
+}

package/dist/decide.d.ts

@@ -5,6 +5,8 @@ export interface AwakeState {
     until?: string;
     batteryFloor: number;
     lastReason?: string;
+    heat?: boolean;
+    revertOnReboot?: boolean;
 }
 export interface SystemReading {
     sleepDisabled: boolean;

package/dist/decide.js

@@ -4,9 +4,9 @@ export function decide(state, sys, now) {
     if (!state.managed)
         return { action: 'keep' };
     if (!sys.sleepDisabled)
-        return { action: 'forget', reason: 'sleep was turned back on outside voidshift' };
+        return { action: 'forget', reason: 'sleep was turned back on outside VoidShift' };
     const since = state.since ? new Date(state.since) : null;
-    if (since && sys.bootTime && sys.bootTime > since)
+    if (state.revertOnReboot !== false && since && sys.bootTime && sys.bootTime > since)
         return { action: 'revert', reason: 'the Mac restarted' };
     if (state.until && now >= new Date(state.until))
         return { action: 'revert', reason: 'the timer ended' };
@@ -14,7 +14,7 @@ export function decide(state, sys, now) {
     if (onBattery && percent !== null && percent <= state.batteryFloor) {
         return { action: 'revert', reason: `battery reached ${percent}%` };
     }
-    if (sys.thermalSerious)
+    if (state.heat !== false && sys.thermalSerious)
         return { action: 'revert', reason: 'the Mac is running too hot' };
     return { action: 'keep' };
 }

package/dist/index.js

@@ -1,22 +1,63 @@
-import { rmSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readFileSync, readSync, rmSync, statSync } from 'node:fs';
 import { parseArgs } from 'node:util';
+import { readConfig, writeConfig } from "./config.js";
 import { decide } from "./decide.js";
 import { logPath, readState, stateDir, writeState } from "./state.js";
-import { SUDOERS_PATH, installSudoers, loadWatchdog, readSystem, removeSudoers, ruleInstalled, ruleWorks, setSleepDisabled, unloadWatchdog, watchdogLoaded, } from "./system.js";
-import { parseFor, parseUntil } from "./time.js";
+import { SUDOERS_PATH, installSudoers, loadWatchdog, plistPath, readSystem, removeSudoers, ruleInstalled, ruleWorks, setSleepDisabled, unloadWatchdog, watchdogLoaded, } from "./system.js";
+import { programPaths } from "./plist.js";
+import { formatLeft, minutesLeft, parseFor, parseUntil } from "./time.js";
 const clock = (d) => d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
 function ensureWatchdog(ctx) {
     return watchdogLoaded() || loadWatchdog(ctx.home, [...ctx.selfCommand, 'awake', 'tick'], logPath(ctx.configDir));
 }
+const USAGE = {
+    on: 'Usage: vsf awake on [--until TIME | --for DURATION] [--battery PERCENT]\n  Keep the Mac running with the lid closed. TIME is like 7am or 19:30, DURATION like 6h.',
+    off: 'Usage: vsf awake off\n  Turn sleep back on.',
+    status: 'Usage: vsf awake status [--json]\n  Show whether the Mac is being kept awake, and the guardrails.',
+    logs: 'Usage: vsf awake logs [-f | --follow] [--lines N]\n  Show the last N (default 50) watchdog log lines. -f keeps printing new ones.',
+    help: 'Usage: vsf awake help [COMMAND]\n  Show usage for one command, or the list.',
+};
+const summary = () => Object.values(USAGE).map((u) => u.split('\n')[0]).join('\n');
+const bad = (ctx, command, e) => {
+    ctx.log(e instanceof Error ? e.message.split(/\. To specify|\n/)[0] : String(e));
+    ctx.log(USAGE[command]);
+    return 2;
+};
+async function help(args, ctx) {
+    const name = args.find((a) => !a.startsWith('-'));
+    if (!name)
+        ctx.log(summary());
+    else if (USAGE[name])
+        ctx.log(USAGE[name]);
+    else {
+        ctx.log(`No command called "${name}".`);
+        ctx.log(summary());
+        return 2;
+    }
+    return 0;
+}
 async function on(args, ctx) {
-    const { values } = parseArgs({
-        args,
-        options: { until: { type: 'string' }, for: { type: 'string' }, battery: { type: 'string' } },
-    });
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            options: { until: { type: 'string' }, for: { type: 'string' }, battery: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
+            allowPositionals: true,
+            strict: true,
+        }));
+    }
+    catch (e) {
+        return bad(ctx, 'on', e);
+    }
+    if (values.help) {
+        ctx.log(USAGE.on);
+        return 0;
+    }
     const now = new Date();
     let until = null;
     if (values.until && values.for) {
         ctx.log('Use --until or --for, not both.');
+        ctx.log(USAGE.on);
         return 2;
     }
     if (values.until)
@@ -25,54 +66,181 @@ async function on(args, ctx) {
         until = parseFor(values.for, now);
     if ((values.until || values.for) && !until) {
         ctx.log('Could not read that time. Try --until 7am, --until 19:30 or --for 6h.');
+        ctx.log(USAGE.on);
         return 2;
     }
-    const floor = values.battery ? Number(values.battery) : readState(ctx.configDir).batteryFloor;
+    const prior = readState(ctx.configDir);
+    const floor = values.battery ? Number(values.battery) : prior.batteryFloor;
     if (!Number.isInteger(floor) || floor < 5 || floor > 95) {
         ctx.log('--battery takes a whole percentage between 5 and 95.');
+        ctx.log(USAGE.on);
         return 2;
     }
+    const already = prior.managed && readSystem().sleepDisabled;
     if (!setSleepDisabled(true)) {
-        ctx.log('Could not turn sleep off. Run voidshift add awake first.');
+        ctx.log('Could not turn sleep off. Run vsf add awake first.');
         return 1;
     }
     writeState(ctx.configDir, {
+        ...prior,
         managed: true,
-        since: now.toISOString(),
-        until: until?.toISOString(),
+        since: already && prior.since ? prior.since : now.toISOString(),
+        // Changing only --battery on a running session keeps its end time.
+        until: until ? until.toISOString() : already ? prior.until : undefined,
         batteryFloor: floor,
     });
     if (!ensureWatchdog(ctx))
-        ctx.log('Warning: the watchdog is not running, so guardrails will not act. Run voidshift doctor.');
-    const stop = until ? `at ${clock(until)} or at ${floor}% battery` : `at ${floor}% battery`;
-    ctx.log(`Awake. The lid can close. Stops ${stop}, or with voidshift awake off.`);
-    ctx.log('Keep it out of a bag: a closed Mac with no airflow runs hot.');
+        ctx.log('Warning: the watchdog is not running, so guardrails will not act. Run vsf doctor.');
+    const endsAt = until ?? (already && prior.until ? new Date(prior.until) : null);
+    const stop = endsAt ? `at ${clock(endsAt)} or at ${floor}% battery` : `at ${floor}% battery`;
+    ctx.log(already ? `Updated. Stops ${stop}, or with vsf awake off.` : `Awake. The lid can close. Stops ${stop}, or with vsf awake off.`);
+    if (!already)
+        ctx.log('Keep it out of a bag: a closed Mac with no airflow runs hot.');
     return 0;
 }
-async function off(_args, ctx) {
+async function off(args, ctx) {
+    try {
+        const { values } = parseArgs({ args, options: { help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
+        if (values.help) {
+            ctx.log(USAGE.off);
+            return 0;
+        }
+    }
+    catch (e) {
+        return bad(ctx, 'off', e);
+    }
     const ok = setSleepDisabled(false);
     writeState(ctx.configDir, { ...readState(ctx.configDir), managed: false, lastReason: 'you turned it off' });
     ctx.log(ok ? 'Sleep restored.' : 'Could not restore sleep. Run: sudo pmset -a disablesleep 0');
     return ok ? 0 : 1;
 }
-async function status(_args, ctx) {
+async function status(args, ctx) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            options: { json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+            allowPositionals: true,
+            strict: true,
+        }));
+    }
+    catch (e) {
+        return bad(ctx, 'status', e);
+    }
+    if (values.help) {
+        ctx.log(USAGE.status);
+        return 0;
+    }
     const state = readState(ctx.configDir);
     const sys = readSystem();
+    const on = state.managed && sys.sleepDisabled;
+    const left = on && state.until ? minutesLeft(new Date(state.until), new Date()) : null;
+    const loaded = watchdogLoaded();
+    if (values.json) {
+        ctx.log(JSON.stringify({
+            on,
+            sleepDisabledByOther: sys.sleepDisabled && !state.managed,
+            since: on ? (state.since ?? null) : null,
+            until: on ? (state.until ?? null) : null,
+            minutesLeft: left,
+            batteryFloor: state.batteryFloor,
+            floorApplies: sys.battery.onBattery,
+            power: { onBattery: sys.battery.onBattery, percent: sys.battery.percent },
+            watchdog: loaded,
+            lastReason: state.lastReason ?? null,
+            heat: state.heat !== false,
+            revertOnReboot: state.revertOnReboot !== false,
+        }, null, 2));
+        return 0;
+    }
     const power = sys.battery.onBattery ? `on battery, ${sys.battery.percent ?? '?'}%` : 'on power adapter';
-    if (state.managed && sys.sleepDisabled) {
+    if (on) {
         const since = state.since ? clock(new Date(state.since)) : '?';
         const stop = state.until ? `at ${clock(new Date(state.until))} or at ${state.batteryFloor}% battery` : `at ${state.batteryFloor}% battery`;
         ctx.log(`Awake since ${since}. Stops ${stop}. Mac is ${power}.`);
     }
     else if (sys.sleepDisabled) {
-        ctx.log(`Sleep is turned off, but not by voidshift. Mac is ${power}.`);
+        ctx.log(`Sleep is turned off, but not by VoidShift. Mac is ${power}.`);
     }
     else {
         const last = state.lastReason ? ` Last session ended because ${state.lastReason}.` : '';
         ctx.log(`Off. The Mac sleeps normally.${last}`);
     }
+    if (left !== null)
+        ctx.log(`Time left: ${formatLeft(left)}.`);
+    if (!sys.battery.onBattery)
+        ctx.log(`Battery floor ${state.batteryFloor}% applies on battery only; the Mac is on power now.`);
+    if (!loaded)
+        ctx.log('Watchdog: not loaded, guardrails will not act. vsf setup awake fixes it.');
     return 0;
 }
+async function logs(args, ctx) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            options: { follow: { type: 'boolean', short: 'f' }, lines: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
+            allowPositionals: true,
+            strict: true,
+        }));
+    }
+    catch (e) {
+        return bad(ctx, 'logs', e);
+    }
+    if (values.help) {
+        ctx.log(USAGE.logs);
+        return 0;
+    }
+    const n = values.lines === undefined ? 50 : Number(values.lines);
+    if (!Number.isInteger(n) || n < 1) {
+        ctx.log('--lines takes a whole number, 1 or more.');
+        ctx.log(USAGE.logs);
+        return 2;
+    }
+    const path = logPath(ctx.configDir);
+    if (!existsSync(path)) {
+        ctx.log('No watchdog log yet.');
+        return 0;
+    }
+    const text = readFileSync(path, 'utf8');
+    const lines = text.split('\n');
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    for (const l of lines.slice(-n))
+        ctx.log(l);
+    if (!values.follow)
+        return 0;
+    // Poll for appended bytes until Ctrl+C. A shrunk file means it was rotated.
+    let offset = Buffer.byteLength(text);
+    return new Promise((resolve) => {
+        const timer = setInterval(() => {
+            try {
+                const size = statSync(path).size;
+                if (size < offset)
+                    offset = 0;
+                if (size === offset)
+                    return;
+                const fd = openSync(path, 'r');
+                const buf = Buffer.alloc(size - offset);
+                readSync(fd, buf, 0, buf.length, offset);
+                closeSync(fd);
+                offset = size;
+                const chunk = buf.toString('utf8').split('\n');
+                if (chunk[chunk.length - 1] === '')
+                    chunk.pop();
+                for (const l of chunk)
+                    ctx.log(l);
+            }
+            catch {
+                // The log may be briefly missing; try again next second.
+            }
+        }, 1000);
+        process.once('SIGINT', () => {
+            clearInterval(timer);
+            resolve(0);
+        });
+    });
+}
 // Run by launchd every minute.
 async function tick(_args, ctx) {
     const state = readState(ctx.configDir);
@@ -108,7 +276,7 @@ const awake = {
         }
         if (!ensureWatchdog(ctx))
             throw new Error('could not start the watchdog');
-        ctx.log(`Ready. voidshift awake on keeps the Mac running until ${floor}% battery or voidshift awake off.`);
+        ctx.log(`Ready. vsf awake on keeps the Mac running until ${floor}% battery or vsf awake off.`);
     },
     async uninstall(ctx) {
         const state = readState(ctx.configDir);
@@ -125,21 +293,29 @@ const awake = {
         checks.push(ruleInstalled() && works
             ? { name: 'awake rule', status: 'ok', detail: SUDOERS_PATH }
             : works
-                ? { name: 'awake rule', status: 'warn', detail: "works only through another tool's sudoers rule", fix: 'voidshift add awake' }
-                : { name: 'awake rule', status: 'fail', detail: 'cannot turn sleep off without a password', fix: 'voidshift add awake' });
+                ? { name: 'awake rule', status: 'warn', detail: "works only through another tool's sudoers rule", fix: 'vsf setup awake' }
+                : { name: 'awake rule', status: 'fail', detail: 'cannot turn sleep off without a password', fix: 'vsf setup awake' });
         checks.push(watchdogLoaded()
             ? { name: 'awake watchdog', status: 'ok', detail: 'running every minute' }
-            : { name: 'awake watchdog', status: 'fail', detail: 'not loaded, guardrails will not act', fix: 'voidshift add awake' });
+            : { name: 'awake watchdog', status: 'fail', detail: 'not loaded, guardrails will not act', fix: 'vsf setup awake' });
+        const plist = plistPath(ctx.home);
+        if (existsSync(plist)) {
+            const missing = programPaths(readFileSync(plist, 'utf8')).find((p) => !existsSync(p));
+            checks.push(missing
+                ? { name: 'awake program', status: 'fail', detail: `watchdog points at a missing ${missing}`, fix: 'vsf setup awake' }
+                : { name: 'awake program', status: 'ok', detail: 'watchdog program exists' });
+        }
         const state = readState(ctx.configDir);
         const sys = readSystem();
         if (sys.sleepDisabled && !state.managed) {
-            checks.push({ name: 'awake state', status: 'warn', detail: 'sleep is off, but not by voidshift', fix: 'Another tool may be holding it. sudo pmset -a disablesleep 0 resets it' });
+            checks.push({ name: 'awake state', status: 'warn', detail: 'sleep is off, but not by VoidShift', fix: 'Another tool may be holding it. sudo pmset -a disablesleep 0 resets it' });
         }
         else {
             checks.push({ name: 'awake state', status: 'ok', detail: state.managed ? 'on' : 'off' });
         }
         return checks;
     },
-    commands: { on, off, status, tick },
+    config: { read: readConfig, write: writeConfig },
+    commands: { on, off, status, logs, help, tick },
 };
 export default awake;

package/dist/plist.d.ts

@@ -0,0 +1 @@
+export declare function programPaths(plist: string): string[];

package/dist/plist.js

@@ -0,0 +1,9 @@
+// Absolute paths in the watchdog's ProgramArguments, so doctor can spot a
+// plist that points at something that was moved or removed.
+export function programPaths(plist) {
+    const array = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(plist);
+    if (!array)
+        return [];
+    const unxml = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+    return [...array[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unxml(m[1])).filter((v) => v.startsWith('/'));
+}

package/dist/time.d.ts

@@ -1,2 +1,4 @@
 export declare function parseUntil(input: string, now: Date): Date | null;
 export declare function parseFor(input: string, now: Date): Date | null;
+export declare function minutesLeft(until: Date, now: Date): number;
+export declare function formatLeft(minutes: number): string;

package/dist/time.js

@@ -35,3 +35,12 @@ export function parseFor(input, now) {
         return null;
     return new Date(now.getTime() + minutes * 60_000);
 }
+// Whole minutes until a time, rounded up, never negative.
+export function minutesLeft(until, now) {
+    return Math.max(0, Math.ceil((until.getTime() - now.getTime()) / 60_000));
+}
+export function formatLeft(minutes) {
+    const h = Math.floor(minutes / 60);
+    const m = minutes % 60;
+    return h && m ? `${h}h ${m}m` : h ? `${h}h` : `${m}m`;
+}

package/dist/types.d.ts

@@ -44,4 +44,8 @@ export interface Tool {
     uninstall(ctx: ToolContext): Promise<void>;
     checks(ctx: ToolContext): Promise<Check[]>;
     commands?: Record<string, ToolCommand>;
+    config?: {
+        read(configDir: string): Record<string, unknown>;
+        write(configDir: string, value: Record<string, unknown>): string[];
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devvoid/voidshift-awake",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Keep a Mac running on battery with the lid closed, with guardrails.",
   "license": "Apache-2.0",
   "repository": {