maqcli 0.2.0

package/dist/core/exec.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Safe command execution.
+ *
+ * Uses spawn with an explicit argument array and shell:false so user/model
+ * provided values can never be interpreted by a shell. This is the single
+ * chokepoint for running worker CLIs and raw commands.
+ */
+export interface ExecOptions {
+    cwd?: string;
+    /** Milliseconds before the child is killed. */
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    /** Hard cap on captured output per stream to avoid unbounded memory. */
+    maxBuffer?: number;
+    /** Abort signal; kills the child when aborted. */
+    signal?: AbortSignal;
+}
+export interface ExecOutcome {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/**
+ * Run a command safely. `cmd` is the binary, `args` are passed verbatim.
+ * Never pass a full command string here — that is what enables injection.
+ */
+export declare function execSafe(cmd: string, args?: string[], opts?: ExecOptions): Promise<ExecOutcome>;
+/** A single line of worker output, tagged by stream. */
+export interface StreamLine {
+    stream: "stdout" | "stderr";
+    line: string;
+}
+export interface StreamOptions extends ExecOptions {
+    /** Called for every complete line the worker emits (real-time). */
+    onLine?: (l: StreamLine) => void;
+}
+/**
+ * Run a command and stream its output line-by-line via `onLine`, in real time,
+ * while still capturing the full transcript for the returned outcome. Same
+ * safety guarantees as execSafe: shell:false, explicit argument array.
+ */
+export declare function execStream(cmd: string, args?: string[], opts?: StreamOptions): Promise<ExecOutcome>;

package/dist/core/exec.js

@@ -0,0 +1,154 @@
+/**
+ * Safe command execution.
+ *
+ * Uses spawn with an explicit argument array and shell:false so user/model
+ * provided values can never be interpreted by a shell. This is the single
+ * chokepoint for running worker CLIs and raw commands.
+ */
+import { spawn } from "node:child_process";
+/**
+ * Run a command safely. `cmd` is the binary, `args` are passed verbatim.
+ * Never pass a full command string here — that is what enables injection.
+ */
+export function execSafe(cmd, args = [], opts = {}) {
+    const maxBuffer = opts.maxBuffer ?? 10 * 1024 * 1024;
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd ?? process.cwd(),
+            env: opts.env ?? process.env,
+            shell: false,
+            windowsHide: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let killed = false;
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                killed = true;
+                child.kill("SIGKILL");
+            }, opts.timeoutMs)
+            : null;
+        // Abort support: kill the child when the caller's signal fires (parity with
+        // execStream). Without this, a cancelled session could not stop a
+        // non-streaming worker (verify test-runner, the /v1/exec runner, …).
+        const onAbort = () => {
+            killed = true;
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        if (opts.signal) {
+            if (opts.signal.aborted)
+                onAbort();
+            else
+                opts.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        child.stdout?.on("data", (d) => {
+            if (stdout.length < maxBuffer)
+                stdout += d.toString();
+        });
+        child.stderr?.on("data", (d) => {
+            if (stderr.length < maxBuffer)
+                stderr += d.toString();
+        });
+        child.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onAbort);
+            resolve({ code: null, stdout, stderr: stderr + String(err), timedOut });
+        });
+        child.on("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onAbort);
+            resolve({ code: killed ? null : code, stdout, stderr, timedOut });
+        });
+    });
+}
+/**
+ * Run a command and stream its output line-by-line via `onLine`, in real time,
+ * while still capturing the full transcript for the returned outcome. Same
+ * safety guarantees as execSafe: shell:false, explicit argument array.
+ */
+export function execStream(cmd, args = [], opts = {}) {
+    const maxBuffer = opts.maxBuffer ?? 20 * 1024 * 1024;
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd ?? process.cwd(),
+            env: opts.env ?? process.env,
+            shell: false,
+            windowsHide: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let outBuf = "";
+        let errBuf = "";
+        let timedOut = false;
+        let killed = false;
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                killed = true;
+                child.kill("SIGKILL");
+            }, opts.timeoutMs)
+            : null;
+        const onAbort = () => {
+            killed = true;
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        if (opts.signal) {
+            if (opts.signal.aborted)
+                onAbort();
+            else
+                opts.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        const pump = (chunk, which) => {
+            let buf = (which === "stdout" ? outBuf : errBuf) + chunk;
+            const parts = buf.split(/\r?\n/);
+            buf = parts.pop() ?? "";
+            if (which === "stdout")
+                outBuf = buf;
+            else
+                errBuf = buf;
+            for (const line of parts)
+                opts.onLine?.({ stream: which, line });
+        };
+        child.stdout?.on("data", (d) => {
+            const s = d.toString();
+            if (stdout.length < maxBuffer)
+                stdout += s;
+            pump(s, "stdout");
+        });
+        child.stderr?.on("data", (d) => {
+            const s = d.toString();
+            if (stderr.length < maxBuffer)
+                stderr += s;
+            pump(s, "stderr");
+        });
+        child.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({ code: null, stdout, stderr: stderr + String(err), timedOut });
+        });
+        child.on("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onAbort);
+            if (outBuf)
+                opts.onLine?.({ stream: "stdout", line: outBuf });
+            if (errBuf)
+                opts.onLine?.({ stream: "stderr", line: errBuf });
+            resolve({ code: killed ? null : code, stdout, stderr, timedOut });
+        });
+    });
+}

