@ironbee-ai/cli 0.5.3 → 0.6.1

package/dist/queue/registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * IronBee CLI — Queue Handler Registry
+ *
+ * Handlers are registered per job `type`. The worker captures a snapshot of
+ * the registry at the top of processFile() (§5.3 "Handler registry" note) so
+ * mid-run registration changes cannot confuse dispatch.
+ */
+import { Job } from "./types";
+export interface Handler<TData = unknown> {
+    /**
+     * Batch dispatch. Must throw:
+     *   - TransientError        on retriable failures (5xx, network)
+     *   - AuthError             on auth failures (401/403)
+     *   - BadRequestBatchError  when the batch was rejected but the specific
+     *                           offending line is unknown (worker will fall back
+     *                           to per-job dispatchSingle)
+     * Other thrown errors bubble up as `unexpected:` and per-job-dead-letter
+     * via the fallback path.
+     */
+    dispatch(jobs: Job<TData>[]): Promise<void> | void;
+    /**
+     * Per-job fallback. Must throw:
+     *   - BadRequestError  for a permanent per-job failure (worker dead-letters
+     *                      this job and continues with the next)
+     *   - TransientError   to bail out of the fallback and leave the snapshot
+     *                      for a full-file retry
+     *   - AuthError        same as transient but signals auth needs fixing
+     */
+    dispatchSingle(job: Job<TData>): Promise<void> | void;
+}
+export type HandlerRegistry = Map<string, Handler>;
+export declare function register<TData>(type: string, handler: Handler<TData>): void;
+export declare function unregister(type: string): void;
+export declare function get(type: string): Handler | undefined;
+export declare function clear(): void;
+/**
+ * Return an immutable snapshot of the registry. Callers should capture this
+ * once per processFile() invocation and use it for the entire pass — see
+ * §7.18 (registry snapshot consistency).
+ */
+export declare function snapshotRegistry(): HandlerRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/queue/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/queue/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAE9B,MAAM,WAAW,OAAO,CAAC,KAAK,GAAG,OAAO;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAEnD;;;;;;;OAOG;IACH,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACzD;AAED,MAAM,MAAM,eAAe,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAInD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAE3E;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAErD;AAED,wBAAgB,KAAK,IAAI,IAAI,CAE5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,eAAe,CAElD"}

package/dist/queue/registry.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * IronBee CLI — Queue Handler Registry
+ *
+ * Handlers are registered per job `type`. The worker captures a snapshot of
+ * the registry at the top of processFile() (§5.3 "Handler registry" note) so
+ * mid-run registration changes cannot confuse dispatch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+exports.unregister = unregister;
+exports.get = get;
+exports.clear = clear;
+exports.snapshotRegistry = snapshotRegistry;
+const globalRegistry = new Map();
+function register(type, handler) {
+    globalRegistry.set(type, handler);
+}
+function unregister(type) {
+    globalRegistry.delete(type);
+}
+function get(type) {
+    return globalRegistry.get(type);
+}
+function clear() {
+    globalRegistry.clear();
+}
+/**
+ * Return an immutable snapshot of the registry. Callers should capture this
+ * once per processFile() invocation and use it for the entire pass — see
+ * §7.18 (registry snapshot consistency).
+ */
+function snapshotRegistry() {
+    return new Map(globalRegistry);
+}
+//# sourceMappingURL=registry.js.map

package/dist/queue/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/queue/registry.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAgCH,4BAEC;AAED,gCAEC;AAED,kBAEC;AAED,sBAEC;AAOD,4CAEC;AAzBD,MAAM,cAAc,GAAoB,IAAI,GAAG,EAAmB,CAAC;AAEnE,SAAgB,QAAQ,CAAQ,IAAY,EAAE,OAAuB;IACjE,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,OAAkB,CAAC,CAAC;AACjD,CAAC;AAED,SAAgB,UAAU,CAAC,IAAY;IACnC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,SAAgB,GAAG,CAAC,IAAY;IAC5B,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,SAAgB,KAAK;IACjB,cAAc,CAAC,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB;IAC5B,OAAO,IAAI,GAAG,CAAkB,cAAc,CAAC,CAAC;AACpD,CAAC"}

