@indigoai-us/hq-cli 5.167.0 → 5.168.0

package/dist/lib/lanes/outpost-pruner-install.js

@@ -0,0 +1,226 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { resolveHqBinary, resolveNodeBinary } from "../mesh/live/daemon/install.js";
+import { SYSTEMD_PATH_ENV } from "../service-manager/systemd.js";
+export const OUTPOST_PRUNER_PRESSURE_SERVICE = "hq-outpost-worktree-pruner-pressure.service";
+export const OUTPOST_PRUNER_PRESSURE_TIMER = "hq-outpost-worktree-pruner-pressure.timer";
+export const OUTPOST_PRUNER_DAILY_SERVICE = "hq-outpost-worktree-pruner-daily.service";
+export const OUTPOST_PRUNER_DAILY_TIMER = "hq-outpost-worktree-pruner-daily.timer";
+export const OUTPOST_PRUNER_MIN_AGE_DAYS = 14;
+function shellQuote(value) {
+    return /^[A-Za-z0-9_./:-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function systemdEnvironment(name, value) {
+    if (/[\r\n\0]/.test(value))
+        throw new TypeError(`${name} contains a line break or NUL`);
+    const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%");
+    return `Environment="${name}=${escaped}"`;
+}
+function writeIfChanged(filePath, contents) {
+    try {
+        if (fs.readFileSync(filePath, "utf8") === contents)
+            return false;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, contents, { encoding: "utf8", mode: 0o644 });
+        fs.renameSync(temporary, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch (unlinkError) {
+            if (unlinkError.code !== "ENOENT") {
+                process.stderr.write(`outpost pruner install: temporary unit cleanup failed (${unlinkError.code ?? "Error"})\n`);
+            }
+        }
+        throw err;
+    }
+    return true;
+}
+function unlinkIfExists(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+function runSystemctl(args, run) {
+    const result = run("systemctl", args);
+    if (result.status !== 0)
+        throw new Error(`systemctl ${args.join(" ")} failed (${result.status})`);
+}
+function pnpmBinaryDirs() {
+    const resolved = [];
+    for (const directory of (process.env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+        const binary = path.join(directory, "pnpm");
+        try {
+            fs.accessSync(binary, fs.constants.X_OK);
+            for (const candidate of [path.resolve(directory), path.dirname(fs.realpathSync(binary))]) {
+                if (!resolved.includes(candidate))
+                    resolved.push(candidate);
+            }
+            break;
+        }
+        catch {
+            // Keep looking. The full interactive-shell PATH is not copied into units.
+        }
+    }
+    return resolved;
+}
+function unitPathEnv(hqBinary, nodeBinary) {
+    const dirs = [
+        ...pnpmBinaryDirs(),
+        path.dirname(path.resolve(hqBinary)),
+        path.dirname(path.resolve(nodeBinary)),
+        ...SYSTEMD_PATH_ENV.split(":"),
+    ];
+    return [...new Set(dirs)].filter(Boolean).join(":");
+}
+function renderService(opts) {
+    const command = [
+        opts.nodeBinary,
+        opts.hqBinary,
+        "lanes",
+        "outpost-pruner",
+        "run",
+        "--trigger",
+        opts.trigger,
+        "--min-age-days",
+        String(OUTPOST_PRUNER_MIN_AGE_DAYS),
+    ].map(shellQuote).join(" ");
+    return `[Unit]
+Description=HQ outpost worktree pruning (${opts.trigger})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=${command}
+WorkingDirectory=${shellQuote(opts.hqRoot)}
+Nice=10
+Environment=HOME=${shellQuote(opts.home)}
+Environment=PATH=${shellQuote(opts.pathEnv)}
+Environment=HQ_ROOT=${shellQuote(opts.hqRoot)}
+Environment=HQ_NO_UPDATE_CHECK=1
+${opts.flagEnvironment}
+KillMode=process
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function renderOutpostPrunerPressureTimer() {
+    return `[Unit]
+Description=Check HQ outpost disk pressure for safe worktree cleanup
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=5min
+AccuracySec=30s
+Persistent=true
+Unit=${OUTPOST_PRUNER_PRESSURE_SERVICE}
+
+[Install]
+WantedBy=timers.target
+`;
+}
+export function renderOutpostPrunerDailyTimer() {
+    return `[Unit]
+Description=Daily HQ outpost safe worktree cleanup
+
+[Timer]
+OnCalendar=*-*-* 03:10:00
+RandomizedDelaySec=10min
+AccuracySec=1min
+Persistent=true
+Unit=${OUTPOST_PRUNER_DAILY_SERVICE}
+
+[Install]
+WantedBy=timers.target
+`;
+}
+export function defaultOutpostPrunerSystemdDir(home = os.homedir()) {
+    return path.join(home, ".config", "systemd", "user");
+}
+export function installOutpostPrunerTimers(options) {
+    const nodeBinary = options.nodeBinary ?? resolveNodeBinary();
+    const hqBinary = options.hqBinary ?? resolveHqBinary();
+    const home = options.home ?? os.homedir();
+    const flagApiUrl = (options.flagApiUrl ?? process.env.HQ_FLAGS_API_URL ?? "").trim();
+    const companyUid = (options.companyUid ?? process.env.HQ_COMPANY_UID ?? "").trim();
+    if (!flagApiUrl || !companyUid) {
+        throw new TypeError("install requires HQ_FLAGS_API_URL and HQ_COMPANY_UID for the timer services");
+    }
+    const flagEnvironment = [
+        systemdEnvironment("HQ_FLAGS_API_URL", flagApiUrl),
+        systemdEnvironment("HQ_COMPANY_UID", companyUid),
+    ].join("\n");
+    const pathEnv = unitPathEnv(hqBinary, nodeBinary);
+    const units = [
+        [OUTPOST_PRUNER_PRESSURE_SERVICE, renderService({ trigger: "pressure", nodeBinary, hqBinary, hqRoot: options.hqRoot, home, pathEnv, flagEnvironment })],
+        [OUTPOST_PRUNER_PRESSURE_TIMER, renderOutpostPrunerPressureTimer()],
+        [OUTPOST_PRUNER_DAILY_SERVICE, renderService({ trigger: "daily", nodeBinary, hqBinary, hqRoot: options.hqRoot, home, pathEnv, flagEnvironment })],
+        [OUTPOST_PRUNER_DAILY_TIMER, renderOutpostPrunerDailyTimer()],
+    ];
+    let written = false;
+    for (const [name, contents] of units) {
+        written = writeIfChanged(path.join(options.systemdRoot, name), contents) || written;
+    }
+    let enabled = false;
+    if (options.enable) {
+        if (!options.runCommand)
+            throw new Error("--enable needs a systemctl runner");
+        runSystemctl(["--user", "daemon-reload"], options.runCommand);
+        runSystemctl(["--user", "enable", "--now", OUTPOST_PRUNER_PRESSURE_TIMER, OUTPOST_PRUNER_DAILY_TIMER], options.runCommand);
+        enabled = true;
+    }
+    return {
+        ok: true,
+        action: "outpost-pruner.install",
+        systemd_root: options.systemdRoot,
+        units: units.map(([name]) => path.join(options.systemdRoot, name)),
+        written,
+        enabled,
+    };
+}
+export function uninstallOutpostPrunerTimers(options) {
+    if (options.disable) {
+        if (!options.runCommand)
+            throw new Error("--disable needs a systemctl runner");
+        runSystemctl(["--user", "disable", "--now", OUTPOST_PRUNER_PRESSURE_TIMER, OUTPOST_PRUNER_DAILY_TIMER], options.runCommand);
+    }
+    const units = [
+        OUTPOST_PRUNER_PRESSURE_SERVICE,
+        OUTPOST_PRUNER_PRESSURE_TIMER,
+        OUTPOST_PRUNER_DAILY_SERVICE,
+        OUTPOST_PRUNER_DAILY_TIMER,
+    ];
+    let removed = false;
+    for (const name of units) {
+        removed = unlinkIfExists(path.join(options.systemdRoot, name)) || removed;
+    }
+    if (options.disable && options.runCommand)
+        runSystemctl(["--user", "daemon-reload"], options.runCommand);
+    return {
+        ok: true,
+        action: "outpost-pruner.uninstall",
+        systemd_root: options.systemdRoot,
+        units: units.map((name) => path.join(options.systemdRoot, name)),
+        removed,
+    };
+}
+//# sourceMappingURL=outpost-pruner-install.js.map

package/dist/lib/lanes/outpost-worktree-pruner-flag.d.ts

@@ -0,0 +1,19 @@
+import { createFlagClient } from "@indigoai-us/hq-flags-client";
+export declare const OUTPOST_WORKTREE_PRUNER_FLAG = "outpost.worktree-pruner";
+export declare const OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK = false;
+export declare const OUTPOST_WORKTREE_PRUNER_FLAG_TIMEOUT_MS = 5000;
+export interface OutpostPrunerFlagClient {
+    ready(): Promise<void>;
+    isEnabled(flagKey: string, options?: {
+        fallback?: boolean;
+    }): boolean;
+    close(): void;
+}
+export interface OutpostPrunerFlagDependencies {
+    env?: NodeJS.ProcessEnv;
+    createClient?: typeof createFlagClient;
+    getToken?: () => string | Promise<string>;
+    reportFailure?: (error: unknown) => void;
+}
+export declare function outpostWorktreePrunerEnabled(dependencies?: OutpostPrunerFlagDependencies): Promise<boolean>;
+//# sourceMappingURL=outpost-worktree-pruner-flag.d.ts.map

package/dist/lib/lanes/outpost-worktree-pruner-flag.js

@@ -0,0 +1,76 @@
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { createFlagClient } from "@indigoai-us/hq-flags-client";
+export const OUTPOST_WORKTREE_PRUNER_FLAG = "outpost.worktree-pruner";
+export const OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK = false;
+export const OUTPOST_WORKTREE_PRUNER_FLAG_TIMEOUT_MS = 5_000;
+/**
+ * Read the company-scoped rollout flag with bounded I/O. Missing endpoint,
+ * company identity, registry row, cached token, or registry availability all
+ * leave destructive pruning disabled.
+ */
+function errorClass(error) {
+    return error instanceof Error ? error.name : "UnknownError";
+}
+function reportFlagFailure(error) {
+    process.stderr.write(`${JSON.stringify({
+        event: "outpost.worktree_pruner.flag_read_failed",
+        flag: OUTPOST_WORKTREE_PRUNER_FLAG,
+        error: errorClass(error),
+        fallback: OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK,
+    })}\n`);
+}
+export async function outpostWorktreePrunerEnabled(dependencies = {}) {
+    const env = dependencies.env ?? process.env;
+    const endpoint = env.HQ_FLAGS_API_URL?.trim() || "";
+    const companyUid = env.HQ_COMPANY_UID?.trim() || "";
+    if (!endpoint || !companyUid) {
+        process.stderr.write(`${JSON.stringify({
+            event: "outpost.worktree_pruner.flag_config_missing",
+            flag: OUTPOST_WORKTREE_PRUNER_FLAG,
+            missing: [
+                ...(!endpoint ? ["HQ_FLAGS_API_URL"] : []),
+                ...(!companyUid ? ["HQ_COMPANY_UID"] : []),
+            ],
+            fallback: OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK,
+        })}\n`);
+        return OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK;
+    }
+    const companySlug = env.HQ_COMPANY_SLUG?.trim() || "";
+    let client;
+    let enabled = OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK;
+    let failed = false;
+    let reported = false;
+    const reportFailure = (error) => {
+        failed = true;
+        if (reported)
+            return;
+        reported = true;
+        (dependencies.reportFailure ?? reportFlagFailure)(error);
+    };
+    try {
+        client = (dependencies.createClient ?? createFlagClient)({
+            endpoint,
+            companyUid,
+            ...(companySlug ? { companyIdentifiers: [companySlug] } : {}),
+            getToken: dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? ""),
+            refreshIntervalMs: 0,
+            requestTimeoutMs: OUTPOST_WORKTREE_PRUNER_FLAG_TIMEOUT_MS,
+            onError: reportFailure,
+        });
+        await client.ready();
+        enabled = client.isEnabled(OUTPOST_WORKTREE_PRUNER_FLAG, {
+            fallback: OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK,
+        });
+    }
+    catch (error) {
+        reportFailure(error);
+    }
+    try {
+        client?.close();
+    }
+    catch (error) {
+        reportFailure(error);
+    }
+    return failed ? OUTPOST_WORKTREE_PRUNER_FLAG_FALLBACK : enabled;
+}
+//# sourceMappingURL=outpost-worktree-pruner-flag.js.map

package/dist/lib/lanes/outpost-worktree-pruner.d.ts

@@ -0,0 +1,60 @@
+/** Safe, host-local cleanup for terminal HQ worktrees on outposts. */
+export type PrunerTrigger = "pressure" | "daily" | "manual";
+export interface OutpostWorktreePrunerOptions {
+    hqRoot: string;
+    trigger: PrunerTrigger;
+    dryRun: boolean;
+    featureEnabled: boolean;
+    minAgeDays: number;
+    now?: number;
+    /** Test seam. Production uses /proc. */
+    processRoot?: string;
+    /** Test seam. Production safely resolves and runs `pnpm store prune`. */
+    runPackageStorePrune?: () => PackageStorePruneResult;
+    /** Test seam for the storage threshold; production reads filesystem stats. */
+    readDiskUsedPercent?: (hqRoot: string) => number | null;
+    /** Test seam for classifying inaccessible /proc entries by owner. */
+    processUserId?: number;
+    /** Test seam for /proc reads; production uses the host filesystem. */
+    processPathReader?: ProcessPathReader;
+}
+export interface ProcessPathReader {
+    readdirSync(path: string): string[];
+    readlinkSync(path: string): string;
+    uid(path: string): number;
+}
+export interface PackageStorePruneResult {
+    attempted: boolean;
+    reason?: string;
+    bytes_freed?: number;
+}
+export interface OutpostWorktreePrunerResult {
+    event: "outpost.worktree_pruner.run";
+    trigger: PrunerTrigger;
+    dry_run: boolean;
+    feature_enabled: boolean;
+    skipped?: string;
+    pressure_percent?: number;
+    min_age_days: number;
+    candidates: string[];
+    removed: Array<{
+        path: string;
+        bytes_freed: number;
+    }>;
+    kept: Array<{
+        path: string;
+        reason: string;
+    }>;
+    bytes_freed: number;
+    bytes_freed_basis: "statfs_available_byte_delta";
+    package_store: PackageStorePruneResult;
+}
+/**
+ * Prune only registered worktrees beneath workspace/worktrees after every
+ * local, git, age, and liveness check has passed. The function never shells
+ * out to rm and never follows symlinks while estimating or checking age.
+ */
+export declare function runOutpostWorktreePruner(options: OutpostWorktreePrunerOptions): OutpostWorktreePrunerResult;
+export declare const OUTPOST_WORKTREE_PRUNER_DEFAULT_MIN_AGE_DAYS = 14;
+export declare const OUTPOST_WORKTREE_PRUNER_PRESSURE_THRESHOLD_PERCENT = 78;
+//# sourceMappingURL=outpost-worktree-pruner.d.ts.map