harnery 0.34.1 → 0.36.0

package/dist/core/storage/sink-graph.js

@@ -0,0 +1,213 @@
+export class HarnerySinkGraphError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "HarnerySinkGraphError";
+    }
+}
+export class HarnerySinkDeliveryError extends Error {
+    code;
+    sink_id;
+    cause;
+    constructor(code, sink_id, message, cause) {
+        super(message);
+        this.code = code;
+        this.sink_id = sink_id;
+        this.cause = cause;
+        this.name = "HarnerySinkDeliveryError";
+    }
+}
+const ID = /^[a-z][a-z0-9._-]{0,63}$/;
+export class HarnerySinkGraph {
+    sinks;
+    edges;
+    #byId;
+    #outgoing;
+    #maxDeliveries;
+    constructor(sinks, edges, options = {}) {
+        const limits = {
+            max_sinks: positive(options.max_sinks ?? 32, "max_sinks"),
+            max_edges: positive(options.max_edges ?? 128, "max_edges"),
+            max_fanout: positive(options.max_fanout ?? 8, "max_fanout"),
+            max_deliveries: positive(options.max_deliveries ?? 64, "max_deliveries"),
+        };
+        if (sinks.length > limits.max_sinks || edges.length > limits.max_edges) {
+            throw new HarnerySinkGraphError("graph_limit", "sink graph exceeds its construction limit");
+        }
+        const sinkCopies = sinks.map((sink) => Object.freeze({ ...sink }));
+        const byId = new Map();
+        for (const sink of sinkCopies) {
+            if (!ID.test(sink.id) || typeof sink.deliver !== "function") {
+                throw new HarnerySinkGraphError("invalid_sink", `invalid sink: ${sink.id}`);
+            }
+            if (byId.has(sink.id)) {
+                throw new HarnerySinkGraphError("duplicate_sink", `duplicate sink: ${sink.id}`);
+            }
+            if (sink.captures?.origin === "cli-emission") {
+                throw new HarnerySinkGraphError("cli_emission_capture", `sink ${sink.id} cannot capture CLI emission`);
+            }
+            byId.set(sink.id, sink);
+        }
+        const edgeCopies = edges.map((edge) => Object.freeze({ ...edge }));
+        const outgoing = new Map();
+        const edgeKeys = new Set();
+        for (const edge of edgeCopies) {
+            if (!byId.has(edge.from) || !byId.has(edge.to)) {
+                throw new HarnerySinkGraphError("unknown_sink", `sink edge references an unknown sink: ${edge.from}->${edge.to}`);
+            }
+            if (edge.from === edge.to) {
+                throw new HarnerySinkGraphError("self_edge", `sink ${edge.from} cannot route ${edge.kind} delivery through itself`);
+            }
+            if (!new Set(["primary", "diagnostic", "fallback"]).has(edge.kind)) {
+                throw new HarnerySinkGraphError("invalid_sink", `invalid sink edge kind: ${edge.kind}`);
+            }
+            const key = `${edge.from}\0${edge.to}\0${edge.kind}`;
+            if (edgeKeys.has(key)) {
+                throw new HarnerySinkGraphError("duplicate_edge", `duplicate sink edge: ${edge.from}->${edge.to}`);
+            }
+            edgeKeys.add(key);
+            const next = [...(outgoing.get(edge.from) ?? []), edge];
+            if (next.length > limits.max_fanout) {
+                throw new HarnerySinkGraphError("fanout_limit", `sink ${edge.from} exceeds fan-out limit`);
+            }
+            outgoing.set(edge.from, Object.freeze(next));
+        }
+        rejectCycles(byId, outgoing);
+        rejectCaptureLoops(byId, outgoing);
+        this.sinks = Object.freeze(sinkCopies);
+        this.edges = Object.freeze(edgeCopies);
+        this.#byId = byId;
+        this.#outgoing = outgoing;
+        this.#maxDeliveries = limits.max_deliveries;
+        Object.freeze(this);
+    }
+    async deliver(entrySinkId, record) {
+        if (!this.#byId.has(entrySinkId)) {
+            throw new HarnerySinkGraphError("unknown_sink", `unknown entry sink: ${entrySinkId}`);
+        }
+        if (record.origin === "cli-emission") {
+            throw new HarnerySinkGraphError("cli_emission_capture", "CLI emission is not a structured sink record");
+        }
+        const queue = [{ sink_id: entrySinkId, route: "entry", record }];
+        const visited = new Set();
+        const delivered = [];
+        const failures = [];
+        let attempted = 0;
+        let truncated = false;
+        while (queue.length > 0) {
+            const next = queue.shift();
+            const visitKey = `${next.sink_id}\0${next.route}`;
+            if (visited.has(visitKey))
+                continue;
+            if (attempted >= this.#maxDeliveries) {
+                truncated = true;
+                failures.push(deliveryFailure("delivery_budget_exhausted", next, undefined));
+                break;
+            }
+            visited.add(visitKey);
+            attempted += 1;
+            const sink = this.#byId.get(next.sink_id);
+            try {
+                await sink.deliver({
+                    ...next.record,
+                    entry_sink_id: entrySinkId,
+                    sink_id: next.sink_id,
+                    route: next.route,
+                    ...(next.source_sink_id ? { source_sink_id: next.source_sink_id } : {}),
+                });
+                delivered.push(next.sink_id);
+                if (next.route === "entry" || next.route === "primary") {
+                    enqueueEdges(queue, this.#outgoing.get(next.sink_id), "primary", next.record);
+                }
+            }
+            catch (error) {
+                const failure = deliveryFailure("sink_delivery_failed", next, error);
+                failures.push(failure);
+                // Recovery lanes are terminal. Their failures remain typed return data
+                // and never emit another diagnostic through this graph.
+                if (next.route === "entry" || next.route === "primary") {
+                    enqueueEdges(queue, this.#outgoing.get(next.sink_id), "diagnostic", {
+                        origin: "structured-log",
+                        payload: failure,
+                    });
+                    enqueueEdges(queue, this.#outgoing.get(next.sink_id), "fallback", next.record);
+                }
+            }
+        }
+        return Object.freeze({
+            attempted,
+            delivered: Object.freeze(delivered),
+            failures: Object.freeze(failures),
+            truncated,
+        });
+    }
+}
+function enqueueEdges(queue, edges, kind, record) {
+    for (const edge of edges ?? []) {
+        if (edge.kind !== kind)
+            continue;
+        queue.push({ sink_id: edge.to, route: kind, source_sink_id: edge.from, record });
+    }
+}
+function deliveryFailure(code, delivery, cause) {
+    const error = new HarnerySinkDeliveryError(code, delivery.sink_id, code === "sink_delivery_failed"
+        ? `sink delivery failed: ${delivery.sink_id}`
+        : `sink delivery budget exhausted before ${delivery.sink_id}`, cause);
+    return Object.freeze({ code, sink_id: delivery.sink_id, route: delivery.route, error });
+}
+function rejectCycles(sinks, outgoing) {
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (id) => {
+        if (visiting.has(id))
+            throw new HarnerySinkGraphError("cycle", `sink graph cycle at ${id}`);
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const edge of outgoing.get(id) ?? [])
+            visit(edge.to);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const id of sinks.keys())
+        visit(id);
+}
+function rejectCaptureLoops(sinks, outgoing) {
+    for (const sink of sinks.values()) {
+        const capture = sink.captures;
+        if (!capture || capture.origin === "cli-emission")
+            continue;
+        if (!capture.origin_sink_id) {
+            throw new HarnerySinkGraphError("capture_origin_invalid", `capturing sink ${sink.id} must name its origin sink`);
+        }
+        const origin = sinks.get(capture.origin_sink_id);
+        if (!origin || origin.emits_stream !== capture.origin) {
+            throw new HarnerySinkGraphError("capture_origin_invalid", `capturing sink ${sink.id} has an invalid ${capture.origin} origin`);
+        }
+        if (sink.id === origin.id || reachable(sink.id, origin.id, outgoing)) {
+            throw new HarnerySinkGraphError("capture_loop", `captured ${capture.origin} from ${origin.id} routes back through ${sink.id}`);
+        }
+    }
+}
+function reachable(from, target, outgoing) {
+    const pending = [from];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === target)
+            return true;
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        for (const edge of outgoing.get(current) ?? [])
+            pending.push(edge.to);
+    }
+    return false;
+}
+function positive(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new HarnerySinkGraphError("graph_limit", `${name} must be a positive safe integer`);
+    }
+    return value;
+}

