@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/fleet/fleet-scheduler.js

@@ -0,0 +1,186 @@
+/**
+ * Fleet scheduler backends.
+ *
+ * A loop's cadence, paused state, and dry-run/live mode do not live in paseo: they live
+ * in whatever schedules the loop's runner on that host. Two backends exist because the
+ * two hosts this fleet runs on disagree:
+ *
+ *   - `systemd-user`: `~/.config/systemd/user/<loop>.{service,timer}` (Linux / WSL2).
+ *     Cadence is the timer's `OnCalendar`; enabled state is the presence of the
+ *     `timers.target.wants/<loop>.timer` symlink; mode is the `--live` / `--dry-run`
+ *     flag inside the service unit's `ExecStart`.
+ *   - `crontab`: one line per loop in the user crontab. Cadence is the 5 leading fields,
+ *     paused is a `#PASEO-PAUSED#` prefix, mode is the same flag on the command.
+ *
+ * Reading is pure over file contents so it can be tested without a scheduler. Writing is
+ * conservative: back up first, touch only the one unit/line that matches the loop, and
+ * report whether anything actually changed.
+ *
+ * Mode is parsed from the EXECUTED command, never from a unit Description. Real units on
+ * this host carry `Description=stage-gc loop (dry-run)` while running `--live`; trusting
+ * the description would report the opposite of what the loop does.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/** Prefix written in front of a cron line to pause it without deleting it. */
+export const PAUSE_MARKER = "#PASEO-PAUSED#";
+const MODE_FLAG_RE = /--(live|dry-run)\b/;
+/** Mode of a command string, from its `--live` / `--dry-run` flag. */
+export function parseModeFromCommand(command) {
+    const match = MODE_FLAG_RE.exec(command);
+    if (!match) {
+        return "unknown";
+    }
+    return match[1] === "live" ? "live" : "dry-run";
+}
+/**
+ * Rewrite a command's mode flag, inserting one right after the runner path when the
+ * command carries none. Appending at the end would land after the shell redirect
+ * (`>> log 2>&1`), where the runner would never see it.
+ */
+export function applyModeToCommand(command, mode, runnerRe) {
+    const flag = mode === "live" ? "--live" : "--dry-run";
+    if (MODE_FLAG_RE.test(command)) {
+        return command.replace(MODE_FLAG_RE, flag);
+    }
+    const match = runnerRe.exec(command);
+    if (!match) {
+        return command;
+    }
+    const insertAt = match.index + match[0].length;
+    return `${command.slice(0, insertAt)} ${flag}${command.slice(insertAt)}`;
+}
+/** Matches the loop's runner path so we only ever touch that loop's own command. */
+export function loopRunnerRegExp(name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // Mirrors LOOP_RUNNER_FILENAMES in fleet-reader: .sh, -poll.sh, and node (.mjs) loops.
+    return new RegExp(`tooling/(?:loops/)?${escaped}/run(?:-poll)?\\.(?:sh|mjs)`);
+}
+function firstDirective(unitText, key) {
+    const re = new RegExp(`^\\s*${key}\\s*=\\s*(.+)$`, "m");
+    const match = re.exec(unitText);
+    return match ? match[1].trim() : null;
+}
+/** All `ExecStart=` values in a service unit (a unit may declare several). */
+export function readExecStart(serviceText) {
+    return firstDirective(serviceText, "ExecStart");
+}
+/** Cadence of a timer unit: `OnCalendar`, falling back to the monotonic variants. */
+export function readTimerCadence(timerText) {
+    return (firstDirective(timerText, "OnCalendar") ??
+        firstDirective(timerText, "OnUnitActiveSec") ??
+        firstDirective(timerText, "OnBootSec") ??
+        undefined);
+}
+/** Derive a loop's schedule from its systemd unit texts. Pure, so it is testable. */
+export function scheduleFromSystemdUnits(units) {
+    if (!units.timerText && !units.serviceText) {
+        return { scheduled: false, paused: false, mode: "unknown" };
+    }
+    const execStart = units.serviceText ? readExecStart(units.serviceText) : null;
+    return {
+        scheduled: units.timerText !== null,
+        // A timer unit that exists but is not linked into timers.target.wants is off.
+        paused: units.timerText !== null && !units.enabled,
+        cadence: units.timerText ? readTimerCadence(units.timerText) : undefined,
+        mode: execStart ? parseModeFromCommand(execStart) : "unknown",
+    };
+}
+function readIfPresent(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function symlinkExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export class SystemdUserScheduler {
+    constructor(config) {
+        this.kind = "systemd-user";
+        this.config = { ...config, unitDir: config.unitDir, backupDir: config.backupDir };
+    }
+    /** True when this host actually schedules anything through systemd --user. */
+    static isAvailable(unitDir) {
+        return existsSync(unitDir);
+    }
+    servicePath(name) {
+        return join(this.config.unitDir, `${name}.service`);
+    }
+    timerPath(name) {
+        return join(this.config.unitDir, `${name}.timer`);
+    }
+    wantsPath(name) {
+        return join(this.config.unitDir, "timers.target.wants", `${name}.timer`);
+    }
+    readUnits(name) {
+        return {
+            serviceText: readIfPresent(this.servicePath(name)),
+            timerText: readIfPresent(this.timerPath(name)),
+            enabled: symlinkExists(this.wantsPath(name)),
+        };
+    }
+    read(name) {
+        return scheduleFromSystemdUnits(this.readUnits(name));
+    }
+    backup(name, contents, suffix) {
+        const now = this.config.now?.() ?? Date.now();
+        const dir = join(this.config.backupDir, "unit-backups");
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `${now}.${name}.${suffix}`);
+        writeFileSync(path, contents, "utf8");
+        return path;
+    }
+    /**
+     * Flip a loop between dry-run and live by rewriting the flag in its service unit,
+     * then reloading systemd so the next timer firing uses it. The unit is backed up
+     * first and only the `ExecStart` flag changes.
+     */
+    setMode(name, mode) {
+        const servicePath = this.servicePath(name);
+        const serviceText = readIfPresent(servicePath);
+        if (serviceText === null) {
+            throw new Error(`No systemd service unit for loop "${name}" (${servicePath})`);
+        }
+        const execStart = readExecStart(serviceText);
+        if (execStart === null) {
+            throw new Error(`Service unit for loop "${name}" has no ExecStart`);
+        }
+        const previousMode = parseModeFromCommand(execStart);
+        const nextExecStart = applyModeToCommand(execStart, mode, loopRunnerRegExp(name));
+        if (nextExecStart === execStart) {
+            return { changed: false, previousMode, mode: previousMode };
+        }
+        const backupPath = this.backup(name, serviceText, "service");
+        // Replace only the ExecStart line, leaving every other directive byte-for-byte.
+        const nextText = serviceText.replace(/^(\s*ExecStart\s*=\s*)(.+)$/m, (_full, prefix) => `${prefix}${nextExecStart}`);
+        writeFileSync(servicePath, nextText, "utf8");
+        this.config.systemctl?.(["daemon-reload"]);
+        return { changed: true, previousMode, mode, backupPath };
+    }
+    setPaused(name, paused) {
+        const units = this.readUnits(name);
+        if (units.timerText === null) {
+            throw new Error(`No systemd timer unit for loop "${name}"`);
+        }
+        if (units.enabled === !paused) {
+            return { changed: false };
+        }
+        const timerUnit = `${name}.timer`;
+        this.config.systemctl?.(paused ? ["disable", "--now", timerUnit] : ["enable", "--now", timerUnit]);
+        return { changed: true };
+    }
+}
+export function defaultSystemdUnitDir() {
+    return process.env.PASEO_FLEET_UNIT_DIR ?? join(homedir(), ".config", "systemd", "user");
+}
+//# sourceMappingURL=fleet-scheduler.js.map

