@addai/node 0.5.1 → 0.6.0

package/dist/autostart-mac.d.ts

@@ -0,0 +1,62 @@
+import { AutostartBackend, AutostartEntry } from './autostart';
+export declare const PLIST_PATH: string;
+export interface PlistSpec {
+    label: string;
+    entry: AutostartEntry;
+    env: Record<string, string>;
+    logPath: string;
+    workingDirectory: string;
+}
+/**
+ * The plist, as a string. Pure — this is what the tests assert on.
+ *
+ * KeepAlive is `true`, not `{SuccessfulExit: false}`: the node is meant to be
+ * always-on, and a remote roll relies on it. A supervised `update_runtime`
+ * installs the new version and simply EXITS; launchd starting the replacement
+ * is what makes that safe (see index.ts). ThrottleInterval keeps a crash loop
+ * to one launch per 10s instead of a spin.
+ *
+ * ProcessType is Interactive because Background jobs get throttled CPU
+ * scheduling — a daemon that supervises agent runs is not a batch job.
+ */
+export declare function buildPlist(spec: PlistSpec): string;
+/** Pull ProgramArguments back out of a plist we wrote, for `status`. */
+export declare function parsePlistEntry(xml: string): AutostartEntry | undefined;
+/** Directories macOS gates behind user consent no background agent can give. */
+export declare function protectedPathReason(scriptPath: string, home?: string): string | null;
+export declare function protectedPathError(label: string, scriptPath: string): string;
+/**
+ * Hand the node over to launchd.
+ *
+ * A daemon started by hand holds the lockfile, and `acquireLockfile()` throws
+ * for anyone else. Bootstrapping the agent underneath it would therefore mean
+ * launchd relaunching a job that exits 1 every ten seconds until the human
+ * closes their terminal. So we ask the incumbent to stand down first — SIGTERM
+ * runs its normal drain, so live entity turns finish rather than being cut.
+ *
+ * Except when the incumbent is US. `ainode startup enable` can be pressed from
+ * inside the console of the very daemon it is arming, and signalling ourselves
+ * there would kill the node the user is looking at. That case writes the plist
+ * and stops: ~/Library/LaunchAgents is read at every login, so the change
+ * lands at the next one without anybody being killed for it.
+ */
+export type Handover = 
+/** Nothing was running — safe to start the agent immediately. */
+{
+    kind: 'none';
+}
+/** The running daemon is this very process. Write only, don't bootstrap. */
+ | {
+    kind: 'self';
+}
+/** Someone else's daemon stood down; the agent can take over now. */
+ | {
+    kind: 'stopped';
+}
+/** It was asked to stop and didn't. */
+ | {
+    kind: 'stuck';
+    pid: number;
+};
+export declare function stopRunningDaemon(timeoutMs?: number, selfPid?: number): Handover;
+export declare const backend: AutostartBackend;

package/dist/autostart-mac.js

