ghostrail 0.8.0 → 0.10.0

package/dist/service/manager.d.ts

@@ -0,0 +1,71 @@
+import { type UnitSpec } from "./unit.js";
+/**
+ * Talking to the platform's user service manager. Detection is deliberate:
+ * "no service manager" and "a service manager this does not support yet" are
+ * different answers and deserve different messages.
+ */
+export type ManagerKind = "systemd" | "launchd" | "none";
+/** Which manager this platform offers, whether or not it is supported. */
+export declare function detectManager(): Promise<ManagerKind>;
+/** Where systemd looks for this user's units. */
+export declare function systemdUnitDir(env?: NodeJS.ProcessEnv): string;
+/** What `install` did with one unit, so the caller can report it honestly. */
+export type InstallOutcome = "written" | "unchanged" | "hand-edited";
+/**
+ * Write a unit unless it is already right, or has been edited.
+ *
+ * An edited unit is never overwritten. Same instinct as `init --update`: a
+ * customization is deliberate until proven otherwise, and silently reverting
+ * one is the kind of thing that makes a tool untrustworthy.
+ */
+export declare function installUnit(spec: UnitSpec, env?: NodeJS.ProcessEnv): Promise<{
+    outcome: InstallOutcome;
+    unit: string;
+    file: string;
+}>;
+/** Reload the manager so a newly written unit is visible. */
+export declare function reload(): Promise<void>;
+/** Enable and start a unit. Returns an error message, or undefined on success. */
+export declare function enableAndStart(unit: string): Promise<string | undefined>;
+/**
+ * Stop and disable a unit.
+ *
+ * This can genuinely take minutes: an in-flight tick is not interrupted, so the
+ * manager waits out the current agent run. Callers should say so before this
+ * starts rather than letting it look hung.
+ */
+export declare function disableAndStop(unit: string): Promise<string | undefined>;
+/** Remove a unit file. Absent is success: the goal is that it is not there. */
+export declare function removeUnit(unit: string, env?: NodeJS.ProcessEnv): Promise<void>;
+/** Active state per unit, for the units asked about. */
+export declare function unitStates(units: readonly string[]): Promise<Map<string, string>>;
+/**
+ * The service manager, behind a seam.
+ *
+ * This is injectable for one blunt reason: without it, a test that calls
+ * `ghostrail start` installs and enables real user services on the developer's
+ * machine. That is not hypothetical. Writing these tests did exactly that,
+ * leaving four enabled units crash-looping against deleted temp directories,
+ * because the default unit directory falls back to the real `~/.config` and
+ * `systemctl enable --now` does what it is told.
+ *
+ * A command must be drivable without touching the machine it runs on.
+ */
+export interface ServiceManager {
+    kind(): Promise<ManagerKind>;
+    /** Write a unit file verbatim, for units with no UnitSpec (the dashboard). */
+    installRaw(unit: string, contents: string): Promise<InstallOutcome>;
+    install(spec: UnitSpec): Promise<{
+        outcome: InstallOutcome;
+        unit: string;
+        file: string;
+    }>;
+    /** Enable and start. Returns an error message, or undefined on success. */
+    enable(unit: string): Promise<string | undefined>;
+    /** Stop and disable. Returns an error message, or undefined on success. */
+    disable(unit: string): Promise<string | undefined>;
+    states(units: readonly string[]): Promise<Map<string, string>>;
+}
+/** The real one: systemd through `systemctl --user`. */
+export declare function systemdManager(env?: NodeJS.ProcessEnv): ServiceManager;
+//# sourceMappingURL=manager.d.ts.map

package/dist/service/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/service/manager.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,QAAQ,EAAgD,MAAM,WAAW,CAAC;AAExF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzD,0EAA0E;AAC1E,wBAAsB,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC,CAU1D;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAG3E;AAED,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,CAAC;AAErE;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,QAAQ,EACd,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBlE;AAQD,6DAA6D;AAC7D,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAE5C;AAED,kFAAkF;AAClF,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG9E;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ9E;AAED,+EAA+E;AAC/E,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wDAAwD;AACxD,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAIvF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7B,8EAA8E;IAC9E,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACpE,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1F,2EAA2E;IAC3E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAClD,2EAA2E;IAC3E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACnD,MAAM,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChE;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,cAAc,CA0BnF"}

package/dist/service/manager.js