package/dist/core/flows.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Flows — scheduled agent sessions (CAO-style, dependency-free). A flow pairs a
+ * task with a simple schedule and (optionally) a target/profile. Flows persist
+ * to `~/.maqcli/flows.json`; a Scheduler ticks them on the daemon.
+ *
+ * Schedule grammar (kept intentionally small, not full cron):
+ *   "@hourly" | "@daily" | "@weekly"
+ *   "every 30m" | "every 2h" | "every 45s"
+ * `nextRun(schedule, from)` returns the next Date; a real cron parser can slot
+ * in behind it later.
+ */
+export interface Flow {
+    name: string;
+    schedule: string;
+    task: string;
+    target?: string;
+    profile?: string;
+    cwd?: string;
+    enabled: boolean;
+}
+export declare function loadFlows(): Flow[];
+export declare function saveFlows(flows: Flow[]): void;
+export declare function addFlow(flow: Flow): Flow[];
+export declare function removeFlow(name: string): Flow[];
+/** Parse a schedule to a millisecond interval, or null if invalid. */
+export declare function scheduleMs(schedule: string): number | null;
+export declare function nextRun(schedule: string, from?: Date): Date | null;
+/** Ticks enabled flows on their interval, invoking `run(flow)` each time. */
+export declare class Scheduler {
+    private run;
+    private log?;
+    private timers;
+    constructor(run: (flow: Flow) => void, log?: ((msg: string) => void) | undefined);
+    start(flows?: Flow[]): void;
+    stop(): void;
+}

package/dist/core/flows.js