package/dist/queue/snapshot.d.ts

@@ -0,0 +1,16 @@
+/**
+ * IronBee CLI — Queue snapshot()
+ *
+ * See docs/job-queue.md §5.2.
+ */
+/**
+ * Atomically freeze the live queue file into a snapshot.
+ *   Success → returns absolute snapshot path
+ *   Live file missing (ENOENT) → returns null
+ *
+ * Throws:
+ *   - InvalidSessionIdError  if sessionId fails validation
+ *   - IOError                on filesystem errors other than ENOENT
+ */
+export declare function snapshot(projectDir: string, sessionId: string): string | null;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/queue/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/queue/snapshot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiB7E"}

package/dist/queue/snapshot.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * IronBee CLI — Queue snapshot()
+ *
+ * See docs/job-queue.md §5.2.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshot = snapshot;
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const types_1 = require("./types");
+const paths_1 = require("./paths");
+/**
+ * Atomically freeze the live queue file into a snapshot.
+ *   Success → returns absolute snapshot path
+ *   Live file missing (ENOENT) → returns null
+ *
+ * Throws:
+ *   - InvalidSessionIdError  if sessionId fails validation
+ *   - IOError                on filesystem errors other than ENOENT
+ */
+function snapshot(projectDir, sessionId) {
+    (0, paths_1.validateSessionId)(sessionId);
+    const snapshotId = (0, crypto_1.randomUUID)();
+    const src = (0, paths_1.liveQueueFile)(projectDir, sessionId);
+    const dst = (0, paths_1.snapshotFile)(projectDir, sessionId, snapshotId);
+    try {
+        (0, fs_1.renameSync)(src, dst);
+        return dst;
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw new types_1.IOError(`failed to rename ${src} -> ${dst}`, e);
+    }
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/queue/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/queue/snapshot.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAgBH,4BAiBC;AA/BD,2BAAgC;AAChC,mCAAoC;AACpC,mCAAkC;AAClC,mCAAyE;AAEzE;;;;;;;;GAQG;AACH,SAAgB,QAAQ,CAAC,UAAkB,EAAE,SAAiB;IAC1D,IAAA,yBAAiB,EAAC,SAAS,CAAC,CAAC;IAE7B,MAAM,UAAU,GAAW,IAAA,mBAAU,GAAE,CAAC;IACxC,MAAM,GAAG,GAAW,IAAA,qBAAa,EAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACzD,MAAM,GAAG,GAAW,IAAA,oBAAY,EAAC,UAAU,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAEpE,IAAI,CAAC;QACD,IAAA,eAAU,EAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACrB,OAAO,GAAG,CAAC;IACf,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,MAAM,GAAG,GAA0B,CAA0B,CAAC;QAC9D,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,MAAM,IAAI,eAAO,CAAC,oBAAoB,GAAG,OAAO,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;IAC9D,CAAC;AACL,CAAC"}

package/dist/queue/spawn.d.ts

@@ -0,0 +1,15 @@
+/**
+ * IronBee CLI — Detached Worker Spawn
+ *
+ * See docs/job-queue.md §5.6 (when to use), §9.1 (platform primitives).
+ *
+ * Callers on the active-use path use this helper to fire-and-forget a worker
+ * on a freshly-minted snapshot. The trigger returns in <10 ms; the worker
+ * survives the trigger's exit.
+ */
+/**
+ * Spawn a detached worker on the given snapshot path. Returns immediately.
+ * The parent process may exit without killing the child.
+ */
+export declare function spawnDetachedWorker(snapshotPath: string): void;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/queue/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../src/queue/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsBH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAU9D"}

package/dist/queue/spawn.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * IronBee CLI — Detached Worker Spawn
+ *
+ * See docs/job-queue.md §5.6 (when to use), §9.1 (platform primitives).
+ *
+ * Callers on the active-use path use this helper to fire-and-forget a worker
+ * on a freshly-minted snapshot. The trigger returns in <10 ms; the worker
+ * survives the trigger's exit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnDetachedWorker = spawnDetachedWorker;
+const child_process_1 = require("child_process");
+/**
+ * Resolve the `ironbee` binary to invoke. Falls back to `node <currentEntry>`
+ * if the CLI was launched via `node dist/index.js` (common in tests / dev).
+ */
+function resolveInvocation() {
+    const override = process.env.IRONBEE_BIN;
+    if (override) {
+        return { command: override, args: [] };
+    }
+    const argv0 = process.argv[0];
+    const argv1 = process.argv[1] ?? "";
+    // when launched via `ironbee` bin, argv[1] is the dist/index.js path — re-run it via node
+    if (argv1.endsWith("index.js") || argv1.endsWith("index.ts")) {
+        return { command: argv0, args: [argv1] };
+    }
+    return { command: "ironbee", args: [] };
+}
+/**
+ * Spawn a detached worker on the given snapshot path. Returns immediately.
+ * The parent process may exit without killing the child.
+ */
+function spawnDetachedWorker(snapshotPath) {
+    const { command, args } = resolveInvocation();
+    const fullArgs = [...args, "process-job-file", snapshotPath];
+    const child = (0, child_process_1.spawn)(command, fullArgs, {
+        detached: true,
+        stdio: "ignore",
+        env: process.env,
+    });
+    child.unref();
+}
+//# sourceMappingURL=spawn.js.map

package/dist/queue/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["../../src/queue/spawn.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AA0BH,kDAUC;AAlCD,iDAAoD;AAEpD;;;GAGG;AACH,SAAS,iBAAiB;IACtB,MAAM,QAAQ,GAAuB,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAC7D,IAAI,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC3C,CAAC;IACD,MAAM,KAAK,GAAW,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,KAAK,GAAW,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5C,0FAA0F;IAC1F,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7C,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,YAAoB;IACpD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,iBAAiB,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAAa,CAAC,GAAG,IAAI,EAAE,kBAAkB,EAAE,YAAY,CAAC,CAAC;IAEvE,MAAM,KAAK,GAAiB,IAAA,qBAAK,EAAC,OAAO,EAAE,QAAQ,EAAE;QACjD,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,QAAQ;QACf,GAAG,EAAE,OAAO,CAAC,GAAG;KACnB,CAAC,CAAC;IACH,KAAK,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC"}

package/dist/queue/submit.d.ts

@@ -0,0 +1,19 @@
+/**
+ * IronBee CLI — Queue submit()
+ *
+ * See docs/job-queue.md §5.1.
+ */
+export interface SubmitOptions {
+    id?: string;
+}
+/**
+ * Append a job to `<projectDir>/.ironbee/sessions/<sessionId>/queue/jobs.jsonl`
+ * via a single O_APPEND write. Returns the job id.
+ *
+ * Throws:
+ *   - InvalidSessionIdError  if sessionId fails validation
+ *   - JobTooLargeError       if serialized line > 4 KB
+ *   - IOError                on filesystem errors (including short write)
+ */
+export declare function submit<TData>(projectDir: string, sessionId: string, type: string, data: TData, opts?: SubmitOptions): string;
+//# sourceMappingURL=submit.d.ts.map

package/dist/queue/submit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit.d.ts","sourceRoot":"","sources":["../../src/queue/submit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,MAAM,WAAW,aAAa;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EACxB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,KAAK,EACX,IAAI,CAAC,EAAE,aAAa,GACrB,MAAM,CAwER"}

package/dist/queue/submit.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * IronBee CLI — Queue submit()
+ *
+ * See docs/job-queue.md §5.1.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.submit = submit;
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const types_1 = require("./types");
+const paths_1 = require("./paths");
+const flush_1 = require("./flush");
+const config_1 = require("../lib/config");
+const logger_1 = require("../lib/logger");
+/**
+ * Append a job to `<projectDir>/.ironbee/sessions/<sessionId>/queue/jobs.jsonl`
+ * via a single O_APPEND write. Returns the job id.
+ *
+ * Throws:
+ *   - InvalidSessionIdError  if sessionId fails validation
+ *   - JobTooLargeError       if serialized line > 4 KB
+ *   - IOError                on filesystem errors (including short write)
+ */
+function submit(projectDir, sessionId, type, data, opts) {
+    (0, paths_1.validateSessionId)(sessionId);
+    // Defense-in-depth gate: when the queue is disabled (default), drop the
+    // job before touching the filesystem. Callers should already short-circuit
+    // before constructing a payload, but this guard stops a stray submit()
+    // from creating the queue dir or growing jobs.jsonl needlessly.
+    if (!(0, config_1.isJobQueueEnabled)(projectDir)) {
+        const id = opts?.id ?? (0, crypto_1.randomUUID)();
+        logger_1.logger.debug(`submit: jobQueue disabled, dropping job type=${type} id=${id}`);
+        return id;
+    }
+    const dir = (0, paths_1.queueDir)(projectDir, sessionId);
+    try {
+        (0, fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    }
+    catch (e) {
+        throw new types_1.IOError(`failed to mkdir queue dir: ${dir}`, e);
+    }
+    const id = opts?.id ?? (0, crypto_1.randomUUID)();
+    const job = {
+        id,
+        type,
+        created_at: new Date().toISOString(),
+        data,
+    };
+    const line = JSON.stringify(job) + "\n";
+    const bytes = Buffer.from(line, "utf-8");
+    if (bytes.length > types_1.MAX_LINE_BYTES) {
+        throw new types_1.JobTooLargeError(bytes.length);
+    }
+    const filePath = (0, paths_1.liveQueueFile)(projectDir, sessionId);
+    const flags = fs_1.constants.O_CREAT
+        | fs_1.constants.O_WRONLY
+        | fs_1.constants.O_APPEND
+        | (typeof fs_1.constants.O_NOFOLLOW === "number" ? fs_1.constants.O_NOFOLLOW : 0);
+    let fd;
+    try {
+        fd = (0, fs_1.openSync)(filePath, flags, 0o600);
+    }
+    catch (e) {
+        throw new types_1.IOError(`failed to open ${filePath}`, e);
+    }
+    try {
+        let written;
+        try {
+            written = (0, fs_1.writeSync)(fd, bytes, 0, bytes.length);
+        }
+        catch (e) {
+            // ENOSPC / EIO / etc — wrap to preserve spec §5.1 contract that
+            // submit() throws IOError with the underlying errno.
+            throw new types_1.IOError(`failed to write to ${filePath}`, e);
+        }
+        if (written !== bytes.length) {
+            throw new types_1.IOError(`short write on ${filePath}: wrote ${written} of ${bytes.length} bytes`);
+        }
+    }
+    finally {
+        try {
+            (0, fs_1.closeSync)(fd);
+        }
+        catch {
+            // ignore close errors — the write has already landed (or failed)
+        }
+    }
+    // size-based auto-flush trigger. Fail-safe: never propagates exceptions
+    // to submit()'s caller, the line has already been persisted.
+    (0, flush_1.maybeAutoFlush)(projectDir, sessionId);
+    return id;
+}
+//# sourceMappingURL=submit.js.map

package/dist/queue/submit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit.js","sourceRoot":"","sources":["../../src/queue/submit.ts"],"names":[],"mappings":"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"}

package/dist/queue/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * IronBee CLI — Queue Types & Errors
+ *
+ * See docs/job-queue.md §4 (job format), §6 (error classification).
+ */
+export declare class InvalidSessionIdError extends Error {
+    constructor(message: string);
+}
+export declare class JobTooLargeError extends Error {
+    readonly sizeBytes: number;
+    constructor(sizeBytes: number);
+}
+export declare class IOError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Handler throws this on transient failures (network timeout, 5xx, 429).
+ * Worker leaves the snapshot on disk for later retry.
+ */
+export declare class TransientError extends Error {
+    constructor(message: string);
+}
+/**
+ * Handler throws this on auth failures (401, 403, expired credential).
+ * Worker leaves the snapshot on disk and logs an operator-actionable error.
+ */
+export declare class AuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * Handler's batch `dispatch()` throws this when the downstream rejected the
+ * batch but we don't know which line caused it — worker falls back to
+ * per-job `dispatchSingle()`.
+ */
+export declare class BadRequestBatchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Handler's `dispatchSingle()` throws this on a permanent per-job failure
+ * (400 for this specific job). Worker dead-letters the job and continues.
+ */
+export declare class BadRequestError extends Error {
+    constructor(message: string);
+}
+/**
+ * Job envelope — exactly three queue-owned top-level fields plus the opaque
+ * `data` payload. Mirrors the spec's §4 schema.
+ */
+export interface Job<TData = unknown> {
+    id: string;
+    type: string;
+    created_at: string;
+    data: TData;
+}
+export interface DeadLetterParsed {
+    id: string;
+    received_at: string;
+    source_file: string;
+    category: string;
+    original: Job;
+}
+export interface DeadLetterParseError {
+    id: string;
+    received_at: string;
+    source_file: string;
+    category: string;
+    raw: string;
+}
+export type DeadLetterEntry = DeadLetterParsed | DeadLetterParseError;
+export declare const MAX_LINE_BYTES: number;
+export declare const DEAD_LETTER_ROTATE_BYTES: number;
+export declare const DEAD_LETTER_RETAIN_COUNT: number;
+export declare const WORKER_LOG_ROTATE_BYTES: number;
+export declare const WORKER_LOG_RETAIN_COUNT: number;
+export declare const DEAD_LETTER_RAW_MAX: number;
+//# sourceMappingURL=types.d.ts.map

package/dist/queue/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/queue/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,qBAAsB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACvC,SAAgB,SAAS,EAAE,MAAM,CAAC;gBACtB,SAAS,EAAE,MAAM;CAKhC;AAED,qBAAa,OAAQ,SAAQ,KAAK;IAC9B,SAAgB,KAAK,CAAC,EAAE,OAAO,CAAC;gBACpB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK/C;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI9B;AAED;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;gBACpB,OAAO,EAAE,MAAM;CAI9B;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI9B;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI9B;AAED;;;GAGG;AACH,MAAM,WAAW,GAAG,CAAC,KAAK,GAAG,OAAO;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,GAAG,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;AAEtE,eAAO,MAAM,cAAc,EAAE,MAAa,CAAC;AAC3C,eAAO,MAAM,wBAAwB,EAAE,MAAyB,CAAC;AACjE,eAAO,MAAM,wBAAwB,EAAE,MAAU,CAAC;AAClD,eAAO,MAAM,uBAAuB,EAAE,MAAyB,CAAC;AAChE,eAAO,MAAM,uBAAuB,EAAE,MAAU,CAAC;AACjD,eAAO,MAAM,mBAAmB,EAAE,MAAY,CAAC"}

package/dist/queue/types.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * IronBee CLI — Queue Types & Errors
+ *
+ * See docs/job-queue.md §4 (job format), §6 (error classification).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEAD_LETTER_RAW_MAX = exports.WORKER_LOG_RETAIN_COUNT = exports.WORKER_LOG_ROTATE_BYTES = exports.DEAD_LETTER_RETAIN_COUNT = exports.DEAD_LETTER_ROTATE_BYTES = exports.MAX_LINE_BYTES = exports.BadRequestError = exports.BadRequestBatchError = exports.AuthError = exports.TransientError = exports.IOError = exports.JobTooLargeError = exports.InvalidSessionIdError = void 0;
+class InvalidSessionIdError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidSessionIdError";
+    }
+}
+exports.InvalidSessionIdError = InvalidSessionIdError;
+class JobTooLargeError extends Error {
+    constructor(sizeBytes) {
+        super(`job line exceeds 4 KB limit (${sizeBytes} bytes)`);
+        this.name = "JobTooLargeError";
+        this.sizeBytes = sizeBytes;
+    }
+}
+exports.JobTooLargeError = JobTooLargeError;
+class IOError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = "IOError";
+        this.cause = cause;
+    }
+}
+exports.IOError = IOError;
+/**
+ * Handler throws this on transient failures (network timeout, 5xx, 429).
+ * Worker leaves the snapshot on disk for later retry.
+ */
+class TransientError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TransientError";
+    }
+}
+exports.TransientError = TransientError;
+/**
+ * Handler throws this on auth failures (401, 403, expired credential).
+ * Worker leaves the snapshot on disk and logs an operator-actionable error.
+ */
+class AuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AuthError";
+    }
+}
+exports.AuthError = AuthError;
+/**
+ * Handler's batch `dispatch()` throws this when the downstream rejected the
+ * batch but we don't know which line caused it — worker falls back to
+ * per-job `dispatchSingle()`.
+ */
+class BadRequestBatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BadRequestBatchError";
+    }
+}
+exports.BadRequestBatchError = BadRequestBatchError;
+/**
+ * Handler's `dispatchSingle()` throws this on a permanent per-job failure
+ * (400 for this specific job). Worker dead-letters the job and continues.
+ */
+class BadRequestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BadRequestError";
+    }
+}
+exports.BadRequestError = BadRequestError;
+exports.MAX_LINE_BYTES = 4096;
+exports.DEAD_LETTER_ROTATE_BYTES = 10 * 1024 * 1024;
+exports.DEAD_LETTER_RETAIN_COUNT = 3;
+exports.WORKER_LOG_ROTATE_BYTES = 10 * 1024 * 1024;
+exports.WORKER_LOG_RETAIN_COUNT = 5;
+exports.DEAD_LETTER_RAW_MAX = 512;
+//# sourceMappingURL=types.js.map

