@devvoid/voidshift-awake 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# VoidShift
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+> 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
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `awake` | Keeps your Mac running, on battery and with the lid closed, and puts sleep back when the battery runs low, the Mac gets hot, a timer ends or it restarts |
+| `agents` | Agents for Claude Code and Codex, and workflows that run them in the background off your Linear cards |
+
+Memory, a markdown vault recalled into Claude Code and Codex, is coming.
+
+### awake
+
+```sh
+voidshift awake on [--until 7am | --for 6h] [--battery 20]
+voidshift awake status
+voidshift awake off
+```
+
+Setup asks for your Mac password once to add a rule that allows only
+`pmset -a disablesleep 0|1`. A small watchdog checks every minute and turns
+sleep back on when it should. Keep a closed Mac out of a bag: with no airflow
+it runs hot.
+
+### agents
+
+Five agents, installed into Claude Code (and Codex if you use it):
+
+| Agent | What it does |
+|---|---|
+| Plan | plans a Linear card against the code |
+| Plan review | checks a plan before it is published |
+| Publish | posts the plan to the card and hands it over |
+| Dev | implements the plan and opens a draft PR |
+| QA | CI, then code review, then a usability check in a headless browser |
+
+Use them yourself (`/vs-plan ENG-123` in Claude Code), or let a **workflow**
+run them. A workflow starts when one of your Linear cards gets a label, runs
+agents in order in a project (a repo on your Mac), and sends work back to the
+step that made it when a check fails:
+
+```
+when ENG + vs-plan:  Dev → QA  in tether-relay
+```
+
+The runner checks Linear every minute, works in its own copy of the repo so
+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
+```
+
+## What to know
+
+- **Your own logins.** Agents run the official `claude` and `codex` CLIs you
+  already use, signed in with your own account. VoidShift never reads or
+  stores those credentials. The Linear API key for the runner lives in your
+  macOS Keychain.
+- **Trust.** The Dev agent can run shell commands inside its copy of the repo
+  so it can install and test. Review its pull requests like any other.
+- **Your config** lives in `~/.config/voidshift`.
+
+```sh
+voidshift doctor   # check everything is set up
+voidshift tools    # list tools
+```
+
+## Development
+
+```sh
+pnpm install
+pnpm test
+node packages/cli/src/main.ts
+```
+
+Node 22.18 or newer runs the TypeScript sources directly. Releases are cut by
+pushing a `v*` tag; CI publishes every package at that version.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/dist/decide.d.ts

@@ -0,0 +1,24 @@
+import type { Battery } from './parse.ts';
+export interface AwakeState {
+    managed: boolean;
+    since?: string;
+    until?: string;
+    batteryFloor: number;
+    lastReason?: string;
+}
+export interface SystemReading {
+    sleepDisabled: boolean;
+    battery: Battery;
+    thermalSerious: boolean;
+    bootTime: Date | null;
+}
+export type Decision = {
+    action: 'keep';
+} | {
+    action: 'revert';
+    reason: string;
+} | {
+    action: 'forget';
+    reason: string;
+};
+export declare function decide(state: AwakeState, sys: SystemReading, now: Date): Decision;

package/dist/decide.js

@@ -0,0 +1,20 @@
+// What the watchdog should do on each tick. 'revert' turns sleep back on;
+// 'forget' clears our state when someone else already turned sleep back on.
+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' };
+    const since = state.since ? new Date(state.since) : null;
+    if (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' };
+    const { onBattery, percent } = sys.battery;
+    if (onBattery && percent !== null && percent <= state.batteryFloor) {
+        return { action: 'revert', reason: `battery reached ${percent}%` };
+    }
+    if (sys.thermalSerious)
+        return { action: 'revert', reason: 'the Mac is running too hot' };
+    return { action: 'keep' };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from './types.ts';
+declare const awake: Tool;
+export default awake;

package/dist/index.js

@@ -0,0 +1,145 @@
+import { rmSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+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";
+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));
+}
+async function on(args, ctx) {
+    const { values } = parseArgs({
+        args,
+        options: { until: { type: 'string' }, for: { type: 'string' }, battery: { type: 'string' } },
+    });
+    const now = new Date();
+    let until = null;
+    if (values.until && values.for) {
+        ctx.log('Use --until or --for, not both.');
+        return 2;
+    }
+    if (values.until)
+        until = parseUntil(values.until, now);
+    if (values.for)
+        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.');
+        return 2;
+    }
+    const floor = values.battery ? Number(values.battery) : readState(ctx.configDir).batteryFloor;
+    if (!Number.isInteger(floor) || floor < 5 || floor > 95) {
+        ctx.log('--battery takes a whole percentage between 5 and 95.');
+        return 2;
+    }
+    if (!setSleepDisabled(true)) {
+        ctx.log('Could not turn sleep off. Run voidshift add awake first.');
+        return 1;
+    }
+    writeState(ctx.configDir, {
+        managed: true,
+        since: now.toISOString(),
+        until: until?.toISOString(),
+        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.');
+    return 0;
+}
+async function off(_args, ctx) {
+    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) {
+    const state = readState(ctx.configDir);
+    const sys = readSystem();
+    const power = sys.battery.onBattery ? `on battery, ${sys.battery.percent ?? '?'}%` : 'on power adapter';
+    if (state.managed && sys.sleepDisabled) {
+        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}.`);
+    }
+    else {
+        const last = state.lastReason ? ` Last session ended because ${state.lastReason}.` : '';
+        ctx.log(`Off. The Mac sleeps normally.${last}`);
+    }
+    return 0;
+}
+// Run by launchd every minute.
+async function tick(_args, ctx) {
+    const state = readState(ctx.configDir);
+    if (!state.managed)
+        return 0;
+    const d = decide(state, readSystem(), new Date());
+    if (d.action === 'keep')
+        return 0;
+    if (d.action === 'revert' && !setSleepDisabled(false)) {
+        ctx.log(`${new Date().toISOString()} could not restore sleep (${d.reason})`);
+        return 1;
+    }
+    writeState(ctx.configDir, { ...state, managed: false, lastReason: d.reason });
+    ctx.log(`${new Date().toISOString()} sleep restored: ${d.reason}`);
+    return 0;
+}
+const awake = {
+    name: 'awake',
+    summary: 'Keep the Mac running on battery with the lid closed, with guardrails',
+    async install(ctx) {
+        if (process.platform !== 'darwin')
+            throw new Error('awake runs on macOS only');
+        const state = readState(ctx.configDir);
+        const floor = await ctx.ui.text('Turn sleep back on at what battery level (%)?', {
+            initial: String(state.batteryFloor),
+            validate: (v) => (/^\d+$/.test(v) && Number(v) >= 5 && Number(v) <= 95 ? undefined : 'A whole number from 5 to 95'),
+        });
+        writeState(ctx.configDir, { ...readState(ctx.configDir), batteryFloor: Number(floor) });
+        if (!ruleInstalled() || !ruleWorks()) {
+            ctx.log('Awake needs your Mac password once, to allow turning sleep off. macOS asks for it next:');
+            if (!installSudoers())
+                throw new Error('could not install the sleep permission rule');
+        }
+        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.`);
+    },
+    async uninstall(ctx) {
+        const state = readState(ctx.configDir);
+        if (state.managed)
+            setSleepDisabled(false);
+        unloadWatchdog(ctx.home);
+        ctx.log('Removing the sleep permission rule needs your password:');
+        removeSudoers();
+        rmSync(stateDir(ctx.configDir), { recursive: true, force: true });
+    },
+    async checks(ctx) {
+        const checks = [];
+        const works = ruleWorks();
+        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' });
+        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' });
+        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' });
+        }
+        else {
+            checks.push({ name: 'awake state', status: 'ok', detail: state.managed ? 'on' : 'off' });
+        }
+        return checks;
+    },
+    commands: { on, off, status, tick },
+};
+export default awake;

package/dist/parse.d.ts

@@ -0,0 +1,8 @@
+export interface Battery {
+    onBattery: boolean;
+    percent: number | null;
+}
+export declare function parseSleepDisabled(out: string): boolean;
+export declare function parseBattery(out: string): Battery;
+export declare function parseThermalSerious(out: string): boolean;
+export declare function parseBootTime(out: string): Date | null;

package/dist/parse.js

@@ -0,0 +1,27 @@
+// Parsers for macOS power tool output. Kept pure so they are testable
+// against captured samples.
+// `pmset -g`: " SleepDisabled\t\t1"
+export function parseSleepDisabled(out) {
+    const m = out.match(/SleepDisabled\s+(\d)/);
+    return m?.[1] === '1';
+}
+// `pmset -g batt`: "Now drawing from 'Battery Power'" then " -InternalBattery-0 ... 89%; discharging"
+export function parseBattery(out) {
+    const onBattery = /'Battery Power'/.test(out);
+    const m = out.match(/(\d{1,3})%/);
+    return { onBattery, percent: m ? Number(m[1]) : null };
+}
+// `pmset -g therm`: nothing recorded on a cool Mac. Under load it reports a
+// thermal warning level and CPU_Speed_Limit (100 = no throttling).
+export function parseThermalSerious(out) {
+    const level = out.match(/thermal warning level[^0-9]*(\d+)/i);
+    if (level && Number(level[1]) > 0)
+        return true;
+    const speed = out.match(/CPU_Speed_Limit\s*=\s*(\d+)/);
+    return speed ? Number(speed[1]) < 60 : false;
+}
+// `sysctl -n kern.boottime`: "{ sec = 1787598645, usec = 753120 } Mon Aug 24 ..."
+export function parseBootTime(out) {
+    const m = out.match(/sec = (\d+)/);
+    return m ? new Date(Number(m[1]) * 1000) : null;
+}

package/dist/state.d.ts

@@ -0,0 +1,7 @@
+import type { AwakeState } from './decide.ts';
+export declare const DEFAULT_BATTERY_FLOOR = 20;
+export declare const stateDir: (configDir: string) => string;
+export declare const statePath: (configDir: string) => string;
+export declare const logPath: (configDir: string) => string;
+export declare function readState(configDir: string): AwakeState;
+export declare function writeState(configDir: string, state: AwakeState): void;

package/dist/state.js

@@ -0,0 +1,17 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const DEFAULT_BATTERY_FLOOR = 20;
+export const stateDir = (configDir) => join(configDir, 'awake');
+export const statePath = (configDir) => join(stateDir(configDir), 'state.json');
+export const logPath = (configDir) => join(stateDir(configDir), 'watchdog.log');
+export function readState(configDir) {
+    const path = statePath(configDir);
+    if (!existsSync(path))
+        return { managed: false, batteryFloor: DEFAULT_BATTERY_FLOOR };
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+export function writeState(configDir, state) {
+    const path = statePath(configDir);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
+}

package/dist/system.d.ts

@@ -0,0 +1,15 @@
+import type { SystemReading } from './decide.ts';
+export declare const SUDOERS_PATH = "/etc/sudoers.d/voidshift-awake";
+export declare const LABEL = "org.devvoid.voidshift.awake";
+export declare function readSystem(): SystemReading;
+export declare function setSleepDisabled(disabled: boolean): boolean;
+export declare function ruleInstalled(): boolean;
+export declare function ruleWorks(): boolean;
+export declare function sudoersRule(user: string): string;
+export declare function installSudoers(): boolean;
+export declare function removeSudoers(): boolean;
+export declare function plistPath(home: string): string;
+export declare function watchdogPlist(program: string[], logPath: string): string;
+export declare function watchdogLoaded(): boolean;
+export declare function loadWatchdog(home: string, program: string[], logPath: string): boolean;
+export declare function unloadWatchdog(home: string): void;

package/dist/system.js

@@ -0,0 +1,108 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir, userInfo } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parseBattery, parseBootTime, parseSleepDisabled, parseThermalSerious } from "./parse.js";
+const PMSET = '/usr/bin/pmset';
+export const SUDOERS_PATH = '/etc/sudoers.d/voidshift-awake';
+export const LABEL = 'org.devvoid.voidshift.awake';
+function exec(cmd, args, interactive = false) {
+    const r = spawnSync(cmd, args, {
+        encoding: 'utf8',
+        stdio: interactive ? 'inherit' : 'pipe',
+        timeout: interactive ? undefined : 10_000,
+    });
+    return { ok: r.status === 0, stdout: (r.stdout ?? '').trim() };
+}
+export function readSystem() {
+    return {
+        sleepDisabled: parseSleepDisabled(exec(PMSET, ['-g']).stdout),
+        battery: parseBattery(exec(PMSET, ['-g', 'batt']).stdout),
+        thermalSerious: parseThermalSerious(exec(PMSET, ['-g', 'therm']).stdout),
+        bootTime: parseBootTime(exec('/usr/sbin/sysctl', ['-n', 'kern.boottime']).stdout),
+    };
+}
+// Never prompts: relies on the sudoers rule installed at setup.
+export function setSleepDisabled(disabled) {
+    return exec('/usr/bin/sudo', ['-n', PMSET, '-a', 'disablesleep', disabled ? '1' : '0']).ok;
+}
+// Another tool's sudoers rule can make ruleWorks() true on its own, so
+// installation and health both key on our own file existing.
+export function ruleInstalled() {
+    return existsSync(SUDOERS_PATH);
+}
+export function ruleWorks() {
+    return exec('/usr/bin/sudo', ['-n', '-l', PMSET, '-a', 'disablesleep', '1']).ok;
+}
+// Allows exactly the two pmset invocations awake needs, for this user only.
+export function sudoersRule(user) {
+    if (!/^[a-z_][a-z0-9_.-]*$/i.test(user) || user.toUpperCase() === 'ALL')
+        throw new Error(`unexpected user name: ${user}`);
+    return `${user} ALL=(root) NOPASSWD: ${PMSET} -a disablesleep 0, ${PMSET} -a disablesleep 1\n`;
+}
+// Interactive: sudo asks for the user's password once. The rule is checked
+// with visudo before it is installed, so a bad file can never lock sudo.
+export function installSudoers() {
+    const dir = mkdtempSync(join(tmpdir(), 'voidshift-'));
+    const file = join(dir, 'voidshift-awake');
+    try {
+        writeFileSync(file, sudoersRule(userInfo().username), { mode: 0o600 });
+        if (!exec('/usr/bin/sudo', ['/usr/sbin/visudo', '-cf', file], true).ok)
+            return false;
+        return exec('/usr/bin/sudo', ['/usr/bin/install', '-m', '0440', '-o', 'root', '-g', 'wheel', file, SUDOERS_PATH], true).ok;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+export function removeSudoers() {
+    if (!existsSync(SUDOERS_PATH))
+        return true;
+    return exec('/usr/bin/sudo', ['/bin/rm', '-f', SUDOERS_PATH], true).ok;
+}
+export function plistPath(home) {
+    return join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`);
+}
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+export function watchdogPlist(program, logPath) {
+    const args = program.map((a) => `    <string>${xml(a)}</string>`).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>StartInterval</key>
+  <integer>60</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xml(logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(logPath)}</string>
+</dict>
+</plist>
+`;
+}
+const domain = () => `gui/${userInfo().uid}`;
+export function watchdogLoaded() {
+    return exec('/bin/launchctl', ['print', `${domain()}/${LABEL}`]).ok;
+}
+export function loadWatchdog(home, program, logPath) {
+    const path = plistPath(home);
+    mkdirSync(dirname(path), { recursive: true });
+    mkdirSync(dirname(logPath), { recursive: true });
+    writeFileSync(path, watchdogPlist(program, logPath));
+    if (watchdogLoaded())
+        exec('/bin/launchctl', ['bootout', `${domain()}/${LABEL}`]);
+    return exec('/bin/launchctl', ['bootstrap', domain(), path]).ok;
+}
+export function unloadWatchdog(home) {
+    if (watchdogLoaded())
+        exec('/bin/launchctl', ['bootout', `${domain()}/${LABEL}`]);
+    rmSync(plistPath(home), { force: true });
+}

package/dist/time.d.ts

@@ -0,0 +1,2 @@
+export declare function parseUntil(input: string, now: Date): Date | null;
+export declare function parseFor(input: string, now: Date): Date | null;

package/dist/time.js

@@ -0,0 +1,37 @@
+// "7am", "7:30am", "19:00" -> the next time that clock reading comes round.
+export function parseUntil(input, now) {
+    const m = input.trim().match(/^(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/i);
+    if (!m)
+        return null;
+    let hour = Number(m[1]);
+    const minute = Number(m[2] ?? 0);
+    const meridiem = m[3]?.toLowerCase();
+    if (minute > 59)
+        return null;
+    if (meridiem) {
+        if (hour < 1 || hour > 12)
+            return null;
+        if (hour === 12)
+            hour = 0;
+        if (meridiem === 'pm')
+            hour += 12;
+    }
+    else if (hour > 23) {
+        return null;
+    }
+    const at = new Date(now);
+    at.setHours(hour, minute, 0, 0);
+    if (at <= now)
+        at.setDate(at.getDate() + 1);
+    return at;
+}
+// "6h", "90m", "1h30m" -> now plus that long.
+export function parseFor(input, now) {
+    const m = input.trim().match(/^(?:(\d+)h)?(?:(\d+)m)?$/i);
+    if (!m || (!m[1] && !m[2]))
+        return null;
+    const minutes = Number(m[1] ?? 0) * 60 + Number(m[2] ?? 0);
+    if (minutes <= 0)
+        return null;
+    return new Date(now.getTime() + minutes * 60_000);
+}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export type CheckStatus = 'ok' | 'warn' | 'fail';
+export interface Check {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+    fix?: string;
+}
+export interface Choice<T extends string> {
+    value: T;
+    label: string;
+    hint?: string;
+}
+export interface Ui {
+    info(line: string): void;
+    warn(line: string): void;
+    text(message: string, o?: {
+        initial?: string;
+        placeholder?: string;
+        validate?: (v: string) => string | undefined;
+    }): Promise<string>;
+    secret(message: string, validate?: (v: string) => string | undefined): Promise<string>;
+    confirm(message: string, initial?: boolean): Promise<boolean>;
+    select<T extends string>(message: string, choices: Choice<T>[], initial?: T): Promise<T>;
+    multiselect<T extends string>(message: string, choices: Choice<T>[], initial?: T[]): Promise<T[]>;
+    search<T extends string>(message: string, choices: Choice<T>[], placeholder?: string, initial?: T): Promise<T>;
+    path(message: string, o?: {
+        initial?: string;
+        validate?: (v: string) => string | undefined;
+    }): Promise<string>;
+}
+export interface ToolContext {
+    defaults: boolean;
+    home: string;
+    configDir: string;
+    selfCommand: string[];
+    log: (line: string) => void;
+    ui: Ui;
+}
+export type ToolCommand = (args: string[], ctx: ToolContext) => Promise<number>;
+export interface Tool {
+    name: string;
+    summary: string;
+    install(ctx: ToolContext): Promise<void>;
+    uninstall(ctx: ToolContext): Promise<void>;
+    checks(ctx: ToolContext): Promise<Check[]>;
+    commands?: Record<string, ToolCommand>;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Structural copy of the contract in packages/cli/src/tool.ts, so the tool
+// builds without depending on the CLI package.
+export {};

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@devvoid/voidshift-awake",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Keep a Mac running on battery with the lid closed, with guardrails.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EratosVoid/voidshift.git",
+    "directory": "tools/awake"
+  },
+  "homepage": "https://github.com/EratosVoid/voidshift#readme",
+  "bugs": {
+    "url": "https://github.com/EratosVoid/voidshift/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "agents",
+    "linear",
+    "cli",
+    "macos"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.ts",
+    "prepublishOnly": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.0",
+    "typescript": "^5.9.0"
+  }
+}