@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/search-index/qmd-exit-diagnostics.js

@@ -0,0 +1,40 @@
+import { QmdExitError } from "./index.js";
+const QMD_ERROR_CODE_TOKENS = [
+    "SQLITE_BUSY",
+    "SQLITE_CORRUPT",
+    "SQLITE_FULL",
+    "ENOSPC",
+    "EACCES",
+    "EPERM",
+    "ENOENT",
+    "ECONNRESET",
+    "ETIMEDOUT",
+];
+const QMD_UPDATE_ENTRY_PATHS = new Set(["index-sync"]);
+/** Bounded Sentry tags for qmd exits; never return captured streams or full argv. */
+export function qmdExitCaptureContext(err) {
+    if (!(err instanceof QmdExitError))
+        return undefined;
+    const output = err.stderr + "\n" + err.stdout;
+    const errorCode = QMD_ERROR_CODE_TOKENS.find((token) => new RegExp("(^|[^A-Za-z0-9_])" + token + "(?=$|[^A-Za-z0-9_])").test(output)) ?? "none";
+    const firstArg = err.args[0];
+    const subcommand = typeof firstArg === "string" && /^[a-z][a-z0-9_-]{0,31}$/.test(firstArg)
+        ? firstArg
+        : "unknown";
+    const exitStatus = typeof err.status === "number" && Number.isSafeInteger(err.status)
+        ? String(err.status)
+        : "unknown";
+    const tags = {
+        qmd_error_code: errorCode,
+        qmd_subcommand: subcommand,
+        qmd_exit_status: exitStatus,
+    };
+    if (typeof err.qmdVersion === "string" && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(err.qmdVersion)) {
+        tags.qmd_version = err.qmdVersion;
+    }
+    if (typeof err.entryPath === "string" && QMD_UPDATE_ENTRY_PATHS.has(err.entryPath)) {
+        tags.qmd_entry_path = err.entryPath;
+    }
+    return { tags };
+}
+//# sourceMappingURL=qmd-exit-diagnostics.js.map

package/dist/lib/search-index/reindex-single-flight-flag.d.ts

@@ -0,0 +1,5 @@
+export declare const QMD_REINDEX_SINGLE_FLIGHT_FLAG = "qmd.reindex-single-flight";
+export declare const QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK = false;
+/** Keep all HQ-managed QMD writers coordinated only for explicitly enabled canaries. */
+export declare function qmdReindexSingleFlightEnabled(): boolean;
+//# sourceMappingURL=reindex-single-flight-flag.d.ts.map

package/dist/lib/search-index/reindex-single-flight-flag.js

@@ -0,0 +1,8 @@
+import { resolveProcessFlagGate } from "../flag-registry.js";
+export const QMD_REINDEX_SINGLE_FLIGHT_FLAG = "qmd.reindex-single-flight";
+export const QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK = false;
+/** Keep all HQ-managed QMD writers coordinated only for explicitly enabled canaries. */
+export function qmdReindexSingleFlightEnabled() {
+    return resolveProcessFlagGate(QMD_REINDEX_SINGLE_FLIGHT_FLAG, { fallback: QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK }, () => QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK);
+}
+//# sourceMappingURL=reindex-single-flight-flag.js.map