package/dist/core/storage/storm-control.d.ts

@@ -0,0 +1,23 @@
+import type { HarneryLogLevel } from "./contract.js";
+export interface HarneryStormSummary {
+    key: string;
+    count: number;
+    represented_bytes: number;
+    first_emitted_at: string;
+    last_emitted_at: string;
+    exemplar_digests: readonly string[];
+}
+export interface ProcessStormControllerOptions {
+    enabled: boolean;
+    window_ms: number;
+    max_exemplars: number;
+    burst?: number;
+    now?: () => number;
+}
+export declare class ProcessStormController {
+    #private;
+    constructor(options: ProcessStormControllerOptions);
+    admit(key: string, level: HarneryLogLevel, bytes: number): boolean;
+    drainSummaries(force?: boolean): HarneryStormSummary[];
+}
+//# sourceMappingURL=storm-control.d.ts.map

package/dist/core/storage/storm-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storm-control.d.ts","sourceRoot":"","sources":["../../../src/core/storage/storm-control.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAYD,qBAAa,sBAAsB;;gBAIrB,OAAO,EAAE,6BAA6B;IAIlD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAiClE,cAAc,CAAC,KAAK,UAAQ,GAAG,mBAAmB,EAAE;CAmBrD"}

package/dist/core/storage/storm-control.js

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+export class ProcessStormController {
+    #options;
+    #buckets = new Map();
+    constructor(options) {
+        this.#options = { ...options, burst: options.burst ?? 100, now: options.now ?? Date.now };
+    }
+    admit(key, level, bytes) {
+        if (!this.#options.enabled || level === "error" || level === "fatal")
+            return true;
+        const now = this.#options.now();
+        let bucket = this.#buckets.get(key);
+        if (!bucket || now - bucket.started >= this.#options.window_ms) {
+            bucket = {
+                started: now,
+                admitted: 0,
+                dropped: 0,
+                representedBytes: 0,
+                first: new Date(now).toISOString(),
+                last: new Date(now).toISOString(),
+                exemplars: [],
+            };
+            this.#buckets.set(key, bucket);
+        }
+        if (bucket.admitted < this.#options.burst) {
+            bucket.admitted += 1;
+            return true;
+        }
+        bucket.dropped += 1;
+        bucket.representedBytes += bytes;
+        bucket.last = new Date(now).toISOString();
+        const digest = createHash("sha256").update(`${key}:${bytes}`).digest("hex").slice(0, 16);
+        if (bucket.exemplars.length < this.#options.max_exemplars &&
+            !bucket.exemplars.includes(digest)) {
+            bucket.exemplars.push(digest);
+        }
+        return false;
+    }
+    drainSummaries(force = false) {
+        const now = this.#options.now();
+        const summaries = [];
+        for (const [key, bucket] of this.#buckets) {
+            if (!force && now - bucket.started < this.#options.window_ms)
+                continue;
+            if (bucket.dropped > 0) {
+                summaries.push({
+                    key,
+                    count: bucket.dropped,
+                    represented_bytes: bucket.representedBytes,
+                    first_emitted_at: bucket.first,
+                    last_emitted_at: bucket.last,
+                    exemplar_digests: bucket.exemplars,
+                });
+            }
+            this.#buckets.delete(key);
+        }
+        return summaries;
+    }
+}

package/dist/core/work/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/core/work/state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/core/work/state.ts"],"names":[],"mappings":"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"}

package/dist/core/work/state.js

@@ -1,7 +1,8 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { appendFileSync, chmodSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { hostname } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { appendSegmentedJsonlFile, readSegmentedJsonlFileSync, } from "../storage/durable-history.js";
 import { readWorkflowApproval } from "../workflow/approvals.js";
 import { stableDigest } from "../workflow/durable-record.js";
 import { readWorkflowProof } from "../workflow/proof.js";
@@ -674,8 +675,6 @@ function appendWorkEventUnderLease(coordRoot, workId, input) {
         });
         return appendWorkEventUnderLease(coordRoot, workId, input);
     }
-    if (events.length >= MAX_EVENTS)
-        throw new Error(`work item ${workId} exceeds ${MAX_EVENTS} events`);
     const event = {
         schema_version: WORK_EVENT_SCHEMA_VERSION,
         work_id: workId,
@@ -688,13 +687,10 @@ function appendWorkEventUnderLease(coordRoot, workId, input) {
     if (Buffer.byteLength(line) > MAX_EVENT_BYTES) {
         throw new Error(`work event exceeds ${MAX_EVENT_BYTES} bytes`);
     }
-    const path = join(workDir(coordRoot, workId), "events.jsonl");
-    const existingBytes = existsSync(path) ? statSync(path).size : 0;
-    if (existingBytes + Buffer.byteLength(line) > MAX_EVENTS_BYTES) {
-        throw new Error("work event log would exceed its limit");
-    }
-    appendFileSync(path, line, { encoding: "utf8", mode: 0o600 });
-    chmodSync(path, 0o600);
+    appendSegmentedJsonlFile(join(workDir(coordRoot, workId), "events.jsonl"), event, {
+        max_record_bytes: MAX_EVENT_BYTES,
+        max_segment_bytes: MAX_EVENTS_BYTES,
+    });
     return event;
 }
 function readWorkIntent(coordRoot, workId) {
@@ -712,10 +708,10 @@ function readWorkIntent(coordRoot, workId) {
 function readWorkEvents(coordRoot, workId) {
     assertWorkId(workId);
     const path = join(workDir(coordRoot, workId), "events.jsonl");
-    if (!existsSync(path))
-        return [];
-    const events = readBoundedLines(path, MAX_EVENTS_BYTES, MAX_EVENT_BYTES, `work item ${workId} events`).map((line, index) => {
-        const event = parseObject(line, `work item ${workId} event ${index + 1}`);
+    const events = readSegmentedJsonlFileSync(path, {
+        max_record_bytes: MAX_EVENT_BYTES,
+        max_records: 1_000_000,
+    }).map((event, index) => {
         validateWorkEvent(event, workId, index + 1);
         return event;
     });

package/dist/core/workflow/live-session-v3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"live-session-v3.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/live-session-v3.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,SAAS,EAEf,MAAM,qCAAqC,CAAC;AAY7C,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8FAA8F;AAC9F,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,2BAA2B,GAAG,SAAS,CAqDzF;AAED,2FAA2F;AAC3F,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,2BAA2B,GAAG;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAC1D,IAAI,CAmBN;AAiBD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"live-session-v3.d.ts","sourceRoot":"","sources":["../../../src/core/workflow/live-session-v3.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,SAAS,EAEf,MAAM,qCAAqC,CAAC;AAU7C,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8FAA8F;AAC9F,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,2BAA2B,GAAG,SAAS,CAqDzF;AAED,2FAA2F;AAC3F,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,2BAA2B,GAAG;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAC1D,IAAI,CAmBN;AAiBD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/workflow/live-session-v3.js

@@ -1,7 +1,8 @@
 import { recordLiveTaskChangeV3 } from "../agents/live-authority-v3.js";
 import { endSessionExplicitV3 } from "../agents/session-finalizer-v3.js";
 import { clearCoordinationCache, setIdentityCache, } from "../agents/state/heartbeat-writer.js";
-import { ensureLiveCoordinationHeartbeat, readLiveCoordinationRow, } from "../agents/state/live-coordination-view.js";
+import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.js";
+import { ensureLiveCoordinationHeartbeat } from "../agents/state/live-coordination-writer.js";
 import { ensureEventLedgerV3 } from "../events/v3/bootstrap.js";
 import { recordLiveHookSignalV3, resolveLiveEventLedgerRouteV3, } from "../events/v3/live-routing.js";
 import { stableScopeId } from "./scope-id.js";

package/dist/index.d.ts

@@ -12,4 +12,6 @@
  */
 export type { HarneryContextOpts, HarneryProgramContext } from "./commander.js";
 export { createHarneryProgram } from "./commander.js";
+export * from "./core/conversations/index.js";
+export * from "./core/inbox/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -11,3 +11,5 @@
  * reachable via their own subpath entries in package.json#exports.
  */
 export { createHarneryProgram } from "./commander.js";
+export * from "./core/conversations/index.js";
+export * from "./core/inbox/index.js";

package/dist/lazy-commands.d.ts

@@ -0,0 +1,26 @@
+import { type Command } from "commander";
+export interface LazyCommandDefinition {
+    /** Commander signature, including any top-level positional arguments. */
+    command: string;
+    description: string;
+    aliases?: readonly string[];
+    hidden?: boolean;
+    /** Preserve the `[options]` marker in root help without loading the implementation. */
+    hasOptions?: boolean;
+}
+export interface LazyCommandBundle {
+    commands: readonly LazyCommandDefinition[];
+    load(program: Command): void | Promise<void>;
+}
+/**
+ * Add lightweight top-level command placeholders whose implementations load
+ * immediately before Commander parses the selected command.
+ */
+export declare function registerLazyCommandBundles(program: Command, definitions: readonly LazyCommandBundle[]): Command;
+/** Load one top-level command by canonical name or alias. */
+export declare function loadLazyCommand(program: Command, name: string): Promise<Command | undefined>;
+/** Materialize every remaining lazy bundle, for whole-tree discovery and completion. */
+export declare function loadAllLazyCommands(program: Command): Promise<Command>;
+/** Run a host hook after a named lazy command becomes concrete. */
+export declare function onLazyCommandLoaded(program: Command, name: string, hook: (program: Command) => void | Promise<void>): Promise<void>;
+//# sourceMappingURL=lazy-commands.d.ts.map

package/dist/lazy-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-commands.d.ts","sourceRoot":"","sources":["../src/lazy-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAA6B,MAAM,WAAW,CAAC;AAIpE,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC3C,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAkBD;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,OAAO,CA+BT;AAED,6DAA6D;AAC7D,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAM9B;AAED,wFAAwF;AACxF,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAK5E;AAED,mEAAmE;AACnE,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC/C,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/lazy-commands.js

@@ -0,0 +1,210 @@
+import { Option } from "commander";
+const lazyState = Symbol("harnery.lazy-command-state");
+/**
+ * Add lightweight top-level command placeholders whose implementations load
+ * immediately before Commander parses the selected command.
+ */
+export function registerLazyCommandBundles(program, definitions) {
+    const state = stateFor(program);
+    for (const definition of definitions) {
+        const registered = {
+            definition,
+            placeholders: new Map(),
+            status: "placeholder",
+        };
+        for (const metadata of definition.commands) {
+            const name = commandName(metadata.command);
+            const claimedNames = [name, ...(metadata.aliases ?? [])];
+            for (const claimedName of claimedNames) {
+                if (state.byName.has(claimedName) || findCommand(program, claimedName)) {
+                    throw new Error(`Cannot register lazy command "${claimedName}": name already exists`);
+                }
+            }
+            const placeholder = program
+                .command(metadata.command, { hidden: metadata.hidden === true })
+                .description(metadata.description);
+            for (const alias of metadata.aliases ?? [])
+                placeholder.alias(alias);
+            if (metadata.hasOptions) {
+                placeholder.addOption(new Option("--__lazy-command-placeholder").hideHelp());
+            }
+            registered.placeholders.set(name, placeholder);
+            for (const claimedName of claimedNames)
+                state.byName.set(claimedName, registered);
+        }
+        state.bundles.push(registered);
+    }
+    return program;
+}
+/** Load one top-level command by canonical name or alias. */
+export async function loadLazyCommand(program, name) {
+    const state = getState(program);
+    const bundle = state?.byName.get(name);
+    if (!state || !bundle)
+        return findCommand(program, name);
+    await loadBundle(program, state, bundle);
+    return findCommand(program, name);
+}
+/** Materialize every remaining lazy bundle, for whole-tree discovery and completion. */
+export async function loadAllLazyCommands(program) {
+    const state = getState(program);
+    if (!state)
+        return program;
+    for (const bundle of state.bundles)
+        await loadBundle(program, state, bundle);
+    return program;
+}
+/** Run a host hook after a named lazy command becomes concrete. */
+export async function onLazyCommandLoaded(program, name, hook) {
+    const state = getState(program);
+    const bundle = state?.byName.get(name);
+    if (!state || !bundle || bundle.status === "loaded") {
+        await hook(program);
+        return;
+    }
+    const hooks = state.hooks.get(name) ?? [];
+    hooks.push(hook);
+    state.hooks.set(name, hooks);
+}
+function stateFor(program) {
+    const existing = getState(program);
+    if (existing)
+        return existing;
+    const originalParse = program.parse;
+    const originalParseAsync = program.parseAsync;
+    const state = {
+        bundles: [],
+        byName: new Map(),
+        hooks: new Map(),
+        originalParse,
+        originalParseAsync,
+    };
+    Object.defineProperty(program, lazyState, { value: state });
+    program.parseAsync = async function lazyParseAsync(argv, parseOptions) {
+        const selected = selectedCommand(program, state, argv, parseOptions);
+        if (selected)
+            await loadBundle(program, state, selected);
+        return originalParseAsync.call(this, argv, parseOptions);
+    };
+    program.parse = function lazyParse(argv, parseOptions) {
+        const selected = selectedCommand(program, state, argv, parseOptions);
+        if (selected && selected.status !== "loaded") {
+            throw new Error(`Command "${selected.definition.commands[0]?.command ?? "unknown"}" loads asynchronously; use parseAsync()`);
+        }
+        return originalParse.call(this, argv, parseOptions);
+    };
+    return state;
+}
+function getState(program) {
+    return program[lazyState];
+}
+async function loadBundle(program, state, bundle) {
+    if (bundle.status === "loaded" || bundle.status === "loading")
+        return;
+    bundle.status = "loading";
+    const positions = new Map();
+    for (const [name, placeholder] of bundle.placeholders) {
+        const index = program.commands.indexOf(placeholder);
+        if (index >= 0)
+            positions.set(name, index);
+    }
+    for (const placeholder of [...bundle.placeholders.values()].sort((a, b) => program.commands.indexOf(b) - program.commands.indexOf(a))) {
+        const index = program.commands.indexOf(placeholder);
+        if (index >= 0)
+            mutableCommands(program).splice(index, 1);
+    }
+    const commandsBefore = new Set(program.commands);
+    try {
+        await bundle.definition.load(program);
+        for (const metadata of bundle.definition.commands) {
+            const name = commandName(metadata.command);
+            const concrete = program.commands.find((candidate) => !commandsBefore.has(candidate) && candidate.name() === name);
+            if (!concrete) {
+                throw new Error(`Lazy command loader did not register "${name}"`);
+            }
+        }
+        restoreCommandOrder(program, bundle, positions);
+        bundle.status = "loaded";
+        for (const metadata of bundle.definition.commands) {
+            const name = commandName(metadata.command);
+            for (const hook of state.hooks.get(name) ?? [])
+                await hook(program);
+            state.hooks.delete(name);
+        }
+    }
+    catch (error) {
+        for (let index = program.commands.length - 1; index >= 0; index--) {
+            if (!commandsBefore.has(program.commands[index]))
+                mutableCommands(program).splice(index, 1);
+        }
+        restorePlaceholders(program, bundle, positions);
+        bundle.status = "placeholder";
+        throw error;
+    }
+}
+function restoreCommandOrder(program, bundle, positions) {
+    const ordered = bundle.definition.commands
+        .map((metadata) => {
+        const name = commandName(metadata.command);
+        const command = findCommand(program, name);
+        const position = positions.get(name);
+        return command && position !== undefined ? { command, position } : undefined;
+    })
+        .filter((entry) => entry !== undefined)
+        .sort((a, b) => a.position - b.position);
+    for (const { command } of ordered) {
+        const index = program.commands.indexOf(command);
+        if (index >= 0)
+            mutableCommands(program).splice(index, 1);
+    }
+    for (const { command, position } of ordered) {
+        mutableCommands(program).splice(Math.min(position, program.commands.length), 0, command);
+    }
+}
+function restorePlaceholders(program, bundle, positions) {
+    const ordered = [...bundle.placeholders]
+        .map(([name, command]) => ({ command, position: positions.get(name) }))
+        .filter((entry) => entry.position !== undefined)
+        .sort((a, b) => a.position - b.position);
+    for (const { command, position } of ordered) {
+        mutableCommands(program).splice(Math.min(position, program.commands.length), 0, command);
+    }
+}
+function selectedCommand(program, state, argv, parseOptions) {
+    const args = userArguments(argv ?? process.argv, parseOptions?.from);
+    for (let index = 0; index < args.length; index++) {
+        const token = args[index];
+        if (token === "--")
+            return undefined;
+        if (token.startsWith("-")) {
+            const option = findRootOption(program, token);
+            if (option?.required || (option?.optional && !args[index + 1]?.startsWith("-")))
+                index++;
+            continue;
+        }
+        if (token === "help")
+            return state.byName.get(args[index + 1] ?? "");
+        return state.byName.get(token);
+    }
+    return undefined;
+}
+function userArguments(argv, from) {
+    if (from === "user")
+        return argv;
+    if (from === "electron")
+        return argv.slice(1);
+    return argv.slice(2);
+}
+function findRootOption(program, token) {
+    const flag = token.includes("=") ? token.slice(0, token.indexOf("=")) : token;
+    return program.options.find((option) => option.short === flag || option.long === flag);
+}
+function findCommand(program, name) {
+    return program.commands.find((candidate) => candidate.name() === name || candidate.aliases().includes(name));
+}
+function mutableCommands(program) {
+    return program.commands;
+}
+function commandName(signature) {
+    return signature.trim().split(/[\s|]/, 1)[0] ?? signature;
+}