package/dist/server/server/fleet/fleet-service.d.ts

@@ -0,0 +1,75 @@
+import { type FleetLoop, type FleetReaderConfig } from "./fleet-reader.js";
+import { LoopDecisionService } from "./decision-service.js";
+import type { CreateLoopDecisionInput, LoopDecision, LoopDecisionResolver } from "@hyperdrive.bot/fleet-protocol/fleet/decisions";
+import type { LoopParamValues } from "@hyperdrive.bot/fleet-protocol/fleet/params";
+import type { SetModeResult } from "./fleet-scheduler.js";
+import { type CreateLoopSpec } from "./fleet-scaffold.js";
+import type { FleetLoopSummary, StoredFleetLoop } from "@hyperdrive.bot/fleet-protocol/fleet/types";
+export interface FleetServiceOptions {
+    loopsDir?: string;
+    stateDir?: string;
+    paseoHome?: string;
+    /** Injectable for tests; defaults to the real fleet reader. */
+    read?: (config: FleetReaderConfig) => FleetLoop[];
+}
+/**
+ * View over the super-repo loop fleet. Unlike ScheduleService, the daemon does NOT own
+ * these loops: they run as their own runners, scheduled by systemd --user timers or the
+ * user crontab depending on the host. This service reads their state on demand (cheap: a
+ * handful of small files) and maps it to the `fleet` protocol shape. Writes are limited
+ * to run-now, pause/resume, and the dry-run/live promotion.
+ */
+export declare class FleetService {
+    private readonly config;
+    private readonly read;
+    private readonly paseoHome;
+    /** Decisions a loop is asking a human. Owned here so the RPC layer stays thin. */
+    readonly decisions: LoopDecisionService;
+    constructor(options?: FleetServiceOptions);
+    list(): FleetLoopSummary[];
+    inspect(name: string): StoredFleetLoop | null;
+    /** Trigger a one-off run of the loop. Defaults to a safe dry-run preview. */
+    runNow(name: string, live?: boolean): {
+        loop: StoredFleetLoop | null;
+        started: boolean;
+    };
+    pause(name: string): FleetLoopSummary | null;
+    resume(name: string): FleetLoopSummary | null;
+    private setPaused;
+    /**
+     * Move a loop between dry-run and live.
+     *
+     * Asymmetric by design, and the asymmetry lives in the UI, not here: demoting to
+     * dry-run is a brake and is always one tap, while promoting to live is offered only
+     * once the loop has real evidence behind it (a gate that returned rows, clean dry
+     * ticks, one supervised live item). The service still performs whatever the caller
+     * asks so an explicit, logged override is never blocked by the transport.
+     */
+    setMode(name: string, mode: "live" | "dry-run"): {
+        loop: FleetLoopSummary | null;
+        result: SetModeResult | null;
+    };
+    /**
+     * Persist a loop's parameters.
+     *
+     * Refuses when the loop declares no schema: without a declaration there is nothing to
+     * validate against, and writing arbitrary keys would hand the runner values it has no
+     * contract for.
+     */
+    setParams(name: string, values: LoopParamValues): {
+        loop: StoredFleetLoop | null;
+        path: string | null;
+    };
+    listDecisions(loopName?: string, includeResolved?: boolean): LoopDecision[];
+    createDecision(input: CreateLoopDecisionInput): LoopDecision;
+    resolveDecision(id: string, optionId: string, by: LoopDecisionResolver): LoopDecision;
+    /**
+     * Scaffold a new loop (the in-app `/new-loop`). Writes the loop dir under
+     * tooling/loops and returns the cron line to install; does not touch crontab.
+     */
+    create(spec: CreateLoopSpec): {
+        loop: StoredFleetLoop | null;
+        cronLine: string;
+    };
+}
+//# sourceMappingURL=fleet-service.d.ts.map

