@indigoai-us/hq-cli 5.299.0 → 5.301.0

package/dist/commands/core-job-native-utils.js

@@ -0,0 +1,80 @@
+import { resolveLiveRoot } from "../utils/hq-roots.js";
+import { runBundledScript } from "../utils/run-bundled-script.js";
+import { describeCoreCommand } from "./core-command-catalog.js";
+import { coreNativeJobsEnabled } from "./core-native-jobs-flag.js";
+/** Preserve raw argv (including the option terminator) through Commander. */
+export function rawJobArgumentsForCommand(command, fallback, raw = process.argv) {
+    const names = [];
+    for (let current = command; current?.parent; current = current.parent) {
+        names.unshift(current.name());
+    }
+    let start = -1;
+    let cursor = 0;
+    for (const name of names) {
+        const index = raw.indexOf(name, cursor);
+        if (index < 0)
+            return command.args.length ? command.args : fallback;
+        cursor = index + 1;
+        start = cursor;
+    }
+    return start >= 0 ? raw.slice(start) : (command.args.length ? command.args : fallback);
+}
+/** Shared gated registration path for each leaf in the singular job group. */
+export function registerCoreJobLeaf(group, core, name, asset, summary, run, canUseLiveRoot, valueOptions, booleanOptions = []) {
+    const command = group.command(name)
+        .description(summary)
+        .helpOption(false)
+        .allowUnknownOption()
+        .allowExcessArguments(true)
+        .argument("[args...]", "Arguments passed to the scaffold helper")
+        .action(async (args, _options, current) => {
+        const argv = rawJobArgumentsForCommand(current, args);
+        const groupHqRoot = core.opts().hqRoot;
+        const hqRoot = canUseLiveRoot(argv)
+            ? resolveLiveRoot({ hqRoot: leafRootOverride(argv, valueOptions, booleanOptions) ?? groupHqRoot })
+            : groupHqRoot ?? "";
+        if (!await coreNativeJobsEnabled()) {
+            const result = runBundledScript({ asset, args: argv, cwd: process.cwd(), hqRoot: hqRoot || undefined });
+            if (result.code !== 0)
+                process.exit(result.code);
+            return;
+        }
+        const result = run(argv, hqRoot);
+        if (result !== 0)
+            process.exit(result);
+    });
+    describeCoreCommand(command, { execution: "native", asset, root: "live" });
+}
+/**
+ * Find a leaf --hq-root without resolving anything until the leaf parser has
+ * had the chance to return its own help or usage error. The option lists are
+ * the same grammar used by the shell and native leaves.
+ */
+function leafRootOverride(argv, valueOptions, booleanOptions) {
+    let root;
+    for (let index = 0; index < argv.length;) {
+        const flag = argv[index];
+        if (flag === "--")
+            return root;
+        if (flag === "--hq-root") {
+            const value = argv[index + 1] ?? "";
+            if (!value)
+                return undefined;
+            root = value;
+            index += 2;
+            continue;
+        }
+        if (valueOptions.includes(flag)) {
+            index += 2;
+            continue;
+        }
+        if (booleanOptions.includes(flag)) {
+            index += 1;
+            continue;
+        }
+        // The preflight parser has already rejected invalid options and operands.
+        return root;
+    }
+    return root;
+}
+//# sourceMappingURL=core-job-native-utils.js.map

package/dist/commands/core-job-native.d.ts

@@ -1,7 +1,5 @@
-/** Native `hq core job <name>` command group. */
+/** Native hq core job command group. */
 import type { Command } from "commander";
-export declare function registerCoreJobNativeCommand(core: Command): void;
-export declare function registerCoreJobCommand(core: Command): void;
-/** Keep eager `core` registration complete while the jobs fast route loads only its own module. */
+/** Register all job leaves on one singular group plus the existing plural group. */
 export declare function registerCoreJobsNativeCommand(core: Command): void;
 //# sourceMappingURL=core-job-native.d.ts.map

package/dist/commands/core-job-native.js

@@ -1,19 +1,15 @@
+import { registerCoreJobNotifyNativeCommand } from "./core-job-notify-native.js";
 import { registerCoreJobProbeCommand } from "./core-job-probe-native.js";
