@tpsdev-ai/flair 0.29.0 → 0.31.0

package/dist/lib/scheduler-platform.js

@@ -0,0 +1,128 @@
+/**
+ * Platform-scheduler primitives shared by every Flair-managed background job.
+ *
+ * Two modules install user-session scheduler entries today:
+ *   - src/rem/scheduler.ts        (`flair rem nightly enable`)
+ *   - src/federation/scheduler.ts (`flair federation sync enable`)
+ *
+ * They differ in what they schedule and how often; they do NOT differ in how
+ * you ask launchd/systemd whether a job is really loaded, how you read the
+ * answer, or how you render a template into a unit file. This module exists so
+ * there is exactly ONE implementation of those — same reason src/lib/xml-escape.ts
+ * exists (#918): the second copy of a subtle rule is where it goes wrong.
+ *
+ * `interpretActiveResult()` in particular encodes a production lesson
+ * (flair#850) that took a real outage to learn. It must not be re-derived.
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { platform } from "node:os";
+import { spawnSync } from "node:child_process";
+/**
+ * 30s ceiling on launchctl/systemctl invocations so a hung service manager
+ * can't block the CLI indefinitely. Sherlock #415 follow-up.
+ */
+export const SPAWN_TIMEOUT_MS = 30_000;
+/**
+ * Status-check spawns (launchctl print / systemctl is-active) return
+ * near-instantly when the service manager is reachable, and fail fast (no
+ * hang) when it isn't (e.g. "Failed to connect to bus"). A short ceiling
+ * keeps status commands and the Health endpoint responsive even when the
+ * query is inconclusive.
+ */
+export const STATUS_CHECK_TIMEOUT_MS = 5_000;
+export function detectPlatform(label, override) {
+    if (override)
+        return override;
+    const p = platform();
+    if (p === "darwin")
+        return "darwin";
+    if (p === "linux")
+        return "linux";
+    throw new Error(`unsupported platform for ${label}: ${p} (only darwin and linux)`);
+}
+export function spawnReport(cmd, timeoutMs = SPAWN_TIMEOUT_MS) {
+    const r = spawnSync(cmd[0], cmd.slice(1), {
+        encoding: "buffer",
+        timeout: timeoutMs,
+    });
+    return {
+        code: r.status,
+        stdout: r.stdout?.toString("utf-8") ?? "",
+        stderr: r.stderr?.toString("utf-8") ?? "",
+    };
+}
+/**
+ * Interprets the result of a `launchctl print` / `systemctl --user is-active`
+ * probe. Shared by the sync (CLI) and async (server) callers of both
+ * schedulers.
+ *
+ * - true  — the service manager confirms the job is loaded/active.
+ * - false — confirmed NOT active. This includes the "no session bus" case
+ *   (flair#850): when `systemctl --user` can't reach a bus, it fails
+ *   before printing a status word ("Failed to connect to bus: No medium
+ *   found") — but nothing CAN be running without a bus, so `false` is the
+ *   honest answer, not "unknown".
+ * - null  — genuinely inconclusive (the command itself couldn't run at
+ *   all — e.g. the binary is missing — with no output to interpret).
+ */
+export function interpretActiveResult(plat, code, stdout, stderr) {
+    const noOutput = !stdout.trim() && !stderr.trim();
+    if (plat === "darwin") {
+        if (code === 0)
+            return true;
+        if (code === null && noOutput)
+            return null; // spawn itself failed — inconclusive
+        return false; // launchctl ran and reported not-loaded
+    }
+    const out = stdout.trim();
+    if (out === "active" || out === "activating")
+        return true;
+    if (out === "inactive" || out === "failed" || out === "unknown")
+        return false;
+    if (code === null && noOutput)
+        return null; // spawn itself failed — inconclusive
+    return false; // covers the no-bus case: empty stdout, nonzero/failed exit
+}
+/**
+ * Human remedy text for a failed scheduler-load attempt (flair#850). Covers
+ * the one root cause traced so far: a missing systemd user session bus,
+ * which blocks `systemctl --user` entirely in ssh-without-lingering,
+ * container, and CI contexts. Returns null when the failure doesn't match a
+ * known pattern — the caller already prints the raw stderr, so the operator
+ * still has something to go on.
+ *
+ * `enableCommand` is the caller's own enable invocation, named in the remedy
+ * so the operator is told to re-run the command they actually ran.
+ */
+export function describeLoadFailure(plat, loadResult, enableCommand) {
+    const stderr = loadResult.stderr || "";
+    if (plat === "linux" && /failed to connect to bus/i.test(stderr)) {
+        return ("No systemd user session bus is available in this session (common over ssh without lingering, " +
+            "in containers, or under CI). Fix: enable lingering for this user — `loginctl enable-linger <user>` " +
+            `— then re-run \`${enableCommand}\`.`);
+    }
+    return null;
+}
+/** Single-pass `{{KEY}}` substitution, with a per-value escape hook. */
+export function renderTemplateWith(text, subs, escape) {
+    return text.replace(/\{\{([A-Z_]+)\}\}/g, (_, key) => {
+        const value = subs[key];
+        if (value === undefined)
+            throw new Error(`unknown template placeholder: ${key}`);
+        return escape(String(value));
+    });
+}
+export function readTemplate(rootDir, relativePath) {
+    const full = resolve(rootDir, relativePath);
+    if (!existsSync(full)) {
+        throw new Error(`template not found: ${full}`);
+    }
+    return readFileSync(full, "utf-8");
+}
+export function writeFileWithDir(path, contents, mode = 0o600) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, contents, { mode });
+}