package/dist/server/server/fleet/fleet-service.js

@@ -0,0 +1,134 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { defaultFleetReaderConfig, readFleet, } from "./fleet-reader.js";
+import { runLoopNow, setLoopMode, setLoopPausedForHost, writeLoopParams, } from "./fleet-controls.js";
+import { LoopDecisionService } from "./decision-service.js";
+import { createLoopScaffold } from "./fleet-scaffold.js";
+/**
+ * View over the super-repo loop fleet. Unlike ScheduleService, the daemon does NOT own
+ * these loops: they run as their own runners, scheduled by systemd --user timers or the
+ * user crontab depending on the host. This service reads their state on demand (cheap: a
+ * handful of small files) and maps it to the `fleet` protocol shape. Writes are limited
+ * to run-now, pause/resume, and the dry-run/live promotion.
+ */
+export class FleetService {
+    constructor(options = {}) {
+        const base = defaultFleetReaderConfig();
+        this.config = {
+            loopsDir: options.loopsDir ?? base.loopsDir,
+            stateDir: options.stateDir ?? base.stateDir,
+        };
+        this.read = options.read ?? readFleet;
+        this.paseoHome = options.paseoHome ?? process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+        this.decisions = new LoopDecisionService({ paseoHome: this.paseoHome });
+    }
+    list() {
+        return this.read(this.config).map(toSummary);
+    }
+    inspect(name) {
+        const loop = this.read(this.config).find((entry) => entry.name === name);
+        return loop ? toStored(loop) : null;
+    }
+    /** Trigger a one-off run of the loop. Defaults to a safe dry-run preview. */
+    runNow(name, live = false) {
+        const loop = this.read(this.config).find((entry) => entry.name === name);
+        if (!loop)
+            return { loop: null, started: false };
+        const result = runLoopNow({
+            name: loop.name,
+            dir: loop.dir,
+            stateDir: this.config.stateDir,
+            live,
+            now: Date.now(),
+        });
+        return { loop: toStored(loop), started: result.started };
+    }
+    pause(name) {
+        return this.setPaused(name, true);
+    }
+    resume(name) {
+        return this.setPaused(name, false);
+    }
+    setPaused(name, paused) {
+        const exists = this.read(this.config).some((entry) => entry.name === name);
+        if (!exists)
+            return null;
+        setLoopPausedForHost(name, paused, { paseoHome: this.paseoHome });
+        const updated = this.read(this.config).find((entry) => entry.name === name);
+        return updated ? toSummary(updated) : null;
+    }
+    /**
+     * Move a loop between dry-run and live.
+     *
+     * Asymmetric by design, and the asymmetry lives in the UI, not here: demoting to
+     * dry-run is a brake and is always one tap, while promoting to live is offered only
+     * once the loop has real evidence behind it (a gate that returned rows, clean dry
+     * ticks, one supervised live item). The service still performs whatever the caller
+     * asks so an explicit, logged override is never blocked by the transport.
+     */
+    setMode(name, mode) {
+        const exists = this.read(this.config).some((entry) => entry.name === name);
+        if (!exists)
+            return { loop: null, result: null };
+        const result = setLoopMode(name, mode, { paseoHome: this.paseoHome });
+        const updated = this.read(this.config).find((entry) => entry.name === name);
+        return { loop: updated ? toSummary(updated) : null, result };
+    }
+    /**
+     * Persist a loop's parameters.
+     *
+     * Refuses when the loop declares no schema: without a declaration there is nothing to
+     * validate against, and writing arbitrary keys would hand the runner values it has no
+     * contract for.
+     */
+    setParams(name, values) {
+        const loop = this.read(this.config).find((entry) => entry.name === name);
+        if (!loop)
+            return { loop: null, path: null };
+        if (!loop.paramsSchema) {
+            throw new Error(`Loop "${name}" declares no parameters (no params.schema.json)`);
+        }
+        const result = writeLoopParams({
+            dir: loop.dir,
+            schema: loop.paramsSchema,
+            values,
+            paseoHome: this.paseoHome,
+        });
+        const updated = this.read(this.config).find((entry) => entry.name === name);
+        return { loop: updated ? toStored(updated) : null, path: result.path };
+    }
+    listDecisions(loopName, includeResolved = false) {
+        return this.decisions.list({ loopName, includeResolved });
+    }
+    createDecision(input) {
+        return this.decisions.create(input);
+    }
+    resolveDecision(id, optionId, by) {
+        return this.decisions.resolve(id, optionId, by);
+    }
+    /**
+     * Scaffold a new loop (the in-app `/new-loop`). Writes the loop dir under
+     * tooling/loops and returns the cron line to install; does not touch crontab.
+     */
+    create(spec) {
+        const superRepoRoot = process.env.PASEO_SUPERREPO ?? join(homedir(), "super-repo");
+        const result = createLoopScaffold({
+            loopsDir: this.config.loopsDir,
+            superRepoRoot,
+            spec,
+        });
+        const created = this.read(this.config).find((entry) => entry.name === spec.name.trim());
+        return {
+            loop: created ? toStored(created) : null,
+            cronLine: result.cronLine,
+        };
+    }
+}
+function toStored(loop) {
+    return { ...loop, findingCount: loop.openFindings.length };
+}
+function toSummary(loop) {
+    const { openFindings, recentRuns: _recentRuns, errorTail: _errorTail, ...rest } = loop;
+    return { ...rest, findingCount: openFindings.length };
+}
+//# sourceMappingURL=fleet-service.js.map