@@ -0,0 +1,96 @@
+/**
+ * Flows — scheduled agent sessions (CAO-style, dependency-free). A flow pairs a
+ * task with a simple schedule and (optionally) a target/profile. Flows persist
+ * to `~/.maqcli/flows.json`; a Scheduler ticks them on the daemon.
+ *
+ * Schedule grammar (kept intentionally small, not full cron):
+ *   "@hourly" | "@daily" | "@weekly"
+ *   "every 30m" | "every 2h" | "every 45s"
+ * `nextRun(schedule, from)` returns the next Date; a real cron parser can slot
+ * in behind it later.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+function flowsPath() {
+    const dir = process.env.MAQ_CONFIG_DIR ?? join(homedir(), ".maqcli");
+    return join(dir, "flows.json");
+}
+export function loadFlows() {
+    const p = flowsPath();
+    if (!existsSync(p))
+        return [];
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+export function saveFlows(flows) {
+    const p = flowsPath();
+    mkdirSync(join(p, ".."), { recursive: true });
+    writeFileSync(p, JSON.stringify(flows, null, 2), "utf8");
+}
+export function addFlow(flow) {
+    const flows = loadFlows().filter((f) => f.name !== flow.name);
+    flows.push(flow);
+    saveFlows(flows);
+    return flows;
+}
+export function removeFlow(name) {
+    const flows = loadFlows().filter((f) => f.name !== name);
+    saveFlows(flows);
+    return flows;
+}
+/** Parse a schedule to a millisecond interval, or null if invalid. */
+export function scheduleMs(schedule) {
+    const s = schedule.trim().toLowerCase();
+    if (s === "@hourly")
+        return 3600_000;
+    if (s === "@daily")
+        return 86_400_000;
+    if (s === "@weekly")
+        return 604_800_000;
+    const m = /^every\s+(\d+)\s*([smhd])$/.exec(s);
+    if (m) {
+        const n = Number(m[1]);
+        const unit = { s: 1000, m: 60_000, h: 3600_000, d: 86_400_000 }[m[2]];
+        return n * unit;
+    }
+    return null;
+}
+export function nextRun(schedule, from = new Date()) {
+    const ms = scheduleMs(schedule);
+    return ms === null ? null : new Date(from.getTime() + ms);
+}
+/** Ticks enabled flows on their interval, invoking `run(flow)` each time. */
+export class Scheduler {
+    run;
+    log;
+    timers = [];
+    constructor(run, log) {
+        this.run = run;
+        this.log = log;
+    }
+    start(flows = loadFlows()) {
+        this.stop();
+        for (const flow of flows) {
+            if (!flow.enabled)
+                continue;
+            const ms = scheduleMs(flow.schedule);
+            if (ms === null) {
+                this.log?.(`flow '${flow.name}': invalid schedule '${flow.schedule}', skipped`);
+                continue;
+            }
+            const timer = setInterval(() => this.run(flow), ms);
+            this.timers.push(timer);
+            this.log?.(`flow '${flow.name}': scheduled ${flow.schedule} (every ${ms}ms)`);
+        }
+    }
+    stop() {
+        for (const t of this.timers)
+            clearInterval(t);
+        this.timers = [];
+    }
+}

package/dist/core/headroom.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Headroom-style context compression (local, reversible).
+ *
+ * This is a lightweight, dependency-free implementation of the pattern used by
+ * Headroom (github.com/headroomlabs-ai/headroom): compress verbose tool output
+ * / logs / file reads before they reach a model, while keeping the original
+ * retrievable on demand (Compress-Cache-Retrieve). It is intentionally
+ * conservative — lossless-ish transforms only — so it is safe to enable by
+ * default. The real product can swap this for the upstream engine.
+ */
+export interface CompressionResult {
+    compressed: string;
+    originalTokensEst: number;
+    compressedTokensEst: number;
+    ratio: number;
+    /** Retrieval handle for the original content. */
+    ref: string;
+}
+/** Rough token estimate: ~4 chars/token, good enough for budgeting. */
+export declare function estimateTokens(text: string): number;
+export declare class Headroom {
+    private store;
+    /** Compress a blob of text and cache the original for retrieval. */
+    compress(content: string): CompressionResult;
+    /** Retrieve the original content by reference (the escape hatch). */
+    retrieve(ref: string): string | undefined;
+    size(): number;
+    /**
+     * Conservative, reversible-in-spirit transforms:
+     *  - collapse runs of blank lines
+     *  - trim trailing whitespace
+     *  - collapse long runs of repeated lines into a "(xN)" marker
+     *  - re-serialize JSON compactly when the whole blob parses as JSON
+     */
+    private transform;
+}

package/dist/core/headroom.js