@@ -0,0 +1,306 @@
+"use strict";
+// macOS backend: a per-user LaunchAgent.
+//
+// ~/Library/LaunchAgents is loaded by launchd at every login, so the plist
+// existing IS the answer to "does this node start at login?" — no daemon, no
+// admin rights, no stored password.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backend = exports.PLIST_PATH = void 0;
+exports.buildPlist = buildPlist;
+exports.parsePlistEntry = parsePlistEntry;
+exports.protectedPathReason = protectedPathReason;
+exports.protectedPathError = protectedPathError;
+exports.stopRunningDaemon = stopRunningDaemon;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const autostart_1 = require("./autostart");
+const lockfile_1 = require("./lockfile");
+exports.PLIST_PATH = path.join(os.homedir(), 'Library', 'LaunchAgents', `${autostart_1.LABEL}.plist`);
+/** `<string>` bodies are the only place user data lands in the plist, and a
+ *  PATH entry with an `&` in it would otherwise produce invalid XML that
+ *  launchd rejects at login — silently, from the user's point of view. */
+function esc(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+/**
+ * The plist, as a string. Pure — this is what the tests assert on.
+ *
+ * KeepAlive is `true`, not `{SuccessfulExit: false}`: the node is meant to be
+ * always-on, and a remote roll relies on it. A supervised `update_runtime`
+ * installs the new version and simply EXITS; launchd starting the replacement
+ * is what makes that safe (see index.ts). ThrottleInterval keeps a crash loop
+ * to one launch per 10s instead of a spin.
+ *
+ * ProcessType is Interactive because Background jobs get throttled CPU
+ * scheduling — a daemon that supervises agent runs is not a batch job.
+ */
+function buildPlist(spec) {
+    const args = [spec.entry.file, ...spec.entry.args]
+        .map(a => `      <string>${esc(a)}</string>`)
+        .join('\n');
+    const env = Object.entries(spec.env)
+        .map(([k, v]) => `      <key>${esc(k)}</key>\n      <string>${esc(v)}</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>${esc(spec.label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+${args}
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+    <key>ProcessType</key>
+    <string>Interactive</string>
+    <key>WorkingDirectory</key>
+    <string>${esc(spec.workingDirectory)}</string>
+    <key>StandardOutPath</key>
+    <string>${esc(spec.logPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${esc(spec.logPath)}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+${env}
+    </dict>
+  </dict>
+</plist>
+`;
+}
+/** Pull ProgramArguments back out of a plist we wrote, for `status`. */
+function parsePlistEntry(xml) {
+    const block = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(xml);
+    if (!block)
+        return undefined;
+    const items = [...block[1].matchAll(/<string>([\s\S]*?)<\/string>/g)]
+        .map(m => m[1].replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&'));
+    if (!items.length)
+        return undefined;
+    return { file: items[0], args: items.slice(1) };
+}
+/* ── TCC: the failure that looks like success ────────────────────────────
+ * Found by running this for real. A LaunchAgent pinned to a script under
+ * ~/Documents starts, reports `state = running` with a healthy pid, writes
+ * nothing, and serves nothing — because macOS privacy protection blocks the
+ * open() and the process HANGS in module resolution rather than failing.
+ * `launchctl print` says the job is fine. It is not.
+ *
+ * That is the worst possible failure for this feature: the node looks alive
+ * to every tool including our own, so refuse to arm it instead. Our fleet's
+ * checkouts live in ~/Documents/GitHub, so this is the default case here, not
+ * an edge one.
+ */
+/** Directories macOS gates behind user consent no background agent can give. */
+function protectedPathReason(scriptPath, home = os.homedir()) {
+    const p = scriptPath.replace(/\/+$/, '');
+    const under = (dir) => p === dir || p.startsWith(dir + path.sep);
+    const guarded = [
+        [path.join(home, 'Documents'), '~/Documents'],
+        [path.join(home, 'Desktop'), '~/Desktop'],
+        [path.join(home, 'Downloads'), '~/Downloads'],
+        [path.join(home, 'Library', 'Mobile Documents'), 'iCloud Drive'],
+    ];
+    for (const [dir, label] of guarded)
+        if (under(dir))
+            return label;
+    if (under('/Volumes'))
+        return 'an external volume';
+    return null;
+}
+function protectedPathError(label, scriptPath) {
+    return [
+        `macOS will not let a login agent read ${label}, and this node runs from there:`,
+        `  ${scriptPath}`,
+        '',
+        'It would not fail loudly — the agent starts, reports itself healthy, and hangs',
+        'forever on the first file it tries to read. So this refuses instead.',
+        '',
+        'Fix it either way:',
+        '  npm i -g @addai/node     install outside the protected folder, then re-run this',
+        '  — or move the checkout somewhere like ~/src and start the node from there',
+        '',
+        'If you have already granted Full Disk Access to node, re-run with --force.',
+    ].join('\n');
+}
+function domain() {
+    const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+    return `gui/${uid}`;
+}
+function launchctl(args) {
+    try {
+        // stderr is piped, not inherited: `bootout` on a label that isn't loaded
+        // prints "Boot-out failed: 3: No such process", and that expected no-op
+        // was landing in the user's terminal above our own success message.
+        const out = (0, child_process_1.execFileSync)('launchctl', args, {
+            encoding: 'utf8', timeout: 20_000, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return { ok: true, output: out.toString().trim() };
+    }
+    catch (err) {
+        const e = err;
+        const stderr = e.stderr ? e.stderr.toString().trim() : '';
+        return { ok: false, output: stderr || e.message || 'launchctl failed' };
+    }
+}
+function stopRunningDaemon(timeoutMs = 40_000, selfPid = process.pid) {
+    const lock = (0, lockfile_1.readLockfile)();
+    if (!lock || !(0, lockfile_1.lockfileAlive)(lock))
+        return { kind: 'none' };
+    if (lock.pid === selfPid)
+        return { kind: 'self' };
+    try {
+        process.kill(lock.pid, 'SIGTERM');
+    }
+    catch {
+        return { kind: 'stopped' };
+    }
+    // Synchronous poll: `startup enable` is a one-shot CLI command, and making
+    // the whole backend async to sleep 250ms would buy nothing.
+    const deadline = Date.now() + timeoutMs;
+    const nap = new Int32Array(new SharedArrayBuffer(4));
+    while (Date.now() < deadline) {
+        Atomics.wait(nap, 0, 0, 250);
+        if (!(0, lockfile_1.lockfileAlive)((0, lockfile_1.readLockfile)()))
+            return { kind: 'stopped' };
+    }
+    return { kind: 'stuck', pid: lock.pid };
+}
+function enable(entry, env, logPath, opts = {}) {
+    const warnings = [];
+    const script = entry.args[0] ?? entry.file;
+    const guarded = protectedPathReason(script);
+    if (guarded && !opts.force) {
+        return { ok: false, warnings, error: protectedPathError(guarded, script) };
+    }
+    if (guarded)
+        warnings.push(`forced past macOS protection on ${guarded} — if the node hangs at login, that is why`);
+    fs.mkdirSync(path.dirname(exports.PLIST_PATH), { recursive: true });
+    fs.writeFileSync(exports.PLIST_PATH, buildPlist({
+        label: autostart_1.LABEL,
+        entry,
+        env,
+        logPath,
+        workingDirectory: os.homedir(),
+    }), { mode: 0o644 });
+    // Unload any previous copy of the agent BEFORE looking for a daemon to hand
+    // over from. Order matters: an already-supervised job that we SIGTERM while
+    // it is still loaded gets restarted by KeepAlive within the second, and the
+    // handover would sit there watching a lockfile that keeps coming back and
+    // conclude the node is stuck. Booting out first makes the stop stick.
+    launchctl(['bootout', `${domain()}/${autostart_1.LABEL}`]);
+    const handover = stopRunningDaemon();
+    if (handover.kind === 'stuck') {
+        return {
+            ok: false,
+            path: exports.PLIST_PATH,
+            warnings,
+            error: `a node is already running here (pid ${handover.pid}) and did not stop within 40s — quit it, then run \`ainode startup enable\` again`,
+        };
+    }
+    if (handover.kind === 'self') {
+        // Deliberately no bootstrap: launchd would start a second daemon, which
+        // would fail to take the lockfile and be relaunched every 10s for as long
+        // as this one lives. The plist on disk is enough.
+        warnings.push('this node is running right now, so launchd takes over at your next login (or when you restart it)');
+        return { ok: true, path: exports.PLIST_PATH, warnings };
+    }
+    if (handover.kind === 'stopped') {
+        warnings.push('stopped the node that was already running; launchd owns it now');
+    }
+    let load = launchctl(['bootstrap', domain(), exports.PLIST_PATH]);
+    if (!load.ok) {
+        // Pre-Yosemite verbs still work on every macOS we support and are the
+        // documented fallback when bootstrap is unavailable or refuses.
+        const legacy = launchctl(['load', '-w', exports.PLIST_PATH]);
+        if (!legacy.ok) {
+            return { ok: false, path: exports.PLIST_PATH, warnings, error: `launchctl could not load the agent: ${load.output}` };
+        }
+        load = legacy;
+    }
+    return { ok: true, path: exports.PLIST_PATH, warnings };
+}
+function disable() {
+    // Order matters: bootout while the plist still exists, or launchd has
+    // nothing to look up. This also STOPS a running supervised daemon — the
+    // node goes offline, which is what "stop starting at login" has to mean
+    // when the thing is running right now.
+    const out = launchctl(['bootout', `${domain()}/${autostart_1.LABEL}`]);
+    // Only fall back to the legacy verb if the modern one didn't do the job —
+    // running both unconditionally printed "Unload failed: 5" after a perfectly
+    // successful bootout.
+    if (!out.ok && fs.existsSync(exports.PLIST_PATH))
+        launchctl(['unload', '-w', exports.PLIST_PATH]);
+    try {
+        fs.unlinkSync(exports.PLIST_PATH);
+    }
+    catch { /* already gone */ }
+    return { ok: true };
+}
+function status() {
+    if (!fs.existsSync(exports.PLIST_PATH)) {
+        return { supported: true, enabled: false, supervisor: 'launchd' };
+    }
+    // Deliberately no `launchctl print` here: status() rides every heartbeat,
+    // and the plist sitting in ~/Library/LaunchAgents is already the whole
+    // answer to "will this start at login?" — launchd loads that directory at
+    // every login regardless of what is loaded right now.
+    const xml = fs.readFileSync(exports.PLIST_PATH, 'utf8');
+    const entry = parsePlistEntry(xml);
+    const issues = [];
+    if (entry && !fs.existsSync(entry.args[0] ?? entry.file)) {
+        issues.push(`the pinned program is gone (${entry.args[0] ?? entry.file}) — re-run \`ainode startup enable\``);
+    }
+    return {
+        supported: true,
+        enabled: true,
+        supervisor: 'launchd',
+        entry,
+        path: exports.PLIST_PATH,
+        ...(issues.length ? { issues } : {}),
+    };
+}
+exports.backend = { supervisor: 'launchd', status, enable, disable };

package/dist/autostart-win.d.ts

@@ -0,0 +1,46 @@
+import { AutostartBackend, AutostartEntry } from './autostart';
+export declare const STARTUP_DIR: string;
+export declare const CMD_PATH: string;
+export declare const VBS_PATH: string;
+export declare const XML_PATH: string;
+/** The account the task runs as. `DOMAIN\User` when we have a domain — a bare
+ *  username is ambiguous on a machine joined to one. */
+export declare function currentUserId(env?: NodeJS.ProcessEnv): string;
+/**
+ * The batch file that actually starts the node.
+ *
+ * Environment and output redirection live here, in a file where batch quoting
+ * behaves, instead of being wedged into a VBS string or a `schtasks` argument.
+ * The redirect matters: headless stdout on Windows has nowhere else to go, and
+ * a node whose only account of itself is missing is a node nobody can debug.
+ */
+export declare function buildCmd(entry: AutostartEntry, env: Record<string, string>, logPath: string): string;
+/**
+ * The window-hiding shim.
+ *
+ * A task running under an InteractiveToken shows a console window for every
+ * launch; with the logon trigger repeating, that would be a window popping up
+ * on the user's desktop every five minutes. `WScript.Shell.Run(…, 0, False)`
+ * starts the batch file with no window and does not wait for it.
+ */
+export declare function buildVbs(cmdPath: string): string;
+export interface TaskSpec {
+    userId: string;
+    vbsPath: string;
+    wscriptPath: string;
+    /** ISO-8601 local timestamp for the task's Date field. */
+    createdAt: string;
+}
+/**
+ * The task definition.
+ *
+ * The repetition is what stands in for launchd's KeepAlive. Task Scheduler
+ * cannot supervise this process — the shim returns instantly, so the task is
+ * "finished" a second after it starts and RestartOnFailure never applies. So
+ * the logon trigger repeats every five minutes and the action is
+ * `run --ensure`, which exits immediately when a live daemon already owns the
+ * node. Crash recovery therefore costs at most five minutes and never stacks
+ * a second daemon.
+ */
+export declare function buildTaskXml(spec: TaskSpec): string;
+export declare const backend: AutostartBackend;