package/dist/server/server/hostnames.d.ts

@@ -0,0 +1,13 @@
+export type HostnamesConfig = true | string[] | undefined;
+/**
+ * Vite-style hostname allowlist check, adapted to raw Host headers.
+ *
+ * Semantics:
+ * - `hostnames === true` => allow any host.
+ * - `hostnames === []` or `undefined` => allow localhost, *.localhost, and all IPs.
+ * - `hostnames === ['.example.com', 'myhost']` => allow those *in addition* to defaults.
+ */
+export declare function isHostnameAllowed(hostHeader: string | undefined, hostnames: HostnamesConfig): boolean;
+export declare function mergeHostnames(values: Array<HostnamesConfig>): HostnamesConfig;
+export declare function parseHostnamesEnv(raw: string | undefined): HostnamesConfig;
+//# sourceMappingURL=hostnames.d.ts.map

package/dist/server/server/hostnames.js

@@ -0,0 +1,94 @@
+import net from "node:net";
+function normalizeHostname(hostname) {
+    return hostname.trim().toLowerCase();
+}
+function parseHostnameFromHostHeader(hostHeader) {
+    const trimmed = hostHeader.trim();
+    if (!trimmed)
+        return null;
+    // IPv6 in brackets: [::1]:6767
+    if (trimmed.startsWith("[")) {
+        const end = trimmed.indexOf("]");
+        if (end === -1)
+            return null;
+        return normalizeHostname(trimmed.slice(1, end));
+    }
+    // IPv4/hostname with optional port: localhost:6767
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex === -1) {
+        return normalizeHostname(trimmed);
+    }
+    return normalizeHostname(trimmed.slice(0, colonIndex));
+}
+function matchesHostnamePattern(hostname, pattern) {
+    const normalizedPattern = normalizeHostname(pattern);
+    if (!normalizedPattern)
+        return false;
+    if (normalizedPattern.startsWith(".")) {
+        const base = normalizedPattern.slice(1);
+        if (!base)
+            return false;
+        return hostname === base || hostname.endsWith(`.${base}`);
+    }
+    return hostname === normalizedPattern;
+}
+function isDefaultAllowedHostname(hostname) {
+    // Vite-style defaults: localhost, *.localhost, and all IP addresses.
+    if (hostname === "localhost")
+        return true;
+    if (hostname.endsWith(".localhost"))
+        return true;
+    if (net.isIP(hostname) !== 0)
+        return true;
+    return false;
+}
+/**
+ * Vite-style hostname allowlist check, adapted to raw Host headers.
+ *
+ * Semantics:
+ * - `hostnames === true` => allow any host.
+ * - `hostnames === []` or `undefined` => allow localhost, *.localhost, and all IPs.
+ * - `hostnames === ['.example.com', 'myhost']` => allow those *in addition* to defaults.
+ */
+export function isHostnameAllowed(hostHeader, hostnames) {
+    const hostname = hostHeader ? parseHostnameFromHostHeader(hostHeader) : null;
+    if (!hostname)
+        return false;
+    if (hostnames === true)
+        return true;
+    // Defaults are always allowed.
+    if (isDefaultAllowedHostname(hostname))
+        return true;
+    const patterns = hostnames ?? [];
+    for (const pattern of patterns) {
+        if (matchesHostnamePattern(hostname, pattern))
+            return true;
+    }
+    return false;
+}
+export function mergeHostnames(values) {
+    let merged = [];
+    for (const value of values) {
+        if (value === true)
+            return true;
+        if (!value)
+            continue;
+        merged = merged.concat(value);
+    }
+    const deduped = Array.from(new Set(merged.map((v) => v.trim()).filter((v) => v.length > 0)));
+    return deduped;
+}
+export function parseHostnamesEnv(raw) {
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.toLowerCase() === "true")
+        return true;
+    return trimmed
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+//# sourceMappingURL=hostnames.js.map