@@ -0,0 +1,125 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { spawnCollect } from "../backend/proc.js";
+import { parseUnitStates, renderSystemdUnit, unitName } from "./unit.js";
+/** Which manager this platform offers, whether or not it is supported. */
+export async function detectManager() {
+    if (process.platform === "darwin") {
+        const launchctl = await spawnCollect(["launchctl", "help"], { timeoutMs: 5_000 });
+        // launchctl exits nonzero for `help`, so presence is what is being tested.
+        return launchctl.exitCode === 127 ? "none" : "launchd";
+    }
+    const systemctl = await spawnCollect(["systemctl", "--user", "--version"], {
+        timeoutMs: 5_000,
+    });
+    return systemctl.exitCode === 0 ? "systemd" : "none";
+}
+/** Where systemd looks for this user's units. */
+export function systemdUnitDir(env = process.env) {
+    const base = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(base, "systemd", "user");
+}
+/**
+ * Write a unit unless it is already right, or has been edited.
+ *
+ * An edited unit is never overwritten. Same instinct as `init --update`: a
+ * customization is deliberate until proven otherwise, and silently reverting
+ * one is the kind of thing that makes a tool untrustworthy.
+ */
+export async function installUnit(spec, env = process.env) {
+    const unit = unitName(spec.name, spec.path);
+    const dir = systemdUnitDir(env);
+    const file = join(dir, unit);
+    const wanted = renderSystemdUnit(spec);
+    let current;
+    try {
+        current = await readFile(file, "utf8");
+    }
+    catch {
+        current = undefined;
+    }
+    if (current === wanted)
+        return { outcome: "unchanged", unit, file };
+    if (current !== undefined)
+        return { outcome: "hand-edited", unit, file };
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, wanted, "utf8");
+    return { outcome: "written", unit, file };
+}
+/** Run a systemctl user subcommand, returning its exit code and output. */
+async function systemctl(args) {
+    const result = await spawnCollect(["systemctl", "--user", ...args], { timeoutMs: 30_000 });
+    return { code: result.exitCode, out: `${result.stdout}${result.stderr}` };
+}
+/** Reload the manager so a newly written unit is visible. */
+export async function reload() {
+    await systemctl(["daemon-reload"]);
+}
+/** Enable and start a unit. Returns an error message, or undefined on success. */
+export async function enableAndStart(unit) {
+    const result = await systemctl(["enable", "--now", unit]);
+    return result.code === 0 ? undefined : result.out.trim();
+}
+/**
+ * Stop and disable a unit.
+ *
+ * This can genuinely take minutes: an in-flight tick is not interrupted, so the
+ * manager waits out the current agent run. Callers should say so before this
+ * starts rather than letting it look hung.
+ */
+export async function disableAndStop(unit) {
+    const result = await systemctl(["disable", "--now", unit]);
+    if (result.code === 0)
+        return undefined;
+    // A unit that was never installed is not a failure to stop. The goal is that
+    // it is not running, and it is not. Reporting this as an error made `stop` on
+    // a never-started ghostrail look broken.
+    if (/does not exist|not loaded|no such file/i.test(result.out))
+        return undefined;
+    return result.out.trim();
+}
+/** Remove a unit file. Absent is success: the goal is that it is not there. */
+export async function removeUnit(unit, env = process.env) {
+    await rm(join(systemdUnitDir(env), unit), { force: true });
+}
+/** Active state per unit, for the units asked about. */
+export async function unitStates(units) {
+    if (units.length === 0)
+        return new Map();
+    const result = await systemctl(["show", "--property=Id", "--property=ActiveState", ...units]);
+    return parseUnitStates(result.out);
+}
+/** The real one: systemd through `systemctl --user`. */
+export function systemdManager(env = process.env) {
+    return {
+        kind: detectManager,
+        install: (spec) => installUnit(spec, env),
+        installRaw: async (unit, contents) => {
+            const dir = systemdUnitDir(env);
+            const file = join(dir, unit);
+            let current;
+            try {
+                current = await readFile(file, "utf8");
+            }
+            catch {
+                current = undefined;
+            }
+            if (current === contents)
+                return "unchanged";
+            if (current !== undefined)
+                return "hand-edited";
+            await mkdir(dir, { recursive: true });
+            await writeFile(file, contents, "utf8");
+            return "written";
+        },
+        enable: async (unit) => {
+            await reload();
+            return enableAndStart(unit);
+        },
+        disable: disableAndStop,
+        states: unitStates,
+    };
+}
+//# sourceMappingURL=manager.js.map

package/dist/service/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/service/manager.ts"],"names":[],"mappings":"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"}