package/dist/lib/service-manager/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Install / uninstall / status for a SET of user-level services, dispatching
+ * to launchd or systemd. All filesystem and process-control effects are
+ * injectable so the kit tests exercise the real rendering and dispatch
+ * without touching the host's service manager.
+ */
+import * as fs from "node:fs";
+import { type RunCommand } from "./launchd.js";
+import { type ServiceHostPaths, type ServicePlatform, type ServiceSpec } from "./types.js";
+export type { ServiceSpec, ServiceHostPaths, ServicePlatform } from "./types.js";
+export { detectServicePlatform } from "./types.js";
+export { defaultRunCommand, renderLaunchdPlist } from "./launchd.js";
+export { renderSystemdUserUnit, systemdUnitName } from "./systemd.js";
+export interface ServiceManagerDeps {
+    platform?: ServicePlatform;
+    run?: RunCommand;
+    writeFileSync?: typeof fs.writeFileSync;
+    mkdirSync?: typeof fs.mkdirSync;
+    unlinkSync?: typeof fs.unlinkSync;
+    existsSync?: typeof fs.existsSync;
+    /** When false, render + write units but do not (de)activate them. */
+    activate?: boolean;
+}
+export interface ServiceUnitResult {
+    name: string;
+    unitPath: string;
+    rendered?: string;
+    installed: boolean;
+    running?: boolean;
+    error?: string;
+}
+export interface ServiceSetResult {
+    platform: ServicePlatform;
+    units: ServiceUnitResult[];
+    /** Human hint when the platform has no service manager integration. */
+    manualCommands?: string[];
+}
+export declare function renderUnit(platform: ServicePlatform, spec: ServiceSpec, host: ServiceHostPaths): string;
+export declare function installServices(specs: ServiceSpec[], host: ServiceHostPaths, deps?: ServiceManagerDeps): ServiceSetResult;
+export declare function uninstallServices(specs: ServiceSpec[], host: ServiceHostPaths, deps?: ServiceManagerDeps): ServiceSetResult;
+export declare function servicesStatus(specs: ServiceSpec[], host: ServiceHostPaths, deps?: ServiceManagerDeps): ServiceSetResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/service-manager/index.js