@@ -0,0 +1,88 @@
+/**
+ * Headroom-style context compression (local, reversible).
+ *
+ * This is a lightweight, dependency-free implementation of the pattern used by
+ * Headroom (github.com/headroomlabs-ai/headroom): compress verbose tool output
+ * / logs / file reads before they reach a model, while keeping the original
+ * retrievable on demand (Compress-Cache-Retrieve). It is intentionally
+ * conservative — lossless-ish transforms only — so it is safe to enable by
+ * default. The real product can swap this for the upstream engine.
+ */
+import { createHash } from "node:crypto";
+/** Rough token estimate: ~4 chars/token, good enough for budgeting. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export class Headroom {
+    store = new Map();
+    /** Compress a blob of text and cache the original for retrieval. */
+    compress(content) {
+        const ref = "hr_" + createHash("sha256").update(content).digest("hex").slice(0, 16);
+        this.store.set(ref, content);
+        const compressed = this.transform(content);
+        const originalTokensEst = estimateTokens(content);
+        const compressedTokensEst = estimateTokens(compressed);
+        return {
+            compressed,
+            originalTokensEst,
+            compressedTokensEst,
+            ratio: originalTokensEst === 0 ? 1 : compressedTokensEst / originalTokensEst,
+            ref,
+        };
+    }
+    /** Retrieve the original content by reference (the escape hatch). */
+    retrieve(ref) {
+        return this.store.get(ref);
+    }
+    size() {
+        return this.store.size;
+    }
+    /**
+     * Conservative, reversible-in-spirit transforms:
+     *  - collapse runs of blank lines
+     *  - trim trailing whitespace
+     *  - collapse long runs of repeated lines into a "(xN)" marker
+     *  - re-serialize JSON compactly when the whole blob parses as JSON
+     */
+    transform(content) {
+        const trimmed = content.trim();
+        // JSON: compact it (drops insignificant whitespace only).
+        if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+            (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
+            try {
+                return JSON.stringify(JSON.parse(trimmed));
+            }
+            catch {
+                /* fall through to text handling */
+            }
+        }
+        const lines = content.split(/\r?\n/).map((l) => l.replace(/[ \t]+$/g, ""));
+        const out = [];
+        let blankRun = 0;
+        let i = 0;
+        while (i < lines.length) {
+            const line = lines[i];
+            if (line === "") {
+                blankRun++;
+                if (blankRun <= 1)
+                    out.push("");
+                i++;
+                continue;
+            }
+            blankRun = 0;
+            // Collapse consecutive identical non-blank lines.
+            let repeat = 1;
+            while (i + repeat < lines.length && lines[i + repeat] === line)
+                repeat++;
+            if (repeat >= 3) {
+                out.push(`${line}  (x${repeat})`);
+            }
+            else {
+                for (let k = 0; k < repeat; k++)
+                    out.push(line);
+            }
+            i += repeat;
+        }
+        return out.join("\n");
+    }
+}

package/dist/core/help-topics.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module help-topics
+ *
+ * Conceptual help system for `maq help <topic>`.
+ * Provides detailed reference content for core maq concepts
+ * including the pipeline, permissions, routing, board, skills,
+ * providers, safety, and audit subsystems.
+ *
+ * Zero npm dependencies. ESM module.
+ */
+/** A single help topic with its name, display title, and prose content. */
+export interface HelpTopic {
+    name: string;
+    title: string;
+    content: string;
+}
+/** Returns a shallow copy of all available help topics. */
+export declare function listTopics(): HelpTopic[];
+/** Looks up a topic by name (case-insensitive). Returns `null` if not found. */
+export declare function getTopic(name: string): HelpTopic | null;
+/**
+ * Renders a topic as a formatted string suitable for terminal output.
+ * The title is displayed with an underline, followed by word-wrapped
+ * paragraphs of the content body.
+ */
+export declare function renderTopic(topic: HelpTopic): string;