+import { registerCoreJobRemediateNativeCommand } from "./core-job-remediate-native.js";
 import { registerCoreJobRunCommand } from "./core-job-run-native.js";
 import { registerCoreJobsNativeCommand as registerPluralJobsCommand } from "./core-jobs-native.js";
-const JOB_GROUP_DESCRIPTION = "Run or inspect one scheduled job";
-export function registerCoreJobNativeCommand(core) {
-    const job = core.command("job").description(JOB_GROUP_DESCRIPTION);
-    registerCoreJobProbeCommand(job);
-}
-export function registerCoreJobCommand(core) {
-    const job = core.command("job").description(JOB_GROUP_DESCRIPTION);
-    registerCoreJobRunCommand(job);
-}
-/** Keep eager `core` registration complete while the jobs fast route loads only its own module. */
+const JOB_GROUP_DESCRIPTION = "Run, inspect, notify, or remediate one scheduled job";
+/** Register all job leaves on one singular group plus the existing plural group. */
 export function registerCoreJobsNativeCommand(core) {
     const job = core.command("job").description(JOB_GROUP_DESCRIPTION);
+    registerCoreJobNotifyNativeCommand(job, core);
     registerCoreJobProbeCommand(job);
+    registerCoreJobRemediateNativeCommand(job, core);
     registerCoreJobRunCommand(job);
     registerPluralJobsCommand(core);
 }

package/dist/commands/core-job-notify-native.d.ts

@@ -0,0 +1,36 @@
+/** Native TypeScript port of hq-job-notify.sh. */
+import { Command } from "commander";
+type Environment = Record<string, string | undefined>;
+export type JobNotifyProcessResult = {
+    code: number;
+    stdout: string;
+};
+export type JobNotifyRunOptions = {
+    cwd: string;
+    env: Environment;
+    captureStdout: boolean;
+    logPath?: string;
+};
+export type JobNotifyDependencies = {
+    env: Environment;
+    cwd: string;
+    now: () => Date;
+    exists: (file: string) => boolean;
+    readFile: (file: string) => string;
+    mkdir: (directory: string) => void;
+    writeFile: (file: string, content: string) => void;
+    appendFile: (file: string, content: string) => void;
+    chmod: (file: string, mode: number) => void;
+    commandExists: (command: string) => boolean;
+    run: (command: string, args: string[], options: JobNotifyRunOptions) => JobNotifyProcessResult;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+};
+export declare function defaultJobNotifyDependencies(env?: Environment, cwd?: string): JobNotifyDependencies;
+export declare function runJobNotify(argv: string[], options?: {
+    hqRoot?: string;
+    dependencies?: Partial<JobNotifyDependencies>;
+}): number;
+export declare function registerCoreJobNotifyNativeCommand(group: Command, core: Command): void;
+export {};
+//# sourceMappingURL=core-job-notify-native.d.ts.map

package/dist/commands/core-job-notify-native.js