@@ -0,0 +1,105 @@
+/**
+ * Install / uninstall / status for a SET of user-level services, dispatching
+ * to launchd or systemd. All filesystem and process-control effects are
+ * injectable so the kit tests exercise the real rendering and dispatch
+ * without touching the host's service manager.
+ */
+import * as fs from "node:fs";
+import { activateLaunchd, deactivateLaunchd, defaultRunCommand, launchAgentsDir, launchdIsLoaded, launchdPlistPath, renderLaunchdPlist, } from "./launchd.js";
+import { activateSystemd, deactivateSystemd, renderSystemdUserUnit, systemdIsActive, systemdUnitName, systemdUnitPath, systemdUserDir, } from "./systemd.js";
+import { detectServicePlatform, } from "./types.js";
+export { detectServicePlatform } from "./types.js";
+export { defaultRunCommand, renderLaunchdPlist } from "./launchd.js";
+export { renderSystemdUserUnit, systemdUnitName } from "./systemd.js";
+function unitPathFor(platform, home, spec) {
+    return platform === "darwin" ? launchdPlistPath(home, spec) : systemdUnitPath(home, spec);
+}
+export function renderUnit(platform, spec, host) {
+    return platform === "darwin"
+        ? renderLaunchdPlist(spec, host)
+        : renderSystemdUserUnit(spec, host);
+}
+export function installServices(specs, host, deps = {}) {
+    const platform = deps.platform ?? detectServicePlatform();
+    const run = deps.run ?? defaultRunCommand;
+    const writeFileSync = deps.writeFileSync ?? fs.writeFileSync;
+    const mkdirSync = deps.mkdirSync ?? fs.mkdirSync;
+    const activate = deps.activate ?? true;
+    if (platform === "other") {
+        return {
+            platform,
+            units: specs.map((s) => ({ name: s.name, unitPath: "", installed: false })),
+            manualCommands: specs.map((s) => `${host.nodeBinary} ${host.hqBinary} ${s.args.join(" ")}  # >> ${s.logPath}`),
+        };
+    }
+    const dir = platform === "darwin" ? launchAgentsDir(host.home) : systemdUserDir(host.home);
+    mkdirSync(dir, { recursive: true });
+    const units = [];
+    for (const spec of specs) {
+        const unitPath = unitPathFor(platform, host.home, spec);
+        const rendered = renderUnit(platform, spec, host);
+        writeFileSync(unitPath, rendered, { mode: 0o600 });
+        const unit = { name: spec.name, unitPath, rendered, installed: true };
+        if (activate) {
+            try {
+                if (platform === "darwin")
+                    activateLaunchd(unitPath, run);
+                else
+                    activateSystemd(systemdUnitName(spec), run);
+                unit.running = true;
+            }
+            catch (err) {
+                unit.running = false;
+                unit.error = err instanceof Error ? err.message : String(err);
+            }
+        }
+        units.push(unit);
+    }
+    return { platform, units };
+}
+export function uninstallServices(specs, host, deps = {}) {
+    const platform = deps.platform ?? detectServicePlatform();
+    const run = deps.run ?? defaultRunCommand;
+    const unlinkSync = deps.unlinkSync ?? fs.unlinkSync;
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    const activate = deps.activate ?? true;
+    if (platform === "other") {
+        return { platform, units: specs.map((s) => ({ name: s.name, unitPath: "", installed: false })) };
+    }
+    const units = [];
+    for (const spec of specs) {
+        const unitPath = unitPathFor(platform, host.home, spec);
+        const present = existsSync(unitPath);
+        if (present) {
+            if (activate) {
+                if (platform === "darwin")
+                    deactivateLaunchd(unitPath, run);
+                else
+                    deactivateSystemd(systemdUnitName(spec), run);
+            }
+            unlinkSync(unitPath);
+        }
+        units.push({ name: spec.name, unitPath, installed: false, running: false });
+    }
+    return { platform, units };
+}
+export function servicesStatus(specs, host, deps = {}) {
+    const platform = deps.platform ?? detectServicePlatform();
+    const run = deps.run ?? defaultRunCommand;
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    if (platform === "other") {
+        return { platform, units: specs.map((s) => ({ name: s.name, unitPath: "", installed: false })) };
+    }
+    const units = specs.map((spec) => {
+        const unitPath = unitPathFor(platform, host.home, spec);
+        const installed = existsSync(unitPath);
+        const running = installed
+            ? platform === "darwin"
+                ? launchdIsLoaded(spec.label, run)
+                : systemdIsActive(systemdUnitName(spec), run)
+            : false;
+        return { name: spec.name, unitPath, installed, running };
+    });
+    return { platform, units };
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/service-manager/launchd.d.ts

@@ -0,0 +1,81 @@
+/**
+ * macOS LaunchAgent rendering + activation for kit services.
+ *
+ * Units live at ~/Library/LaunchAgents/<label>.plist. Activation uses the
+ * modern `launchctl bootstrap gui/<uid>` form (bootout first so a re-install
+ * picks up a changed plist). Command execution is injected so tests never
+ * touch launchctl.
+ */
+import { type ServiceHostPaths, type ServiceSpec } from "./types.js";
+export declare function launchAgentsDir(home: string): string;
+export declare function launchdPlistPath(home: string, spec: Pick<ServiceSpec, "label">): string;
+export declare function renderLaunchdPlist(spec: ServiceSpec, host: ServiceHostPaths): string;
+export type RunCommand = (cmd: string, args: string[]) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+export type SleepFn = (ms: number) => void;
+/** How long to wait for a booted-out job to leave launchd before bootstrapping anyway. */
+export declare const LAUNCHD_UNLOAD_DEADLINE_MS = 10000;
+/** Interval between `launchctl print` polls while the old job unloads. */
+export declare const LAUNCHD_UNLOAD_POLL_MS = 250;
+/** Backoff before each bootstrap retry on EIO (one retry per entry). */
+export declare const LAUNCHD_BOOTSTRAP_BACKOFF_MS: readonly number[];
+/** Bootstrap attempts after bootout (first try + EIO retries). */
+export declare const LAUNCHD_BOOTSTRAP_ATTEMPTS: number;
+export declare const defaultRunCommand: RunCommand;
+export declare function launchdServiceTarget(plistPath: string, uid?: number): string;
+/** ProgramArguments from a LaunchAgent plist. */
+export declare function launchdPlistProgramArguments(plist: string): string[];
+/**
+ * Arguments of a loaded job from `launchctl print gui/<uid>/<label>`.
+ * Prefers the `arguments = { ... }` block; falls back to `program =`.
+ */
+export declare function parseLaunchctlPrintArguments(stdout: string): string[];
+export declare function launchdProgramArgumentsDiffer(loaded: string[], plist: string[]): boolean;
+/**
+ * Poll `launchctl print <target>` until the label is gone. Returns false when
+ * it is still loaded at the deadline. Elapsed time is counted in slept
+ * intervals so an injected sleep keeps tests deterministic.
+ */
+export declare function waitForLaunchdUnload(target: string, run: RunCommand, opts?: {
+    sleep?: SleepFn;
+    deadlineMs?: number;
+}): boolean;
+export interface LaunchdReloadResult {
+    /** bootstrap of the plist succeeded. */
+    ok: boolean;
+    /** The label is present in launchd after the reload (new or previous definition). */
+    loaded: boolean;
+    /** The previous job was still loaded when the unload deadline passed. */
+    unloadTimedOut: boolean;
+    bootstrapAttempts: number;
+    /** Last bootstrap error when !ok. */
+    error?: string;
+}
+/**
+ * bootout, wait for the label to actually leave launchd, then bootstrap with
+ * backoff on EIO. `launchctl bootout` returns before launchd finishes tearing
+ * the job down, and a bootstrap issued in that window fails with
+ * "Bootstrap failed: 5: Input/output error" — after which the old job
+ * finishes unloading and nothing is left running.
+ */
+export declare function reloadLaunchd(plistPath: string, run: RunCommand, uid?: number, opts?: {
+    sleep?: SleepFn;
+    unloadDeadlineMs?: number;
+}): LaunchdReloadResult;
+/**
+ * (Re)load a plist so launchd picks up a rewritten ProgramArguments, then
+ * kickstart it. Never leaves the service silently unloaded: when bootstrap
+ * keeps failing but the previous job is still loaded, that job is restarted
+ * and the error says so; when nothing is loaded, the error says the service
+ * is NOT loaded and gives the command to load it.
+ */
+export declare function activateLaunchd(plistPath: string, run: RunCommand, uid?: number, opts?: {
+    sleep?: SleepFn;
+    unloadDeadlineMs?: number;
+}): void;
+export declare function deactivateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
+export declare function launchdIsLoaded(label: string, run: RunCommand, uid?: number): boolean;
+//# sourceMappingURL=launchd.d.ts.map

package/dist/lib/service-manager/launchd.js

@@ -0,0 +1,212 @@
+/**
+ * macOS LaunchAgent rendering + activation for kit services.
+ *
+ * Units live at ~/Library/LaunchAgents/<label>.plist. Activation uses the
+ * modern `launchctl bootstrap gui/<uid>` form (bootout first so a re-install
+ * picks up a changed plist). Command execution is injected so tests never
+ * touch launchctl.
+ */
+import { spawnSync } from "node:child_process";
+import * as os from "node:os";
+import * as path from "node:path";
+import { escapeXml, } from "./types.js";
+const LAUNCHD_PATH_ENV = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
+export function launchAgentsDir(home) {
+    return path.join(home, "Library", "LaunchAgents");
+}
+export function launchdPlistPath(home, spec) {
+    return path.join(launchAgentsDir(home), `${spec.label}.plist`);
+}
+export function renderLaunchdPlist(spec, host) {
+    const args = [host.nodeBinary, host.hqBinary, ...spec.args]
+        .map((a) => `    <string>${escapeXml(a)}</string>`)
+        .join("\n");
+    const env = {
+        HOME: host.home,
+        PATH: LAUNCHD_PATH_ENV,
+        ...spec.env,
+    };
+    const envXml = Object.entries(env)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `    <key>${escapeXml(k)}</key>\n    <string>${escapeXml(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>${escapeXml(spec.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(spec.workingDir)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>${spec.restartSec}</integer>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(spec.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(spec.logPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+</dict>
+</plist>
+`;
+}
+/** How long to wait for a booted-out job to leave launchd before bootstrapping anyway. */
+export const LAUNCHD_UNLOAD_DEADLINE_MS = 10_000;
+/** Interval between `launchctl print` polls while the old job unloads. */
+export const LAUNCHD_UNLOAD_POLL_MS = 250;
+/** Backoff before each bootstrap retry on EIO (one retry per entry). */
+export const LAUNCHD_BOOTSTRAP_BACKOFF_MS = [500, 1000, 2000, 4000, 8000];
+/** Bootstrap attempts after bootout (first try + EIO retries). */
+export const LAUNCHD_BOOTSTRAP_ATTEMPTS = LAUNCHD_BOOTSTRAP_BACKOFF_MS.length + 1;
+export const defaultRunCommand = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8" });
+    return {
+        status: r.status,
+        stdout: typeof r.stdout === "string" ? r.stdout : "",
+        stderr: r.error ? r.error.message : (typeof r.stderr === "string" ? r.stderr : ""),
+    };
+};
+function blockingSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function guiDomain(uid = os.userInfo().uid) {
+    return `gui/${uid}`;
+}
+export function launchdServiceTarget(plistPath, uid) {
+    return `${guiDomain(uid)}/${path.basename(plistPath, ".plist")}`;
+}
+function bootstrapErrorText(r) {
+    return `${r.stderr} ${r.stdout} exit ${r.status ?? ""}`;
+}
+/** launchd returns EIO (5) when bootstrap races the previous job's exit. */
+function isRetryableLaunchdBootstrap(r) {
+    if (r.status === 0)
+        return false;
+    return /Input\/output error|\bEIO\b|Bootstrap failed: 5|Boot-strap failed: 5/i.test(bootstrapErrorText(r));
+}
+function unescapeXml(value) {
+    return value
+        .replace(/&quot;/g, '"')
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
+/** ProgramArguments from a LaunchAgent plist. */
+export function launchdPlistProgramArguments(plist) {
+    const block = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (!block)
+        return [];
+    return [...block[1].matchAll(/<string>([^<]*)<\/string>/g)].map((m) => unescapeXml(m[1]));
+}
+/**
+ * Arguments of a loaded job from `launchctl print gui/<uid>/<label>`.
+ * Prefers the `arguments = { ... }` block; falls back to `program =`.
+ */
+export function parseLaunchctlPrintArguments(stdout) {
+    const block = /(?:program\s+)?arguments\s*=\s*\{([^}]*)\}/i.exec(stdout);
+    if (block) {
+        return block[1]
+            .split(/\r?\n/)
+            .map((line) => line.trim().replace(/;+$/, ""))
+            .filter((line) => line.length > 0);
+    }
+    const program = /^\s*program\s*=\s*(.+?);?\s*$/m.exec(stdout);
+    return program ? [program[1].trim()] : [];
+}
+export function launchdProgramArgumentsDiffer(loaded, plist) {
+    if (loaded.length === 0 || plist.length === 0)
+        return loaded.length !== plist.length;
+    if (loaded.length !== plist.length)
+        return true;
+    return loaded.some((value, i) => value !== plist[i]);
+}
+/**
+ * Poll `launchctl print <target>` until the label is gone. Returns false when
+ * it is still loaded at the deadline. Elapsed time is counted in slept
+ * intervals so an injected sleep keeps tests deterministic.
+ */
+export function waitForLaunchdUnload(target, run, opts) {
+    const sleep = opts?.sleep ?? blockingSleep;
+    const deadline = opts?.deadlineMs ?? LAUNCHD_UNLOAD_DEADLINE_MS;
+    for (let waited = 0; run("launchctl", ["print", target]).status === 0; waited += LAUNCHD_UNLOAD_POLL_MS) {
+        if (waited >= deadline)
+            return false;
+        sleep(LAUNCHD_UNLOAD_POLL_MS);
+    }
+    return true;
+}
+/**
+ * bootout, wait for the label to actually leave launchd, then bootstrap with
+ * backoff on EIO. `launchctl bootout` returns before launchd finishes tearing
+ * the job down, and a bootstrap issued in that window fails with
+ * "Bootstrap failed: 5: Input/output error" — after which the old job
+ * finishes unloading and nothing is left running.
+ */
+export function reloadLaunchd(plistPath, run, uid, opts) {
+    const domain = guiDomain(uid);
+    const target = launchdServiceTarget(plistPath, uid);
+    const sleep = opts?.sleep ?? blockingSleep;
+    // bootout is best-effort: "not loaded" on a first install is fine.
+    run("launchctl", ["bootout", target]);
+    const unloaded = waitForLaunchdUnload(target, run, { sleep, deadlineMs: opts?.unloadDeadlineMs });
+    let last = run("launchctl", ["bootstrap", domain, plistPath]);
+    let attempts = 1;
+    for (const backoff of LAUNCHD_BOOTSTRAP_BACKOFF_MS) {
+        if (last.status === 0 || !isRetryableLaunchdBootstrap(last))
+            break;
+        sleep(backoff);
+        last = run("launchctl", ["bootstrap", domain, plistPath]);
+        attempts++;
+    }
+    if (last.status === 0) {
+        return { ok: true, loaded: true, unloadTimedOut: !unloaded, bootstrapAttempts: attempts };
+    }
+    return {
+        ok: false,
+        loaded: run("launchctl", ["print", target]).status === 0,
+        unloadTimedOut: !unloaded,
+        bootstrapAttempts: attempts,
+        error: last.stderr.trim() || last.stdout.trim() || `exit ${last.status}`,
+    };
+}
+/**
+ * (Re)load a plist so launchd picks up a rewritten ProgramArguments, then
+ * kickstart it. Never leaves the service silently unloaded: when bootstrap
+ * keeps failing but the previous job is still loaded, that job is restarted
+ * and the error says so; when nothing is loaded, the error says the service
+ * is NOT loaded and gives the command to load it.
+ */
+export function activateLaunchd(plistPath, run, uid, opts) {
+    const domain = guiDomain(uid);
+    const target = launchdServiceTarget(plistPath, uid);
+    const r = reloadLaunchd(plistPath, run, uid, opts);
+    if (r.ok) {
+        run("launchctl", ["kickstart", "-k", target]);
+        return;
+    }
+    const detail = `launchctl bootstrap failed for ${plistPath} after ${r.bootstrapAttempts} attempts: ${r.error}`;
+    if (r.loaded) {
+        run("launchctl", ["kickstart", "-k", target]);
+        throw new Error(`${detail}. The previous definition of ${target} is still loaded and was restarted; ` +
+            `the rewritten plist is not active yet. Retry, or run: launchctl bootout ${target} && launchctl bootstrap ${domain} ${plistPath}`);
+    }
+    throw new Error(`${detail}. ${target} is NOT loaded and will not run until it is. Load it with: launchctl bootstrap ${domain} ${plistPath}`);
+}
+export function deactivateLaunchd(plistPath, run, uid) {
+    run("launchctl", ["bootout", guiDomain(uid), plistPath]);
+}
+export function launchdIsLoaded(label, run, uid) {
+    const r = run("launchctl", ["print", `${guiDomain(uid)}/${label}`]);
+    return r.status === 0;
+}
+//# sourceMappingURL=launchd.js.map