package/dist/server/server/ingestion/adapters.d.ts

@@ -0,0 +1,21 @@
+import type { IngestionDeps, SourceGateway, SourceKind } from "./types.js";
+/**
+ * The adapter factory for every source kind.
+ *
+ * The `Record<SourceKind, ...>` annotation is the whole mechanism: a kind added
+ * to SOURCE_CAPABLE_KINDS without an entry here fails to satisfy the record and
+ * breaks the build.
+ *
+ * The obvious alternative does not work. An `as const` list plus a `switch` on
+ * the kind, with no `default` and no `never` assertion, compiles cleanly with a
+ * missing case and simply falls through at runtime. That is the silent
+ * disappearance this shape exists to prevent, so keep the annotation even
+ * though the object literal would infer a usable type without it.
+ */
+export declare const SOURCE_ADAPTERS: Record<SourceKind, (deps: IngestionDeps) => SourceGateway>;
+/**
+ * The gateway for one kind. Total by construction: SOURCE_ADAPTERS covers every
+ * SourceKind, so this never returns undefined and callers never null-check.
+ */
+export declare function resolveSourceGateway(kind: SourceKind, deps: IngestionDeps): SourceGateway;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/server/server/ingestion/adapters.js

@@ -0,0 +1,27 @@
+import { createComposioGateway } from "./composio/gateway.js";
+import { createPipedreamGateway } from "./pipedream/gateway.js";
+/**
+ * The adapter factory for every source kind.
+ *
+ * The `Record<SourceKind, ...>` annotation is the whole mechanism: a kind added
+ * to SOURCE_CAPABLE_KINDS without an entry here fails to satisfy the record and
+ * breaks the build.
+ *
+ * The obvious alternative does not work. An `as const` list plus a `switch` on
+ * the kind, with no `default` and no `never` assertion, compiles cleanly with a
+ * missing case and simply falls through at runtime. That is the silent
+ * disappearance this shape exists to prevent, so keep the annotation even
+ * though the object literal would infer a usable type without it.
+ */
+export const SOURCE_ADAPTERS = {
+    pipedream: (deps) => createPipedreamGateway(deps.config.pipedream),
+    composio: (deps) => createComposioGateway(deps.config.composio),
+};
+/**
+ * The gateway for one kind. Total by construction: SOURCE_ADAPTERS covers every
+ * SourceKind, so this never returns undefined and callers never null-check.
+ */
+export function resolveSourceGateway(kind, deps) {
+    return SOURCE_ADAPTERS[kind](deps);
+}
+//# sourceMappingURL=adapters.js.map