package/dist/service/unit.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Rendering and naming for the user service units that keep a ghostrail
+ * running. Pure: nothing here touches the disk or shells out, so the awkward
+ * parts (unit naming, the stop timeout) are testable without a service manager.
+ */
+/** Everything a unit file needs. */
+export interface UnitSpec {
+    /** The ghostrail's display name, for the unit description. */
+    name: string;
+    /** Absolute path to the repo. Becomes the working directory. */
+    path: string;
+    /** Absolute path to the ghostrail binary. */
+    exec: string;
+    /** Poll interval, as a duration string like `5m`. */
+    interval: string;
+    /** How long the manager waits for a clean stop, in seconds. */
+    stopTimeoutSec: number;
+}
+/**
+ * The unit file name for a ghostrail: `ghostrail-<slug>-<hash>.service`.
+ *
+ * The hash of the path is not decoration. `name` is display-only and duplicates
+ * are entirely legal: two repos scaffolded from the same template are both
+ * called `code-local`. Keying the unit on the name alone would give them one
+ * unit between them, so starting the second would silently hijack the first.
+ * The identity is the path, so the path is what disambiguates.
+ */
+export declare function unitName(name: string, path: string): string;
+/**
+ * How long the service manager must wait for a clean stop.
+ *
+ * `watchLoop` checks its abort signal *before* each tick and each sleep, so a
+ * SIGTERM arriving mid-tick does not interrupt the running agent: the tick
+ * finishes first. A manager that gives up sooner SIGKILLs a live agent run,
+ * orphaning its container and leaving the tracker issue claimed by a bot that no
+ * longer exists.
+ *
+ * The headroom is there because the agent timeout bounds the agent, not the
+ * tick: provisioning, the gate, and publishing all happen outside it.
+ */
+export declare function stopTimeoutSeconds(timeoutMs: number): number;
+/**
+ * A systemd user unit. Deterministic, so an unchanged unit can be recognized
+ * and an edited one left alone.
+ *
+ * Paths are written as-is: a unit file is not shell, and a path containing a
+ * space is legal in `WorkingDirectory=`.
+ */
+export declare function renderSystemdUnit(spec: UnitSpec): string;
+/**
+ * Parse `systemctl --user show --property=Id --property=ActiveState` for
+ * several units into unit name -> active state.
+ *
+ * Tolerates what the real command emits: records separated by blank lines,
+ * properties in any order, extra properties, and a unit that does not exist
+ * (reported as `inactive` rather than as a failure). A record with no `Id` is
+ * skipped rather than fatal.
+ */
+export declare function parseUnitStates(stdout: string): Map<string, string>;
+/** The unit that runs the cross-ghostrail dashboard. Only ever one. */
+export declare const DASHBOARD_UNIT = "ghostrail-dashboard.service";
+/**
+ * The dashboard's unit. Unlike a ghostrail's, it has no `WorkingDirectory`
+ * tied to a repo: it serves all of them and reads the registry from the global
+ * config dir.
+ *
+ * Its stop timeout is short on purpose. A ghostrail needs minutes because an
+ * in-flight tick is not interrupted; an HTTP server has nothing to protect.
+ */
+export declare function renderDashboardUnit(exec: string, port: number, bind: string): string;
+//# sourceMappingURL=unit.d.ts.map

package/dist/service/unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit.d.ts","sourceRoot":"","sources":["../../src/service/unit.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,oCAAoC;AACpC,MAAM,WAAW,QAAQ;IACvB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;CACxB;AAWD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG3D;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAoBxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBnE;AAED,uEAAuE;AACvE,eAAO,MAAM,cAAc,gCAAgC,CAAC;AAE5D;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBpF"}