package/dist/lib/service-manager/systemd.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Linux systemd USER unit rendering + activation for kit services.
+ *
+ * Units live at ~/.config/systemd/user/<name>.service and are enabled with
+ * `systemctl --user enable --now`. A host without a user session bus (some
+ * containers, headless boxes) cannot run user units; the kit's Docker image
+ * is the escape hatch there. Command execution is injected for tests.
+ */
+import { type ServiceHostPaths, type ServiceSpec } from "./types.js";
+import type { RunCommand } from "./launchd.js";
+export declare const SYSTEMD_PATH_ENV = "/usr/local/bin:/usr/bin:/bin";
+export declare function systemdUserDir(home: string): string;
+export declare function systemdUnitName(spec: Pick<ServiceSpec, "name" | "unitName">): string;
+export declare function systemdUnitPath(home: string, spec: Pick<ServiceSpec, "name" | "unitName">): string;
+export declare function renderSystemdUserUnit(spec: ServiceSpec, host: ServiceHostPaths): string;
+export declare function activateSystemd(unitName: string, run: RunCommand): void;
+export declare function deactivateSystemd(unitName: string, run: RunCommand): void;
+export declare function systemdIsActive(unitName: string, run: RunCommand): boolean;
+//# sourceMappingURL=systemd.d.ts.map