@@ -0,0 +1,359 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+import { load } from "js-yaml";
+import { serializeJqJson } from "../lib/core-utils/jq-json-serializer.js";
+import { registerCoreJobLeaf } from "./core-job-native-utils.js";
+const ASSET = "core/scripts/hq-job-notify.sh";
+const USAGE = [
+    "hq-job-notify.sh — dm-only remediation alerts for Outpost scheduled jobs (US-006).",
+    "",
+    'Delivers via schedule-alerts profile with v1 channel=dm only (`hq dm` to owner).',
+    "If profile channel is slack|email|outpost-session, still deliver dm and log",
+    "channel_unimplemented. Never targets the original /schedule create session.",
+    "",
+    "Escalation collapse:",
+    "  - first failure → DM immediately",
+    "  - consecutive failures → at most one failure DM per 24h per job",
+    "  - recovery after failures → recovered DM",
+    "  - success after success → ok DM (every successful run)",
+    "",
+    "Notify delivery failure is logged and never fails the caller (exit 0).",
+    "",
+    "Usage:",
+    "  core/scripts/hq-job-notify.sh \\",
+    "    --job-id <id> --job-name <name> --outcome <ok|failed|blocked> \\",
+    "    --summary <one-line> --duration <sec> --log-path <path> \\",
+    "    [--failure-class <class>] [--next-action <text>] \\",
+    "    [--owner <email|prs_*>] [--notify <dm|none|profile>] \\",
+    "    [--hq-root <dir>]",
+    "",
+    "Env / overrides (tests):",
+    "  HQ_ROOT, HOME, HQ_JOB_ALERT_DIR, HQ_JOB_NOTIFY_DM_BIN, HQ_JOB_NOTIFY_NOW_EPOCH",
+    "  HQ_JOB_NOTIFY_COLLAPSE_SEC (default 86400)",
+    "",
+    "Exit: 0 always (delivery errors logged only); 2 usage.",
+    "",
+    "set -euo pipefail",
+    "",
+    "",
+].join("\n");
+function defaultCommandExists(command, env) {
+    if (command.includes(path.sep)) {
+        try {
+            fs.accessSync(command, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+        if (!directory)
+            continue;
+        try {
+            fs.accessSync(path.join(directory, command), fs.constants.X_OK);
+            return true;
+        }
+        catch { /* Continue PATH lookup. */ }
+    }
+    return false;
+}
+function defaultRun(command, args, options) {
+    let logFd;
+    try {
+        if (options.logPath) {
+            try {
+                logFd = fs.openSync(options.logPath, "a");
+            }
+            catch {
+                // The shell treats failed output redirection as a failed delivery and
+                // continues the caller successfully; runJobNotify records that result.
+                return { code: 1, stdout: "" };
+            }
+        }
+        const result = spawnSync(command, args, {
+            cwd: options.cwd,
+            env: options.env,
+            encoding: "utf8",
+            stdio: options.captureStdout ? ["ignore", "pipe", "ignore"] : ["ignore", logFd ?? "ignore", logFd ?? "ignore"],
+        });
+        if (result.error) {
+            if (logFd !== undefined)
+                fs.writeSync(logFd, `${result.error.message}\n`);
+            return { code: 127, stdout: "" };
+        }
+        const signalNumber = result.signal ? os.constants.signals[result.signal] : undefined;
+        return {
+            code: result.status ?? (signalNumber ? 128 + signalNumber : 1),
+            stdout: result.stdout ?? "",
+        };
+    }
+    finally {
+        if (logFd !== undefined)
+            fs.closeSync(logFd);
+    }
+}
+export function defaultJobNotifyDependencies(env = process.env, cwd = process.cwd()) {
+    return {
+        env,
+        cwd,
+        now: () => new Date(),
+        exists: (file) => fs.existsSync(file),
+        readFile: (file) => fs.readFileSync(file, "utf8"),
+        mkdir: (directory) => fs.mkdirSync(directory, { recursive: true }),
+        writeFile: (file, content) => fs.writeFileSync(file, content),
+        appendFile: (file, content) => fs.appendFileSync(file, content),
+        chmod: (file, mode) => fs.chmodSync(file, mode),
+        commandExists: (command) => defaultCommandExists(command, env),
+        run: defaultRun,
+        stdout: (text) => { process.stdout.write(text); },
+        stderr: (text) => { process.stderr.write(text); },
+    };
+}
+function parseArguments(argv, deps) {
+    const values = {
+        hqRoot: deps.env.HQ_ROOT ?? "",
+        jobId: "", jobName: "", outcome: "", summary: "", duration: "", logPath: "",
+        failureClass: "", nextAction: "", owner: "", notifyMode: "",
+    };
+    const aliases = {
+        "--hq-root": "hqRoot", "--job-id": "jobId", "--job-name": "jobName",
+        "--outcome": "outcome", "--summary": "summary", "--duration": "duration",
+        "--log-path": "logPath", "--failure-class": "failureClass",
+        "--next-action": "nextAction", "--owner": "owner", "--notify": "notifyMode",
+    };
+    for (let index = 0; index < argv.length;) {
+        const flag = argv[index];
+        if (flag === "-h" || flag === "--help") {
+            deps.stdout(USAGE);
+            return 0;
+        }
+        if (flag === "--")
+            break;
+        const key = aliases[flag];
+        if (key) {
+            const value = argv[index + 1] ?? "";
+            if ((key === "hqRoot" || key === "jobId" || key === "outcome") && !value) {
+                deps.stderr(`hq-job-notify: --${key === "hqRoot" ? "hq-root" : key === "jobId" ? "job-id" : "outcome"} requires ${key === "hqRoot" ? "a directory" : "a value"}\n`);
+                return 2;
+            }
+            values[key] = value;
+            index += 2;
+            continue;
+        }
+        if (flag.startsWith("-")) {
+            deps.stderr(`hq-job-notify: unknown option: ${flag}\n`);
+            return 2;
+        }
+        deps.stderr(`hq-job-notify: unexpected argument: ${flag}\n`);
+        return 2;
+    }
+    if (!values.jobId) {
+        deps.stderr("hq-job-notify: usage: hq-job-notify.sh --job-id <id> --outcome <ok|failed|blocked> ...\n");
+        return 2;
+    }
+    if (!["ok", "failed", "blocked"].includes(values.outcome)) {
+        deps.stderr("hq-job-notify: --outcome must be ok|failed|blocked\n");
+        return 2;
+    }
+    if (!values.jobName)
+        values.jobName = values.jobId;
+    if (!values.summary)
+        values.summary = values.outcome;
+    if (!values.duration)
+        values.duration = "0";
+    return values;
+}
+function canUseLiveRootForArguments(argv) {
+    const parsed = parseArguments(argv, {
+        env: {},
+        stdout: () => undefined,
+        stderr: () => undefined,
+    });
+    return typeof parsed !== "number";
+}
+function profileChannel(profilePath, deps) {
+    if (!deps.exists(profilePath) || !deps.commandExists("yq"))
+        return "dm";
+    try {
+        const loaded = load(deps.readFile(profilePath));
+        const channel = loaded?.channel;
+        return channel === undefined || channel === null || channel === false || channel === "" ? "dm" : String(channel);
+    }
+    catch {
+        // The shell suppresses yq parse errors and falls back through `|| echo dm`.
+        return "dm";
+    }
+}
+function emailFromWhoami(output) {
+    for (const line of output.split(/\r?\n/)) {
+        if (!line.startsWith("email:"))
+            continue;
+        const separator = line.indexOf(": ");
+        return (separator < 0 ? line : line.slice(separator + 2)).trimEnd();
+    }
+    return "";
+}
+function normalizedEpoch(value) {
+    if (!/^-?\d+$/.test(value))
+        throw new Error(`invalid HQ_JOB_NOTIFY_NOW_EPOCH: ${value}`);
+    const result = Number(value);
+    if (!Number.isSafeInteger(result))
+        throw new Error(`invalid HQ_JOB_NOTIFY_NOW_EPOCH: ${value}`);
+    return result;
+}
+export function runJobNotify(argv, options = {}) {
+    const deps = {
+        ...defaultJobNotifyDependencies(options.dependencies?.env ?? process.env, options.dependencies?.cwd ?? process.cwd()),
+        ...options.dependencies,
+    };
+    if (options.hqRoot)
+        deps.env = { ...deps.env, HQ_ROOT: options.hqRoot };
+    const parsed = parseArguments(argv, deps);
+    if (typeof parsed === "number")
+        return parsed;
+    const hqRoot = parsed.hqRoot || options.hqRoot || deps.env.HQ_ROOT || "";
+    if (hqRoot)
+        deps.env = { ...deps.env, HQ_ROOT: hqRoot };
+    const nowEpoch = deps.env.HQ_JOB_NOTIFY_NOW_EPOCH
+        ? normalizedEpoch(deps.env.HQ_JOB_NOTIFY_NOW_EPOCH)
+        : Math.floor(deps.now().getTime() / 1000);
+    const collapseSecText = deps.env.HQ_JOB_NOTIFY_COLLAPSE_SEC || "86400";
+    if (!/^-?\d+$/.test(collapseSecText))
+        throw new Error(`invalid HQ_JOB_NOTIFY_COLLAPSE_SEC: ${collapseSecText}`);
+    const collapseSec = Number(collapseSecText);
+    const alertBase = deps.env.HQ_JOB_ALERT_DIR || path.join(deps.env.HOME || path.sep, ".hq", "jobs", "alerts");
+    const stateDir = path.join(alertBase, parsed.jobId);
+    deps.mkdir(stateDir);
+    const stateFile = path.join(stateDir, "state.json");
+    const deliveryLog = path.join(stateDir, "delivery.log");
+    const log = (message) => deps.stderr(`hq-job-notify: ${message}\n`);
+    let notifyMode = parsed.notifyMode;
+    if (!notifyMode || notifyMode === "null")
+        notifyMode = "profile";
+    if (notifyMode === "none") {
+        log(`notify=none — skipping delivery for job ${parsed.jobId}`);
+        deps.stdout('{"delivered":false,"reason":"notify_none"}\n');
+        return 0;
+    }
+    const selectedChannel = notifyMode === "profile"
+        ? profileChannel(path.join(hqRoot, "personal/settings/schedule-alerts.yaml"), deps)
+        : "dm";
+    if (notifyMode !== "profile" && notifyMode !== "dm")
+        log(`unknown notify mode '${notifyMode}' — falling back to dm`);
+    let channelUnimplemented = 0;
+    if (selectedChannel !== "dm" && selectedChannel !== "") {
+        channelUnimplemented = 1;
+        log(`channel_unimplemented=${selectedChannel} — delivering dm fallback`);
+    }
+    let owner = parsed.owner;
+    if (!owner || owner === "null") {
+        owner = "";
+        if (deps.commandExists("hq")) {
+            owner = emailFromWhoami(deps.run("hq", ["whoami"], {
+                cwd: deps.cwd, env: deps.env, captureStdout: true,
+            }).stdout);
+        }
+    }
+    if (!owner) {
+        log("no owner recipient — cannot dm (logged only); never fails the job");
+        deps.appendFile(deliveryLog, '{"delivered":false,"reason":"missing_owner"}\n');
+    }
+    let previous = {};
+    if (deps.exists(stateFile))
+        previous = JSON.parse(deps.readFile(stateFile));
+    const previousOutcome = previous.last_outcome == null ? "" : String(previous.last_outcome);
+    const previousFailureText = String(previous.last_failure_dm_epoch ?? 0);
+    const previousFailureEpoch = /^\d+$/.test(previousFailureText) ? Number(previousFailureText) : 0;
+    const kind = parsed.outcome === "ok"
+        ? previousOutcome === "failed" || previousOutcome === "blocked" ? "recovered" : "ok"
+        : previousOutcome === "failed" || previousOutcome === "blocked"
+            ? nowEpoch - previousFailureEpoch < collapseSec && previousFailureEpoch > 0 ? "suppressed" : "failed"
+            : "failed";
+    if (kind === "suppressed") {
+        log(`collapse: suppressing failure dm for job ${parsed.jobId} (within ${collapseSecText}s window)`);
+        const updatedAt = deps.now().toISOString().replace(/\.\d{3}Z$/, "Z");
+        deps.writeFile(stateFile, serializeJqJson({
+            last_outcome: parsed.outcome,
+            last_failure_dm_epoch: previousFailureEpoch,
+            last_updated_at: updatedAt,
+            last_failure_class: parsed.failureClass,
+            last_delivery: "suppressed",
+        }, "compact"));
+        try {
+            deps.chmod(stateFile, 0o600);
+        }
+        catch { /* chmod failure is ignored by the shell's `|| true`. */ }
+        deps.stdout(serializeJqJson({ delivered: false, reason: "collapsed_24h", channel_unimplemented: channelUnimplemented === 1 }, "compact"));
+        return 0;
+    }
+    const statusWord = kind === "recovered" ? "recovered" : parsed.outcome;
+    const classPart = parsed.failureClass && parsed.failureClass !== "null" ? ` class=${parsed.failureClass}` : "";
+    const actionPart = parsed.nextAction ? ` next: ${parsed.nextAction}` : "";
+    let headline;
+    if (kind === "ok" || kind === "recovered")
+        headline = `Scheduled job '${parsed.jobName}' ${kind} (${parsed.duration}s)`;
+    else
+        headline = `Scheduled job '${parsed.jobName}' ${statusWord}${classPart} (${parsed.duration}s)`;
+    const details = `job=${parsed.jobId}\nstatus=${statusWord}\nclassification=${parsed.failureClass || "none"}\nsummary=${parsed.summary}\nduration_seconds=${parsed.duration}\nlog=${parsed.logPath || "none"}${actionPart}`;
+    let delivered = 0;
+    let deliverRc;
+    let dmBin = deps.env.HQ_JOB_NOTIFY_DM_BIN || "";
+    if (!dmBin && deps.commandExists("hq"))
+        dmBin = "hq";
+    if (!owner) {
+        log("skip dm send — missing owner");
+        deliverRc = 1;
+    }
+    else if (!dmBin) {
+        log("skip dm send — hq CLI not found");
+        deliverRc = 1;
+    }
+    else {
+        const args = dmBin === "hq"
+            ? ["dm", owner, headline, "--details", details]
+            : [owner, headline, details];
+        deliverRc = deps.run(dmBin, args, { cwd: deps.cwd, env: deps.env, captureStdout: false, logPath: deliveryLog }).code;
+        if (deliverRc === 0) {
+            delivered = 1;
+            log(`dm delivered to ${owner} kind=${kind} job=${parsed.jobId}`);
+        }
+        else
+            log(`dm delivery failed rc=${deliverRc} job=${parsed.jobId} (logged; not failing run)`);
+    }
+    let failureDmEpoch = previousFailureEpoch;
+    if (kind === "failed" && delivered === 1)
+        failureDmEpoch = nowEpoch;
+    else if (kind === "ok" || kind === "recovered")
+        failureDmEpoch = 0;
+    const updatedAt = deps.now().toISOString().replace(/\.\d{3}Z$/, "Z");
+    deps.writeFile(stateFile, serializeJqJson({
+        last_outcome: parsed.outcome,
+        last_failure_dm_epoch: failureDmEpoch,
+        last_updated_at: updatedAt,
+        last_failure_class: parsed.failureClass,
+        last_delivery: kind,
+        last_delivered: delivered === 1,
+    }, "compact"));
+    try {
+        deps.chmod(stateFile, 0o600);
+    }
+    catch { /* chmod failure is ignored by the shell's `|| true`. */ }
+    deps.stdout(serializeJqJson({
+        delivered: delivered === 1,
+        kind,
+        owner,
+        channel_unimplemented: channelUnimplemented === 1,
+        deliver_rc: deliverRc,
+    }, "compact"));
+    return 0;
+}
+export function registerCoreJobNotifyNativeCommand(group, core) {
+    registerCoreJobLeaf(group, core, "notify", ASSET, "Send a scheduled-job status alert to its owner", (argv, hqRoot) => runJobNotify(argv, { hqRoot }), canUseLiveRootForArguments, [
+        "--hq-root", "--job-id", "--job-name", "--outcome", "--summary", "--duration", "--log-path",
+        "--failure-class", "--next-action", "--owner", "--notify",
+    ]);
+}
+//# sourceMappingURL=core-job-notify-native.js.map

package/dist/commands/core-job-remediate-native.d.ts

@@ -0,0 +1,26 @@
+/** Native TypeScript port of hq-job-remediate.sh. */
+import { Command } from "commander";
+type Environment = Record<string, string | undefined>;
+export type JobRemediateRunOptions = {
+    cwd: string;
+    env: Environment;
+    logPath: string;
+};
+export type JobRemediateDependencies = {
+    env: Environment;
+    cwd: string;
+    /** Guard seam: this command must never inspect credential file contents. */
+    readFile: (file: string) => string;
+    commandExists: (command: string) => boolean;
+    run: (command: string, args: string[], options: JobRemediateRunOptions) => number;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+};
+export declare function defaultJobRemediateDependencies(env?: Environment, cwd?: string): JobRemediateDependencies;
+export declare function runJobRemediate(argv: string[], options?: {
+    hqRoot?: string;
+    dependencies?: Partial<JobRemediateDependencies>;
+}): number;
+export declare function registerCoreJobRemediateNativeCommand(group: Command, core: Command): void;
+export {};
+//# sourceMappingURL=core-job-remediate-native.d.ts.map