package/dist/service/unit.js

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+/** Lowercase, non-alphanumeric runs collapsed to `-`, trimmed. */
+function slug(name) {
+    const out = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return out.length > 0 ? out : "ghostrail";
+}
+/**
+ * The unit file name for a ghostrail: `ghostrail-<slug>-<hash>.service`.
+ *
+ * The hash of the path is not decoration. `name` is display-only and duplicates
+ * are entirely legal: two repos scaffolded from the same template are both
+ * called `code-local`. Keying the unit on the name alone would give them one
+ * unit between them, so starting the second would silently hijack the first.
+ * The identity is the path, so the path is what disambiguates.
+ */
+export function unitName(name, path) {
+    const hash = createHash("sha256").update(path, "utf8").digest("hex").slice(0, 8);
+    return `ghostrail-${slug(name)}-${hash}.service`;
+}
+/** Headroom over the agent timeout, in seconds. */
+const STOP_HEADROOM_SEC = 300;
+/** Never wait less than this for a stop, however short the configured timeout. */
+const MIN_STOP_SEC = 600;
+/**
+ * How long the service manager must wait for a clean stop.
+ *
+ * `watchLoop` checks its abort signal *before* each tick and each sleep, so a
+ * SIGTERM arriving mid-tick does not interrupt the running agent: the tick
+ * finishes first. A manager that gives up sooner SIGKILLs a live agent run,
+ * orphaning its container and leaving the tracker issue claimed by a bot that no
+ * longer exists.
+ *
+ * The headroom is there because the agent timeout bounds the agent, not the
+ * tick: provisioning, the gate, and publishing all happen outside it.
+ */
+export function stopTimeoutSeconds(timeoutMs) {
+    // Total by construction. The caller reads this from a validated config, so a
+    // negative or non-finite value should be unreachable, but this number is the
+    // one thing standing between a stop and a SIGKILL through a live agent run.
+    // Rendering `TimeoutStopSec=NaN` would make systemd reject the whole unit.
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        return MIN_STOP_SEC;
+    const seconds = Math.ceil(timeoutMs / 1000) + STOP_HEADROOM_SEC;
+    return Math.max(seconds, MIN_STOP_SEC);
+}
+/**
+ * A systemd user unit. Deterministic, so an unchanged unit can be recognized
+ * and an edited one left alone.
+ *
+ * Paths are written as-is: a unit file is not shell, and a path containing a
+ * space is legal in `WorkingDirectory=`.
+ */
+export function renderSystemdUnit(spec) {
+    return `${[
+        "[Unit]",
+        `Description=ghostrail factory (${spec.name})`,
+        "Documentation=https://github.com/timothyjordan/ghostrail",
+        "",
+        "[Service]",
+        "Type=simple",
+        `WorkingDirectory=${spec.path}`,
+        // Absolute: a bare `ghostrail` is not on a service manager's PATH, and on
+        // an nvm install the real path is version-specific.
+        `ExecStart=${spec.exec} watch --interval ${spec.interval}`,
+        "Restart=on-failure",
+        "RestartSec=30",
+        // Long enough for an in-flight tick to finish. See stopTimeoutSeconds.
+        `TimeoutStopSec=${spec.stopTimeoutSec}`,
+        "",
+        "[Install]",
+        "WantedBy=default.target",
+    ].join("\n")}\n`;
+}
+/**
+ * Parse `systemctl --user show --property=Id --property=ActiveState` for
+ * several units into unit name -> active state.
+ *
+ * Tolerates what the real command emits: records separated by blank lines,
+ * properties in any order, extra properties, and a unit that does not exist
+ * (reported as `inactive` rather than as a failure). A record with no `Id` is
+ * skipped rather than fatal.
+ */
+export function parseUnitStates(stdout) {
+    const states = new Map();
+    for (const record of stdout.split(/\n\s*\n/)) {
+        let id;
+        let active;
+        for (const line of record.split("\n")) {
+            const eq = line.indexOf("=");
+            if (eq === -1)
+                continue;
+            const key = line.slice(0, eq).trim();
+            const value = line.slice(eq + 1).trim();
+            if (key === "Id")
+                id = value;
+            else if (key === "ActiveState")
+                active = value;
+        }
+        // A record carrying an Id but no ActiveState becomes "unknown" rather than
+        // being dropped: the unit exists, and saying so beats pretending it does
+        // not. A repeated Id keeps the last record, matching how systemd's own
+        // later output would supersede earlier output.
+        if (id !== undefined && id.length > 0)
+            states.set(id, active ?? "unknown");
+    }
+    return states;
+}
+/** The unit that runs the cross-ghostrail dashboard. Only ever one. */
+export const DASHBOARD_UNIT = "ghostrail-dashboard.service";
+/**
+ * The dashboard's unit. Unlike a ghostrail's, it has no `WorkingDirectory`
+ * tied to a repo: it serves all of them and reads the registry from the global
+ * config dir.
+ *
+ * Its stop timeout is short on purpose. A ghostrail needs minutes because an
+ * in-flight tick is not interrupted; an HTTP server has nothing to protect.
+ */
+export function renderDashboardUnit(exec, port, bind) {
+    return `${[
+        "[Unit]",
+        "Description=ghostrail dashboard (all ghostrails)",
+        "Documentation=https://github.com/timothyjordan/ghostrail",
+        "",
+        "[Service]",
+        "Type=simple",
+        `ExecStart=${exec} dashboard --port ${port} --bind ${bind}`,
+        "Restart=on-failure",
+        "RestartSec=10",
+        "TimeoutStopSec=30",
+        "",
+        "[Install]",
+        "WantedBy=default.target",
+    ].join("\n")}\n`;
+}
+//# sourceMappingURL=unit.js.map

package/dist/service/unit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit.js","sourceRoot":"","sources":["../../src/service/unit.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghostrail",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Open source software factory for coding agents. Config-driven loops, pluggable isolation backends, human merge gate.",
   "keywords": [
     "ai-agents",