package/dist/lib/service-manager/systemd.js

@@ -0,0 +1,72 @@
+/**
+ * Linux systemd USER unit rendering + activation for kit services.
+ *
+ * Units live at ~/.config/systemd/user/<name>.service and are enabled with
+ * `systemctl --user enable --now`. A host without a user session bus (some
+ * containers, headless boxes) cannot run user units; the kit's Docker image
+ * is the escape hatch there. Command execution is injected for tests.
+ */
+import * as path from "node:path";
+import { shellQuote, } from "./types.js";
+export const SYSTEMD_PATH_ENV = "/usr/local/bin:/usr/bin:/bin";
+export function systemdUserDir(home) {
+    return path.join(home, ".config", "systemd", "user");
+}
+export function systemdUnitName(spec) {
+    return spec.unitName ?? `hq-agent-${spec.name}.service`;
+}
+export function systemdUnitPath(home, spec) {
+    return path.join(systemdUserDir(home), systemdUnitName(spec));
+}
+export function renderSystemdUserUnit(spec, host) {
+    const exec = [host.nodeBinary, host.hqBinary, ...spec.args].map(shellQuote).join(" ");
+    const env = {
+        HOME: host.home,
+        PATH: SYSTEMD_PATH_ENV,
+        ...spec.env,
+    };
+    const envLines = Object.entries(env)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `Environment=${shellQuote(`${k}=${v}`)}`)
+        .join("\n");
+    return `[Unit]
+Description=${spec.description}
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+WorkingDirectory=${spec.workingDir}
+Restart=always
+RestartSec=${spec.restartSec}
+${envLines}
+StandardOutput=append:${spec.logPath}
+StandardError=append:${spec.logPath}
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function activateSystemd(unitName, run) {
+    const reload = run("systemctl", ["--user", "daemon-reload"]);
+    if (reload.status !== 0) {
+        throw new Error(`systemctl --user daemon-reload failed: ${reload.stderr.trim() || `exit ${reload.status}`}. ` +
+            `No user session bus? Use the hq-agent-kit Docker image instead.`);
+    }
+    const r = run("systemctl", ["--user", "enable", "--now", unitName]);
+    if (r.status !== 0) {
+        throw new Error(`systemctl --user enable --now ${unitName} failed: ${r.stderr.trim() || `exit ${r.status}`}`);
+    }
+    // A re-install with a changed unit must restart the running instance.
+    run("systemctl", ["--user", "restart", unitName]);
+}
+export function deactivateSystemd(unitName, run) {
+    run("systemctl", ["--user", "disable", "--now", unitName]);
+    run("systemctl", ["--user", "daemon-reload"]);
+}
+export function systemdIsActive(unitName, run) {
+    const r = run("systemctl", ["--user", "is-active", "--quiet", unitName]);
+    return r.status === 0;
+}
+//# sourceMappingURL=systemd.js.map

package/dist/lib/service-manager/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Platform-neutral description of a user-level background service. The
+ * launchd and systemd renderers turn one of these into a unit; the kit
+ * installer owns the list. Every service is just `node hq <args…>` so the
+ * unit files carry no logic of their own.
+ */
+export interface ServiceSpec {
+    /** Short name — unit file stem and log file stem (`sync`, `mesh`, …). */
+    name: string;
+    /** Reverse-DNS launchd label; systemd derives its unit name from `name`. */
+    label: string;
+    description: string;
+    /** Arguments passed to the hq binary (after `node hq`). */
+    args: string[];
+    /** Absolute log path (stdout + stderr appended). */
+    logPath: string;
+    workingDir: string;
+    /** Extra environment for the unit (HOME/PATH are always set). */
+    env: Record<string, string>;
+    /** Seconds to wait before a restart after exit. */
+    restartSec: number;
+    /** systemd unit file name; defaults to `hq-agent-<name>.service`. */
+    unitName?: string;
+}
+export interface ServiceHostPaths {
+    home: string;
+    nodeBinary: string;
+    hqBinary: string;
+}
+export type ServicePlatform = "darwin" | "linux" | "other";
+export declare function detectServicePlatform(platform?: NodeJS.Platform): ServicePlatform;
+export declare function escapeXml(value: string): string;
+export declare function shellQuote(value: string): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/service-manager/types.js

@@ -0,0 +1,26 @@
+/**
+ * Platform-neutral description of a user-level background service. The
+ * launchd and systemd renderers turn one of these into a unit; the kit
+ * installer owns the list. Every service is just `node hq <args…>` so the
+ * unit files carry no logic of their own.
+ */
+export function detectServicePlatform(platform = process.platform) {
+    if (platform === "darwin")
+        return "darwin";
+    if (platform === "linux")
+        return "linux";
+    return "other";
+}
+export function escapeXml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+export function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:=-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+//# sourceMappingURL=types.js.map

package/dist/lib/test-utils/isolated-flag-company-context.d.ts

@@ -0,0 +1,3 @@
+/** Keep process-wide flag tests independent of the developer machine binding. */
+export declare function isolateFlagCompanyContext(): () => void;
+//# sourceMappingURL=isolated-flag-company-context.d.ts.map