package/dist/queue/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/queue/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,MAAa,qBAAsB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACxC,CAAC;CACJ;AALD,sDAKC;AAED,MAAa,gBAAiB,SAAQ,KAAK;IAEvC,YAAY,SAAiB;QACzB,KAAK,CAAC,gCAAgC,SAAS,SAAS,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;CACJ;AAPD,4CAOC;AAED,MAAa,OAAQ,SAAQ,KAAK;IAE9B,YAAY,OAAe,EAAE,KAAe;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;CACJ;AAPD,0BAOC;AAED;;;GAGG;AACH,MAAa,cAAe,SAAQ,KAAK;IACrC,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IACjC,CAAC;CACJ;AALD,wCAKC;AAED;;;GAGG;AACH,MAAa,SAAU,SAAQ,KAAK;IAChC,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC5B,CAAC;CACJ;AALD,8BAKC;AAED;;;;GAIG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACvC,CAAC;CACJ;AALD,oDAKC;AAED;;;GAGG;AACH,MAAa,eAAgB,SAAQ,KAAK;IACtC,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAClC,CAAC;CACJ;AALD,0CAKC;AA+BY,QAAA,cAAc,GAAW,IAAI,CAAC;AAC9B,QAAA,wBAAwB,GAAW,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACpD,QAAA,wBAAwB,GAAW,CAAC,CAAC;AACrC,QAAA,uBAAuB,GAAW,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACnD,QAAA,uBAAuB,GAAW,CAAC,CAAC;AACpC,QAAA,mBAAmB,GAAW,GAAG,CAAC"}

package/dist/queue/worker-log.d.ts

@@ -0,0 +1,21 @@
+/**
+ * IronBee CLI — Worker Log + Rotation
+ *
+ * See docs/job-queue.md §8.1.
+ */
+export type WorkerLogLevel = "INFO" | "WARN" | "ERROR" | "DEBUG";
+export declare class WorkerLog {
+    private readonly projectDir;
+    private readonly sessionId;
+    constructor(projectDir: string, sessionId: string);
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    debug(msg: string): void;
+    private write;
+    private format;
+    private appendLine;
+    private rotateIfNeeded;
+    private enforceRetention;
+}
+//# sourceMappingURL=worker-log.d.ts.map

package/dist/queue/worker-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-log.d.ts","sourceRoot":"","sources":["../../src/queue/worker-log.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuBH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEjE,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAK1C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IACvB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IACvB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAE/B,OAAO,CAAC,KAAK;IAUb,OAAO,CAAC,MAAM;IAqBd,OAAO,CAAC,UAAU;IAqBlB,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,gBAAgB;CAmC3B"}