@indigoai-us/hq-cli 5.313.0 → 5.314.0

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

@@ -1,81 +0,0 @@
-/**
- * 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

@@ -1,212 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-/**
- * 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

@@ -1,72 +0,0 @@
-/**
- * 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

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,26 +0,0 @@
-/**
- * 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

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

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

@@ -1,18 +0,0 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { vi } from "vitest";
-/** Keep process-wide flag tests independent of the developer machine binding. */
-export function isolateFlagCompanyContext() {
-    const home = fs.mkdtempSync(path.join(os.tmpdir(), "hq-flag-company-context-"));
-    vi.stubEnv("HOME", home);
-    vi.stubEnv("HQ_COMPANY_UID", undefined);
-    vi.stubEnv("HQ_COMPANY_SLUG", undefined);
-    vi.stubEnv("HQ_SPAWN_COMPANY", undefined);
-    vi.stubEnv("HQ_SESSION_ID", undefined);
-    vi.stubEnv("HQ_AGENT_IDENTITY_FILE", "");
-    vi.stubEnv("HQ_ROOT", undefined);
-    vi.stubEnv("HQ_WORK_CONTEXT_ROOT", undefined);
-    return () => fs.rmSync(home, { recursive: true, force: true });
-}
-//# sourceMappingURL=isolated-flag-company-context.js.map

package/dist/lib/work-context/bind-best.d.ts

@@ -1,66 +0,0 @@
-/**
- * US-036: pick the best existing project for a session hint.
- * Exact Board, then exact local PRD, then a ranked match.
- * A tie or an empty field stays unbound so the session can ask.
- */
-export interface BindCandidate {
-    projectId: string;
-    title?: string;
-    score: number;
-}
-export interface CatalogProject {
-    projectId: string;
-    title?: string;
-    repos: string[];
-    journalMtimeMs?: number;
-    hasPrd: boolean;
-    hasBoard: boolean;
-    prdPath?: string;
-}
-export type RefineAction = {
-    action: "keep";
-} | {
-    action: "bind";
-    projectId: string;
-    reason: string;
-} | {
-    action: "create";
-    projectId: string;
-    prdPath: string;
-    reason: string;
-} | {
-    action: "ask";
-    reason: string;
-    candidates: BindCandidate[];
-};
-export declare function scoreProject(hint: string, row: CatalogProject, repoPath: string | undefined, nowMs: number): number;
-export declare function discoverProjects(input: {
-    hqRoot?: string;
-    companySlug?: string;
-    companyUid?: string;
-    env?: NodeJS.ProcessEnv;
-    home?: string;
-}): CatalogProject[];
-/** discoverProjects memoized by directory mtime. A cache hit does not rescan. */
-export declare function discoverProjectsCached(input: Parameters<typeof discoverProjects>[0], nowMs?: number): CatalogProject[];
-export declare function refineProjectBinding(input: {
-    hint?: string;
-    hqRoot?: string;
-    companySlug?: string;
-    companyUid?: string;
-    repoPath?: string;
-    env?: NodeJS.ProcessEnv;
-    home?: string;
-    nowMs?: number;
-}): RefineAction;
-export declare function findLocalPrd(hqRoot: string | undefined, companySlug: string | undefined, projectId: string): string | null;
-export declare function listNeedsProjectSessions(workContextRoot: string): Array<{
-    sessionId: string;
-    reason?: string;
-    candidates: BindCandidate[];
-}>;
-export declare function formatProjectAsk(candidates: Array<{
-    projectId: string;
-    title?: string;
-}>): string;
-//# sourceMappingURL=bind-best.d.ts.map