@legioncodeinc/nectar 0.0.1

package/dist/lock.js

@@ -0,0 +1,282 @@
+/**
+ * Single-instance PID/lock guard for the nectar daemon.
+ *
+ * Mirrors honeycomb's `acquireSingleInstanceLock` / `releaseSingleInstanceLock`
+ * (honeycomb/src/daemon/runtime/assemble.ts:715-756) per PRD-002d, hardened by
+ * PRD-018a against the three lock defects the daemon-api review found:
+ *   - a second start with a LIVE recorded identity throws before the socket bind,
+ *   - a stale lock (dead owner, or an owner from a prior boot) is reclaimed so a
+ *     crashed daemon never wedges the next start,
+ *   - reclaim is ATOMIC: a concurrent reclaimer can never delete the winner's
+ *     fresh lock (the unconditional `rmSync` at the old `lock.ts:84` is gone),
+ *   - release is OWNERSHIP-CHECKED: a process only ever removes a lock it holds,
+ *   - the lock records a stronger identity than a bare pid (pid + machine boot
+ *     time + a random token), so a REUSED pid after a crash/reboot is recognized
+ *     as stale instead of masquerading as a live daemon (NEC-020).
+ *
+ * The lock file is the guard and carries the JSON identity; the pid file stays a
+ * bare pid for operator convenience (`cat ~/.honeycomb/nectar.pid`) and doctor
+ * supervision (`doctor-registry.ts` `pidPath`).
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, writeSync, } from "node:fs";
+import { uptime } from "node:os";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { DaemonAlreadyRunningError } from "./errors.js";
+/** How many exclusive-create attempts an acquire makes before conceding to a live holder. */
+const MAX_ACQUIRE_ATTEMPTS = 5;
+/**
+ * Tolerance (seconds) when comparing a recorded boot time against the current
+ * one. `Date.now()` and `os.uptime()` are sampled a few milliseconds apart, so a
+ * live lock written this boot can read back a second off; a real reboot moves
+ * the boot time by minutes or more, so a small window cleanly separates the two.
+ */
+const BOOT_TOLERANCE_SEC = 5;
+/**
+ * Probe whether a PID is alive via signal 0.
+ *   - `ESRCH` -> no such process (stale),
+ *   - `EPERM` -> alive but owned by another user (treated as alive),
+ *   - success -> alive.
+ * Mirrors honeycomb's `isPidAlive` (assemble.ts:692-705).
+ */
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EPERM")
+            return true; // alive, different user
+        return false; // ESRCH or anything else -> not alive
+    }
+}
+/** Read the PID from a lock/pid file; absent/unreadable/garbage returns null. */
+export function readPidFile(path) {
+    try {
+        const raw = readFileSync(path, "utf8").trim();
+        if (raw === "")
+            return null;
+        const pid = Number.parseInt(raw, 10);
+        return Number.isInteger(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The current machine boot time as whole epoch seconds (stable across quick reads). */
+function currentBoot() {
+    return Math.floor(Date.now() / 1000 - uptime());
+}
+/** Two boot timestamps refer to the same boot when they are within the sampling tolerance. */
+function sameBoot(a, b) {
+    return Math.abs(a - b) <= BOOT_TOLERANCE_SEC;
+}
+/**
+ * Read and parse the identity a lock file records. Accepts the current JSON
+ * shape and, for backward compatibility, a legacy bare-pid file (interpreted as
+ * a pid-only identity). Absent / unreadable / unparseable returns null.
+ */
+export function readLockIdentity(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8").trim();
+    }
+    catch {
+        return null;
+    }
+    if (raw === "")
+        return null;
+    // Legacy bare-pid lock (honeycomb-style): pid is the only identity available.
+    if (/^\d+$/.test(raw)) {
+        const pid = Number.parseInt(raw, 10);
+        return Number.isInteger(pid) && pid > 0 ? { pid } : null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return null;
+    const rec = parsed;
+    const pid = typeof rec["pid"] === "number" ? rec["pid"] : Number.NaN;
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    const boot = typeof rec["boot"] === "number" ? rec["boot"] : undefined;
+    const token = typeof rec["token"] === "string" ? rec["token"] : undefined;
+    return {
+        pid,
+        ...(boot !== undefined ? { boot } : {}),
+        ...(token !== undefined ? { token } : {}),
+    };
+}
+/**
+ * True when the recorded identity plausibly belongs to a LIVE nectar daemon: its
+ * pid is alive AND (when the lock records a boot time) it was written this boot.
+ * A live-but-foreign pid from a prior boot (PID reuse) fails the boot check and
+ * is therefore reclaimable rather than a permanent wedge (NEC-020).
+ */
+function isLockOwnerLive(id) {
+    if (!isPidAlive(id.pid))
+        return false;
+    if (id.boot === undefined)
+        return true; // legacy pid-only lock: pid liveness is all we have
+    return sameBoot(id.boot, currentBoot());
+}
+/** Two identities are the same lock when their tokens match (or, legacy, their pid+boot). */
+function sameIdentity(a, b) {
+    if (a.token !== undefined && b.token !== undefined)
+        return a.token === b.token;
+    return a.pid === b.pid && a.boot === b.boot;
+}
+/**
+ * Reclaim a stale lock atomically. Re-reads the lock immediately before removing
+ * it and removes it ONLY if it still holds the same stale content we decided to
+ * reclaim. If a concurrent reclaimer already replaced it (content changed, or the
+ * file is gone), this is a no-op: the caller's next exclusive-create attempt
+ * re-evaluates the fresh content and correctly sees a live owner. This is what
+ * makes two racing reclaims yield exactly one winner without the loser deleting
+ * the winner's lock (NEC-020 / the old unconditional `rmSync`).
+ */
+function reclaimStaleLock(lockFilePath, expected) {
+    const current = readLockIdentity(lockFilePath);
+    if (current === null) {
+        // `readLockIdentity` returns null for two different situations: the file
+        // is now gone (someone else already reclaimed it; the retry loop
+        // re-creates it), OR the file is PRESENT but its content is empty/garbage
+        // (a corrupt lock). CodeRabbit PR-18 finding #2: the pre-fix code treated
+        // both as "already gone" and never removed a present-but-corrupt lock, so
+        // every later acquire hit EEXIST forever and the daemon could never start
+        // without a manual `rm`. A corrupt lock records no owner at all, so it is
+        // unconditionally stale; reclaim it the same way. Re-check immediately
+        // before removing (the same re-read-then-conditionally-remove discipline
+        // the live-lock branch below uses) so a concurrent racer that has already
+        // replaced the corrupt file with a fresh, parseable, live lock is never
+        // deleted out from under its new owner (NEC-020 - the atomic-reclaim
+        // guarantee this function exists to preserve).
+        if (existsSync(lockFilePath) && readLockIdentity(lockFilePath) === null) {
+            rmSync(lockFilePath, { force: true });
+        }
+        return;
+    }
+    if (expected !== null && !sameIdentity(current, expected))
+        return; // changed under us
+    if (isLockOwnerLive(current))
+        return; // became live under us; loop re-evaluates
+    rmSync(lockFilePath, { force: true });
+}
+/**
+ * Acquire the single-instance lock. Called BEFORE the socket bind (PRD-002a).
+ * Throws `DaemonAlreadyRunningError` if a LIVE daemon already holds the lock;
+ * atomically reclaims a stale lock otherwise. Returns the identity it stamped so
+ * the caller can pass it back to {@link releaseSingleInstanceLock} for an
+ * ownership-checked release (PRD-018a NEC-002).
+ */
+export function acquireSingleInstanceLock(paths, options = {}) {
+    mkdirSync(dirname(paths.lockFilePath), { recursive: true });
+    const identity = {
+        pid: options.pid ?? process.pid,
+        boot: options.boot ?? currentBoot(),
+        token: options.token ?? randomUUID(),
+    };
+    const serialized = JSON.stringify(identity);
+    const writeLockBody = options.writeLockBody ?? writeSync;
+    for (let attempt = 0; attempt < MAX_ACQUIRE_ATTEMPTS; attempt++) {
+        let fd;
+        try {
+            // Exclusive create is the atomic winner-picker: only ONE process can create
+            // the lock with "wx"; every other concurrent creator gets EEXIST.
+            fd = openSync(paths.lockFilePath, "wx");
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            const existing = readLockIdentity(paths.lockFilePath);
+            if (existing !== null && isLockOwnerLive(existing)) {
+                throw new DaemonAlreadyRunningError(existing.pid, paths.lockFilePath);
+            }
+            // Stale (dead owner / prior boot / unreadable): reclaim and retry.
+            reclaimStaleLock(paths.lockFilePath, existing);
+            continue;
+        }
+        try {
+            writeLockBody(fd, serialized);
+        }
+        catch (err) {
+            closeSync(fd);
+            // Roll back: the lock file was just created by us (the "wx" open above
+            // succeeded), so a write failure must not leave a half-written/corrupt
+            // lock body behind wedging every future acquire (CodeRabbit PR-18
+            // finding #2), mirroring the pid-file write path's rollback below.
+            rmSync(paths.lockFilePath, { force: true });
+            throw err;
+        }
+        closeSync(fd);
+        // Verify-after-create: confirm the lock still records OUR token. A concurrent
+        // reclaimer cannot have replaced it (our "wx" create means the file existed
+        // for everyone else, who then read our live identity and threw), so this is
+        // belt-and-suspenders; on a mismatch we retry rather than proceed unsafely.
+        const readback = readLockIdentity(paths.lockFilePath);
+        if (readback === null || readback.token !== identity.token)
+            continue;
+        // Write the operator-facing pid file (bare pid). On failure, roll the lock
+        // back so a partial acquisition never leaves a stale lock wedging the next
+        // start; the lock was just created by us, so removing it is safe.
+        try {
+            writeFileSync(paths.pidFilePath, String(identity.pid), "utf8");
+        }
+        catch (err) {
+            rmSync(paths.lockFilePath, { force: true });
+            throw err;
+        }
+        return identity;
+    }
+    // Every attempt lost to a live lock created between our checks.
+    const raced = readLockIdentity(paths.lockFilePath);
+    throw new DaemonAlreadyRunningError(raced?.pid ?? -1, paths.lockFilePath);
+}
+/** Does the recorded lock belong to `identity` (or, absent one, to this live process)? */
+function lockOwnedBy(recorded, identity) {
+    if (identity !== undefined) {
+        if (identity.token !== undefined && recorded.token !== undefined) {
+            return recorded.token === identity.token;
+        }
+        return recorded.pid === identity.pid && bootMatches(recorded.boot, identity.boot);
+    }
+    // No identity supplied: own it iff this live process wrote it (pid + this boot).
+    return recorded.pid === process.pid && (recorded.boot === undefined || sameBoot(recorded.boot, currentBoot()));
+}
+function bootMatches(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return sameBoot(a, b);
+}
+/**
+ * Release the lock: remove both files, but ONLY when this process owns the lock
+ * (PRD-018a NEC-002). Called by a process that does not own the lock (a failed
+ * second start), it is a no-op, so a failed start can never delete the live
+ * daemon's lock and pid. Pass the identity returned by
+ * {@link acquireSingleInstanceLock} for a precise token-based check; omit it to
+ * fall back to a pid+boot check against this live process. Never throws (a
+ * missing lock on shutdown is fine; the goal already holds).
+ */
+export function releaseSingleInstanceLock(paths, identity) {
+    const recorded = readLockIdentity(paths.lockFilePath);
+    // Own the lock, or it is already gone: safe to clear both files. Otherwise the
+    // lock belongs to a live, different owner and we touch nothing.
+    if (recorded === null || lockOwnedBy(recorded, identity)) {
+        rmSync(paths.lockFilePath, { force: true });
+        rmSync(paths.pidFilePath, { force: true });
+    }
+}
+/** True if a live daemon currently holds this lock (used by health/status). */
+export function isLockHeldByLiveDaemon(lockFilePath) {
+    const id = readLockIdentity(lockFilePath);
+    return id !== null && isLockOwnerLive(id);
+}
+//# sourceMappingURL=lock.js.map

package/dist/lock.js.map

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

package/dist/poll-loop.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Adaptive poll loop for the hiveantennae worker.
+ *
+ * Mirrors honeycomb's poll-loop (honeycomb/src/daemon/runtime/services/poll-loop.ts)
+ * per PRD-002b:
+ *   - tick -> run one pass,
+ *   - skip a tick if the previous run is still in flight (overlap guard),
+ *   - reschedule via a backoff state machine: reset to the floor when a tick did
+ *     work, step toward the ceiling when it was idle.
+ * The loop owns no wall clock and no I/O: the timer seam is injected so it is
+ * deterministic under a manual clock in tests.
+ */
+/** A single pass. Returns true if it did work (reset backoff), false if idle (step toward ceiling). */
+export type Tick = () => Promise<boolean> | boolean;
+export interface Timer {
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** Default timer backed by Node's global timers. */
+export declare const realTimer: Timer;
+export interface PollLoopOptions {
+    readonly tick: Tick;
+    /** Backoff floor (fast cadence when there is work). */
+    readonly floorMs: number;
+    /** Backoff ceiling (slow cadence when idle). Defaults to floorMs (no backoff). */
+    readonly ceilingMs?: number;
+    /** Multiplier applied to the delay on each idle tick. Defaults to 2. */
+    readonly backoffFactor?: number;
+    readonly timer?: Timer;
+    readonly onError?: (err: unknown) => void;
+}
+export declare class PollLoop {
+    private readonly tick;
+    private readonly floorMs;
+    private readonly ceilingMs;
+    private readonly backoffFactor;
+    private readonly timer;
+    private readonly onError;
+    private running;
+    private inFlight;
+    /** The currently-running tick, or null when idle. Exposed via {@link whenIdle} for bounded drain on shutdown. */
+    private inFlightPromise;
+    private handle;
+    private currentDelayMs;
+    /** Bumped on every start() and stop(); a pump/schedule from an older generation is ignored. */
+    private generation;
+    constructor(opts: PollLoopOptions);
+    get currentDelay(): number;
+    get isRunning(): boolean;
+    /** Arm the loop. Idempotent: a second start while running is a no-op. */
+    start(): void;
+    /** Disarm the loop. Idempotent. An in-flight tick is allowed to finish but cannot reschedule. */
+    stop(): void;
+    /**
+     * Run exactly one lease pass. Skips (returns false) if a previous run is still
+     * in flight, so a slow tick never overlaps itself. A skipped tick does NOT
+     * feed the backoff state machine. Errors are routed to onError and treated as
+     * idle for backoff purposes.
+     */
+    runOnce(): Promise<boolean>;
+    /**
+     * Resolve once any in-flight tick has settled. `shutdown()` awaits this (under
+     * a bounded timeout) so a tick is drained rather than killed mid-flight
+     * (PRD-018a NEC-033). The tracked promise never rejects (errors are routed to
+     * `onError` inside `runOnce`), so awaiting it is safe.
+     */
+    whenIdle(): Promise<void>;
+    private schedule;
+    private pump;
+}
+//# sourceMappingURL=poll-loop.d.ts.map

package/dist/poll-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-loop.d.ts","sourceRoot":"","sources":["../src/poll-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,uGAAuG;AACvG,MAAM,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAEpD,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzC,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B;AAED,oDAAoD;AACpD,eAAO,MAAM,SAAS,EAAE,KAGvB,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAO;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,iHAAiH;IACjH,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,cAAc,CAAS;IAC/B,+FAA+F;IAC/F,OAAO,CAAC,UAAU,CAAK;gBAEX,IAAI,EAAE,eAAe;IAUjC,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,yEAAyE;IACzE,KAAK,IAAI,IAAI;IAQb,iGAAiG;IACjG,IAAI,IAAI,IAAI;IASZ;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBjC;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B,OAAO,CAAC,QAAQ;YAOF,IAAI;CAoBnB"}

package/dist/poll-loop.js

@@ -0,0 +1,130 @@
+/**
+ * Adaptive poll loop for the hiveantennae worker.
+ *
+ * Mirrors honeycomb's poll-loop (honeycomb/src/daemon/runtime/services/poll-loop.ts)
+ * per PRD-002b:
+ *   - tick -> run one pass,
+ *   - skip a tick if the previous run is still in flight (overlap guard),
+ *   - reschedule via a backoff state machine: reset to the floor when a tick did
+ *     work, step toward the ceiling when it was idle.
+ * The loop owns no wall clock and no I/O: the timer seam is injected so it is
+ * deterministic under a manual clock in tests.
+ */
+/** Default timer backed by Node's global timers. */
+export const realTimer = {
+    set: (fn, ms) => setTimeout(fn, ms),
+    clear: (handle) => clearTimeout(handle),
+};
+export class PollLoop {
+    tick;
+    floorMs;
+    ceilingMs;
+    backoffFactor;
+    timer;
+    onError;
+    running = false;
+    inFlight = false;
+    /** The currently-running tick, or null when idle. Exposed via {@link whenIdle} for bounded drain on shutdown. */
+    inFlightPromise = null;
+    handle = null;
+    currentDelayMs;
+    /** Bumped on every start() and stop(); a pump/schedule from an older generation is ignored. */
+    generation = 0;
+    constructor(opts) {
+        this.tick = opts.tick;
+        this.floorMs = Math.max(1, opts.floorMs);
+        this.ceilingMs = Math.max(this.floorMs, opts.ceilingMs ?? opts.floorMs);
+        this.backoffFactor = Math.max(1, opts.backoffFactor ?? 2);
+        this.timer = opts.timer ?? realTimer;
+        this.onError = opts.onError ?? (() => { });
+        this.currentDelayMs = this.floorMs;
+    }
+    get currentDelay() {
+        return this.currentDelayMs;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    /** Arm the loop. Idempotent: a second start while running is a no-op. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.generation += 1;
+        this.currentDelayMs = this.floorMs;
+        this.schedule(0, this.generation);
+    }
+    /** Disarm the loop. Idempotent. An in-flight tick is allowed to finish but cannot reschedule. */
+    stop() {
+        this.running = false;
+        this.generation += 1;
+        if (this.handle !== null) {
+            this.timer.clear(this.handle);
+            this.handle = null;
+        }
+    }
+    /**
+     * Run exactly one lease pass. Skips (returns false) if a previous run is still
+     * in flight, so a slow tick never overlaps itself. A skipped tick does NOT
+     * feed the backoff state machine. Errors are routed to onError and treated as
+     * idle for backoff purposes.
+     */
+    async runOnce() {
+        if (this.inFlight)
+            return false;
+        this.inFlight = true;
+        const run = (async () => {
+            try {
+                return await this.tick();
+            }
+            catch (err) {
+                this.onError(err);
+                return false;
+            }
+            finally {
+                this.inFlight = false;
+                this.inFlightPromise = null;
+            }
+        })();
+        this.inFlightPromise = run;
+        return run;
+    }
+    /**
+     * Resolve once any in-flight tick has settled. `shutdown()` awaits this (under
+     * a bounded timeout) so a tick is drained rather than killed mid-flight
+     * (PRD-018a NEC-033). The tracked promise never rejects (errors are routed to
+     * `onError` inside `runOnce`), so awaiting it is safe.
+     */
+    async whenIdle() {
+        const inflight = this.inFlightPromise;
+        if (inflight !== null)
+            await inflight;
+    }
+    schedule(delayMs, gen) {
+        if (!this.running || gen !== this.generation)
+            return;
+        this.handle = this.timer.set(() => {
+            void this.pump(gen);
+        }, delayMs);
+    }
+    async pump(gen) {
+        if (!this.running || gen !== this.generation)
+            return;
+        const didWork = await this.runOnce();
+        // A stop()/start() may have happened while the tick was in flight; if so this
+        // is a stale generation and must not reschedule (that would leave two active
+        // schedules on one loop).
+        if (!this.running || gen !== this.generation)
+            return;
+        // Backoff: schedule the NEXT tick at the current delay, then advance the
+        // delay for the tick after that. A tick that did work resets to the floor;
+        // an idle tick steps toward the ceiling. This makes the first idle tick fire
+        // at the floor, and only consecutive idles grow the interval.
+        const nextDelay = didWork ? this.floorMs : this.currentDelayMs;
+        this.currentDelayMs = didWork
+            ? this.floorMs
+            : Math.min(this.ceilingMs, Math.max(this.floorMs, Math.round(this.currentDelayMs * this.backoffFactor)));
+        this.schedule(nextDelay, gen);
+    }
+}
+//# sourceMappingURL=poll-loop.js.map

package/dist/poll-loop.js.map

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

package/dist/portkey/config.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Portkey + activeModel resolution for nectar (PRD-010).
+ *
+ * Disabled or keyless Portkey is an explicit, testable `{ enabled: false }` state;
+ * this module never throws at import time. Env names follow the `NECTAR_*`
+ * convention used by `src/config.ts`.
+ */
+/** SIGNED OFF 2026-07-02 (decision #29): default description model id. */
+export declare const DEFAULT_ACTIVE_MODEL: "gemini-2.5-flash";
+/** Portkey is off or not configured enough to call the gateway. */
+export interface PortkeyDisabled {
+    readonly enabled: false;
+    readonly reason: "disabled" | "missing_api_key" | "missing_config_id";
+}
+/** Portkey is enabled with the credentials needed for chat completions. */
+export interface PortkeyEnabled {
+    readonly enabled: true;
+    readonly apiKey: string;
+    readonly configId: string;
+    readonly activeModel: string;
+}
+export type PortkeyRuntimeConfig = PortkeyDisabled | PortkeyEnabled;
+export interface PortkeyConfigOverrides {
+    readonly enabled?: boolean;
+    readonly apiKey?: string;
+    readonly configId?: string;
+    readonly activeModel?: string;
+    /** Injectable env bag for tests; defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve Portkey enablement, credentials, and the active description model.
+ *
+ * Env layer (each flagged [DEFAULT - confirm before implementation] in PRD-010):
+ *   - `NECTAR_PORTKEY_ENABLED`     explicit on/off gate (absent => off)
+ *   - `NECTAR_PORTKEY_API_KEY`     Portkey API key (required when enabled)
+ *   - `NECTAR_PORTKEY_CONFIG`      `portkey.config` / virtual-key id (required when enabled)
+ *   - `NECTAR_ACTIVE_MODEL`        description model id (default `gemini-2.5-flash`, decision #29)
+ */
+export declare function resolvePortkeyConfig(overrides?: PortkeyConfigOverrides): PortkeyRuntimeConfig;
+/**
+ * Keys exposed on {@link PortkeyRuntimeConfig} for AC-5 structural checks: no cache or
+ * guardrail toggle exists on this surface (DECISION #6).
+ */
+export declare const PORTKEY_CONFIG_SURFACE_KEYS: readonly ["enabled", "apiKey", "configId", "activeModel", "reason"];
+//# sourceMappingURL=config.d.ts.map

package/dist/portkey/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/portkey/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,EAAG,kBAA2B,CAAC;AAEhE,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;CACvE;AAED,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,cAAc,CAAC;AAEpE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,GAAE,sBAA2B,GAAG,oBAAoB,CA4BjG;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B,qEAM9B,CAAC"}

package/dist/portkey/config.js

@@ -0,0 +1,68 @@
+/**
+ * Portkey + activeModel resolution for nectar (PRD-010).
+ *
+ * Disabled or keyless Portkey is an explicit, testable `{ enabled: false }` state;
+ * this module never throws at import time. Env names follow the `NECTAR_*`
+ * convention used by `src/config.ts`.
+ */
+/** SIGNED OFF 2026-07-02 (decision #29): default description model id. */
+export const DEFAULT_ACTIVE_MODEL = "gemini-2.5-flash";
+function envStr(env, name) {
+    const raw = env[name];
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    return raw;
+}
+function envBool(env, name) {
+    const raw = envStr(env, name);
+    if (raw === undefined)
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on")
+        return true;
+    if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off")
+        return false;
+    return undefined;
+}
+/**
+ * Resolve Portkey enablement, credentials, and the active description model.
+ *
+ * Env layer (each flagged [DEFAULT - confirm before implementation] in PRD-010):
+ *   - `NECTAR_PORTKEY_ENABLED`     explicit on/off gate (absent => off)
+ *   - `NECTAR_PORTKEY_API_KEY`     Portkey API key (required when enabled)
+ *   - `NECTAR_PORTKEY_CONFIG`      `portkey.config` / virtual-key id (required when enabled)
+ *   - `NECTAR_ACTIVE_MODEL`        description model id (default `gemini-2.5-flash`, decision #29)
+ */
+export function resolvePortkeyConfig(overrides = {}) {
+    const env = overrides.env ?? process.env;
+    const enabled = overrides.enabled ??
+        envBool(env, "NECTAR_PORTKEY_ENABLED") ??
+        false;
+    if (!enabled) {
+        return { enabled: false, reason: "disabled" };
+    }
+    const apiKey = overrides.apiKey ?? envStr(env, "NECTAR_PORTKEY_API_KEY");
+    if (apiKey === undefined) {
+        return { enabled: false, reason: "missing_api_key" };
+    }
+    const configId = overrides.configId ?? envStr(env, "NECTAR_PORTKEY_CONFIG");
+    if (configId === undefined) {
+        return { enabled: false, reason: "missing_config_id" };
+    }
+    const activeModel = overrides.activeModel ??
+        envStr(env, "NECTAR_ACTIVE_MODEL") ??
+        DEFAULT_ACTIVE_MODEL;
+    return { enabled: true, apiKey, configId, activeModel };
+}
+/**
+ * Keys exposed on {@link PortkeyRuntimeConfig} for AC-5 structural checks: no cache or
+ * guardrail toggle exists on this surface (DECISION #6).
+ */
+export const PORTKEY_CONFIG_SURFACE_KEYS = [
+    "enabled",
+    "apiKey",
+    "configId",
+    "activeModel",
+    "reason",
+];
+//# sourceMappingURL=config.js.map

package/dist/portkey/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/portkey/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAA2B,CAAC;AA2BhE,SAAS,MAAM,CAAC,GAAsB,EAAE,IAAY;IAClD,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACtB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAC7D,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,OAAO,CAAC,GAAsB,EAAE,IAAY;IACnD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,KAAK,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC5G,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC9G,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAAoC,EAAE;IACzE,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IAEzC,MAAM,OAAO,GACX,SAAS,CAAC,OAAO;QACjB,OAAO,CAAC,GAAG,EAAE,wBAAwB,CAAC;QACtC,KAAK,CAAC;IAER,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAChD,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,IAAI,MAAM,CAAC,GAAG,EAAE,wBAAwB,CAAC,CAAC;IACzE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACvD,CAAC;IAED,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,IAAI,MAAM,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC;IAC5E,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,WAAW,GACf,SAAS,CAAC,WAAW;QACrB,MAAM,CAAC,GAAG,EAAE,qBAAqB,CAAC;QAClC,oBAAoB,CAAC;IAEvB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,SAAS;IACT,QAAQ;IACR,UAAU;IACV,aAAa;IACb,QAAQ;CACA,CAAC"}