package/dist/lib/xml-escape.js

@@ -0,0 +1,54 @@
+/**
+ * XML entity escaping for the launchd plists this CLI generates.
+ *
+ * A launchd plist is XML, so ANY value interpolated into one has to be
+ * escaped or the document is malformed — and `launchctl load` rejects a
+ * malformed plist outright, so the service silently never registers.
+ *
+ * Two independent writers generate plists, and both go through here:
+ *   - buildLaunchdPlist() in src/cli.ts (the Harper service, `flair init`)
+ *   - renderPlistTemplate() in src/rem/scheduler.ts (`flair rem nightly enable`)
+ *
+ * This module exists so there is exactly ONE implementation to get right.
+ * Anything that interpolates into plist XML imports it rather than
+ * hand-rolling a `.replace()` chain at the call site — a local chain is how
+ * this class of bug got in (and how it stayed partial: the original one
+ * covered three of the five entities).
+ */
+/** The five XML predefined entities, in the order they must be replaced. */
+const XML_ESCAPES = [
+    // `&` MUST be first: replacing it after `<` would turn the `&` of an
+    // already-emitted `&lt;` into `&amp;lt;` and corrupt the value.
+    [/&/g, "&amp;"],
+    [/</g, "&lt;"],
+    [/>/g, "&gt;"],
+    [/"/g, "&quot;"],
+    [/'/g, "&apos;"],
+];
+/**
+ * Escape the five XML predefined entities for use inside an XML text node.
+ *
+ * Safe to apply to any string, including one with no special characters.
+ * The result round-trips exactly through unescapeXml().
+ */
+export function escapeXml(s) {
+    let out = s;
+    for (const [pattern, replacement] of XML_ESCAPES)
+        out = out.replace(pattern, replacement);
+    return out;
+}
+/**
+ * Inverse of escapeXml(), for reading a value back out of a document we wrote.
+ *
+ * `&amp;` MUST be decoded LAST, mirroring escapeXml()'s ordering: decoding it
+ * first would turn `&amp;lt;` (the escaping of a literal "&lt;") into `<`
+ * instead of back into `&lt;`.
+ */
+export function unescapeXml(s) {
+    return s
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}

package/dist/rem/scheduler.js

@@ -13,25 +13,25 @@
  * No daemon code lives here — the scheduler invokes the shim, the shim
  * invokes `flair rem nightly run-once`, the runner module does the work.
  */
-import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, rmSync } from "node:fs";
+import { existsSync, chmodSync, rmSync } from "node:fs";
 import { resolve, dirname } from "node:path";
-import { homedir, platform } from "node:os";
-import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { escapeXml } from "../lib/xml-escape.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+// Re-exported so this module's public surface is unchanged by the extraction
+// into src/lib/scheduler-platform.ts (a second scheduler — `flair federation
+// sync enable` — needs the identical launchctl/systemctl interpretation, and
+// flair#850's lesson must have exactly one implementation).
+export { interpretActiveResult };
 export const SHIM_PATH_DEFAULT = resolve(homedir(), ".flair", "bin", "flair-rem-nightly");
 export const LAUNCHD_PLIST_PATH = resolve(homedir(), "Library", "LaunchAgents", "dev.flair.rem.nightly.plist");
 export const SYSTEMD_USER_DIR = resolve(homedir(), ".config", "systemd", "user");
 export const SYSTEMD_TIMER_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.timer");
 export const SYSTEMD_SERVICE_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.service");
 function detectPlatform(override) {
-    if (override)
-        return override;
-    const p = platform();
-    if (p === "darwin")
-        return "darwin";
-    if (p === "linux")
-        return "linux";
-    throw new Error(`unsupported platform for REM nightly scheduler: ${p} (only darwin and linux)`);
+    return detectPlatformFor("REM nightly scheduler", override);
 }
 function defaultTemplateRoot() {
     // Templates live alongside dist/ in the published package and alongside
@@ -50,19 +50,30 @@ function defaultTemplateRoot() {
     throw new Error(`unable to locate templates directory (looked in: ${candidates.join(", ")})`);
 }
 export function renderTemplate(text, subs) {
-    return text.replace(/\{\{([A-Z_]+)\}\}/g, (_, key) => {
-        const value = subs[key];
-        if (value === undefined)
-            throw new Error(`unknown template placeholder: ${key}`);
-        return String(value);
-    });
+    return renderTemplateWith(text, { ...subs }, (v) => v);
+}
+/**
+ * renderTemplate() for the launchd plist template specifically: substituted
+ * values are XML-escaped.
+ *
+ * A launchd plist is XML, so a substitution carrying `&`, `<`, `>`, `"` or
+ * `'` makes it malformed and `launchctl bootstrap` rejects it — the timer
+ * silently never registers. FLAIR_URL is the realistic carrier (a URL with
+ * more than one query parameter contains `&`), but HOME and SHIM_PATH are
+ * arbitrary paths and equally capable of it. HOUR/MINUTE and AGENT_ID are
+ * validated upstream in buildSubstitutions(), but they are escaped too
+ * rather than exempted — the point of a chokepoint is that no value gets to
+ * argue it is special.
+ *
+ * Deliberately NOT folded into renderTemplate(): the same substitutions are
+ * rendered into the systemd unit files and the shell shim, where XML
+ * escaping would be corruption rather than a fix.
+ */
+export function renderPlistTemplate(text, subs) {
+    return renderTemplateWith(text, { ...subs }, escapeXml);
 }
 export function readTemplate(rootDir, relativePath) {
-    const full = resolve(rootDir, relativePath);
-    if (!existsSync(full)) {
-        throw new Error(`template not found: ${full}`);
-    }
-    return readFileSync(full, "utf-8");
+    return readTemplateFrom(rootDir, relativePath);
 }
 /**
  * Validates the hour:minute schedule. Throws on invalid input rather than
@@ -93,25 +104,157 @@ function buildSubstitutions(opts, shimPath, flairBin) {
         MINUTE_PAD: String(opts.minute).padStart(2, "0"),
     };
 }
-function writeFileWithDir(path, contents, mode = 0o600) {
-    const dir = dirname(path);
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
-    writeFileSync(path, contents, { mode });
-}
-// 30s ceiling on launchctl/systemctl invocations so a hung service manager
-// can't block the CLI indefinitely. Sherlock #415 follow-up.
-const SPAWN_TIMEOUT_MS = 30_000;
-function spawnReport(cmd) {
-    const r = spawnSync(cmd[0], cmd.slice(1), {
-        encoding: "buffer",
-        timeout: SPAWN_TIMEOUT_MS,
+/**
+ * Command to genuinely query the platform scheduler's active/loaded state
+ * for a given install (as opposed to the shape of `loadCommand`, which
+ * *installs* it). Shared by the sync and async active-state checks below so
+ * the two can't drift.
+ */
+function activeCheckCommand(plat) {
+    if (plat === "darwin") {
+        return ["launchctl", "print", `gui/${process.getuid?.() ?? ""}/dev.flair.rem.nightly`];
+    }
+    return ["systemctl", "--user", "is-active", "flair-rem-nightly.timer"];
+}
+/**
+ * Synchronous active-state check for CLI use (`flair rem nightly status`).
+ * Blocking is fine here — this is a one-shot process and the caller wants
+ * the answer before printing anything.
+ */
+function queryActiveState(plat) {
+    const [cmd, ...args] = activeCheckCommand(plat);
+    const r = spawnReport([cmd, ...args], STATUS_CHECK_TIMEOUT_MS);
+    return interpretActiveResult(plat, r.code, r.stdout, r.stderr);
+}
+/**
+ * Async, non-blocking equivalent for server contexts (the Health endpoint)
+ * where a synchronous subprocess would stall the request-handling thread.
+ * Same semantics as `queryActiveState()`.
+ */
+export async function queryActiveStateAsync(plat, timeoutMs = STATUS_CHECK_TIMEOUT_MS) {
+    const [cmd, ...args] = activeCheckCommand(plat);
+    return new Promise((resolvePromise) => {
+        let settled = false;
+        let child;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolvePromise(result);
+        };
+        const timer = setTimeout(() => {
+            try {
+                child?.kill("SIGKILL");
+            }
+            catch { /* best-effort */ }
+            finish(null);
+        }, timeoutMs);
+        try {
+            child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch {
+            finish(null);
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (d) => { stdout += d.toString("utf-8"); });
+        child.stderr?.on("data", (d) => { stderr += d.toString("utf-8"); });
+        child.on("error", () => finish(null));
+        child.on("close", (code) => finish(interpretActiveResult(plat, code, stdout, stderr)));
     });
-    return {
-        code: r.status,
-        stdout: r.stdout?.toString("utf-8") ?? "",
-        stderr: r.stderr?.toString("utf-8") ?? "",
-    };
+}
+/**
+ * Human remedy text for a failed scheduler-load attempt (flair#850). Covers
+ * the one root cause traced so far: a missing systemd user session bus,
+ * which blocks `systemctl --user` entirely in ssh-without-lingering,
+ * container, and CI contexts. Returns null when the failure doesn't match a
+ * known pattern — the caller already prints the raw stderr, so the operator
+ * still has something to go on.
+ */
+export function describeLoadFailure(plat, loadResult) {
+    return describeLoadFailureFor(plat, loadResult, "flair rem nightly enable");
+}
+/**
+ * Formats the `flair rem nightly enable` report from an `EnableResult`.
+ * Pulled out of the CLI action so the success-vs-failure decision (flair#850:
+ * do not print a success headline before activation is known to have
+ * succeeded) is unit-testable without spawning a real launchctl/systemctl or
+ * parsing CLI argv.
+ *
+ * `r.loadResult` is only set when the load command actually ran (the CLI
+ * never sets `skipLoad`). A missing `loadResult` (test-only path) is treated
+ * as success — matches the CLI's real-world behavior, which always runs the
+ * load command and therefore always gets a `loadResult`.
+ */
+export function formatEnableReport(r, input) {
+    const { hour, minute, agentId, flairUrl } = input;
+    const scheduleTime = `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
+    const activationFailed = !!r.loadResult && r.loadResult.code !== 0;
+    if (activationFailed) {
+        const lr = r.loadResult;
+        const lines = [
+            `⚠️  REM nightly scheduler files written but NOT activated (${r.platform})`,
+            `   Schedule:    ${scheduleTime} local time — NOT scheduled (see below)`,
+            `   Scheduler:   ${r.schedulerPath}`,
+            `   Shim:        ${r.shimPath}`,
+            `   Agent:       ${agentId}`,
+            `   Flair URL:   ${flairUrl}`,
+            `   Activation:  ${r.loadCommand.join(" ")} → code ${lr.code}`,
+        ];
+        if (lr.stderr)
+            lines.push(`     stderr: ${lr.stderr.trim()}`);
+        const remedy = describeLoadFailure(r.platform, lr);
+        lines.push("");
+        lines.push(remedy ? `   ${remedy}` : `   Re-run the activation command above manually to see the full diagnostic.`);
+        lines.push("");
+        lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair rem nightly status`);
+        return { lines, ok: false };
+    }
+    const lines = [
+        `✅ REM nightly scheduler enabled (${r.platform})`,
+        `   Schedule:    ${scheduleTime} local time`,
+        `   Scheduler:   ${r.schedulerPath}`,
+        `   Shim:        ${r.shimPath}`,
+        `   Agent:       ${agentId}`,
+        `   Flair URL:   ${flairUrl}`,
+    ];
+    if (r.loadResult) {
+        lines.push(`   Load:        ${r.loadCommand.join(" ")} → ok`);
+    }
+    lines.push("");
+    lines.push(`Tip: run \`flair rem nightly run-once --dry-run\` to verify the cycle works`);
+    lines.push(`     before the first scheduled fire. Disable with \`flair rem nightly disable\`.`);
+    return { lines, ok: true };
+}
+/**
+ * Formats the `flair rem nightly status` report from a `SchedulerStatus`.
+ * Extracted for the same testability reason as `formatEnableReport()`
+ * (flair#850): status must report genuine active state, not file presence.
+ */
+export function formatStatusReport(s) {
+    const activeTxt = s.active === true ? "yes" : s.active === false ? "no" : "unknown";
+    const lines = [
+        `REM nightly scheduler (${s.platform}):`,
+        `  Active:      ${activeTxt}`,
+        `  Installed:   ${s.installed ? "yes" : "no"}`,
+        `  Scheduler:   ${s.schedulerPath}`,
+        `  Shim:        ${s.shimPath}${s.shimExists ? "" : " (missing)"}`,
+    ];
+    if (!s.installed) {
+        lines.push("");
+        lines.push(`Enable with: flair rem nightly enable --agent <id> [--at HH:MM]`);
+    }
+    else if (s.active === false) {
+        lines.push("");
+        lines.push(`Files are written but nothing is scheduled — the job is not loaded/active.`);
+        lines.push(`Re-run: flair rem nightly enable --agent <id> [--at HH:MM]`);
+    }
+    // Status is informational — it does not itself signal process failure,
+    // consistent with the pre-existing "not installed" case never exiting
+    // nonzero. `ok` here only reflects whether the headline claims success.
+    return { lines, ok: s.active !== false };
 }
 /**
  * Installs the platform-native scheduler entry and the shim script.
@@ -135,7 +278,7 @@ export function enableScheduler(opts) {
     // 2. Write the scheduler entry.
     if (plat === "darwin") {
         const plistPath = opts.launchdPlistOverride ?? LAUNCHD_PLIST_PATH;
-        const plistContents = renderTemplate(readTemplate(templateRoot, "launchd/dev.flair.rem.nightly.plist.tmpl"), subs);
+        const plistContents = renderPlistTemplate(readTemplate(templateRoot, "launchd/dev.flair.rem.nightly.plist.tmpl"), subs);
         writeFileWithDir(plistPath, plistContents, 0o600);
         const loadCommand = ["launchctl", "bootstrap", `gui/${process.getuid?.() ?? ""}`, plistPath];
         let loadResult;
@@ -215,26 +358,40 @@ export function disableScheduler(opts = {}) {
     return { platform: plat, removed, unloadCommand, unloadResult };
 }
 /**
- * Reports whether the scheduler is installed. Filesystem-only — does not
- * shell out to launchctl/systemctl to query active state. The Health
- * endpoint already does that via existence checks; same approach here.
+ * Reports whether the scheduler is installed AND whether it is genuinely
+ * active. File presence alone proves the templates were written — it does
+ * NOT prove `launchctl`/`systemctl` successfully loaded the job (flair#850).
  */
 export function schedulerStatus(opts = {}) {
     const plat = detectPlatform(opts.platformOverride);
+    const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+    let schedulerPath;
+    let installed;
     if (plat === "darwin") {
-        return {
-            platform: plat,
-            installed: existsSync(LAUNCHD_PLIST_PATH),
-            schedulerPath: LAUNCHD_PLIST_PATH,
-            shimPath: SHIM_PATH_DEFAULT,
-            shimExists: existsSync(SHIM_PATH_DEFAULT),
-        };
+        schedulerPath = opts.launchdPlistOverride ?? LAUNCHD_PLIST_PATH;
+        installed = existsSync(schedulerPath);
+    }
+    else {
+        schedulerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
+        const servicePath = opts.systemdServiceOverride ?? SYSTEMD_SERVICE_PATH;
+        installed = existsSync(schedulerPath) && existsSync(servicePath);
+    }
+    let active;
+    if (!installed) {
+        active = false; // nothing written — definitely nothing active
+    }
+    else if (opts.skipActiveCheck) {
+        active = null; // caller opted out — unknown, not a claim either way
+    }
+    else {
+        active = queryActiveState(plat);
     }
     return {
         platform: plat,
-        installed: existsSync(SYSTEMD_TIMER_PATH) && existsSync(SYSTEMD_SERVICE_PATH),
-        schedulerPath: SYSTEMD_TIMER_PATH,
-        shimPath: SHIM_PATH_DEFAULT,
-        shimExists: existsSync(SHIM_PATH_DEFAULT),
+        installed,
+        active,
+        schedulerPath,
+        shimPath,
+        shimExists: existsSync(shimPath),
     };
 }

package/dist/rem/snapshot.js

@@ -134,6 +134,19 @@ export async function extractSnapshot(opts) {
         throw new Error(`target directory already exists: ${targetDir}`);
     }
     mkdirSync(targetDir, { recursive: true, mode: 0o700 });
+    // Deliberately NOT preservePaths, and deliberately NOT routed through
+    // src/lib/safe-snapshot-extract.ts. The snapshot path comes from the
+    // operator, so provenance here is no more controlled than the data-dir
+    // restore's — the difference is the flag, not the trust. With node-tar's
+    // defaults its own containment applies: it strips a leading "/" from entry
+    // paths, drops ".." entries, and refuses to write through a symlink,
+    // including one created earlier in the same archive. Verified against the
+    // pinned tar (7.5.20) on all four cases — absolute path, ".." traversal,
+    // in-archive symlink, pre-existing symlink in the target — each contained,
+    // with a benign control entry landing to prove the archives were valid.
+    // If `preservePaths` is ever added here, that containment is gone and this
+    // call MUST move to extractSnapshotSafely, which is why the data-dir
+    // restore needs the wrapper and this does not.
     await tarExtract({ file: opts.snapshotPath, cwd: targetDir });
     return { targetDir, entries };
 }