gitnexus 1.6.4-rc.11 → 1.6.4-rc.111

package/README.md

@@ -156,6 +156,7 @@ gitnexus analyze --embeddings    # Enable embedding generation (slower, better s
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
 gitnexus analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
+gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
 gitnexus index                   # Register an existing .gitnexus/ folder into the global registry
@@ -295,6 +296,25 @@ If `npm install -g gitnexus` fails on native modules:
 npm install -g gitnexus
 ```
 
+### Analyze warns about unavailable FTS or VECTOR extensions
+
+GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process `INSTALL` if `LOAD` fails and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
+
+Configure the behavior with two environment variables:
+
+| Variable | Values | Default | Effect |
+|----------|--------|---------|--------|
+| `GITNEXUS_LBUG_EXTENSION_INSTALL` | `auto`, `load-only`, `never` | `auto` | `auto` runs one bounded INSTALL if LOAD fails. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely. |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer | `15000` | Wall-clock budget for the out-of-process `INSTALL` child before it is killed. |
+
+```bash
+# Offline/airgapped: never reach the network for extensions
+GITNEXUS_LBUG_EXTENSION_INSTALL=load-only npx gitnexus analyze
+
+# Slow network: give extension downloads more time
+GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS=30000 npx gitnexus analyze
+```
+
 ### Analysis runs out of memory
 
 For very large repositories:
@@ -323,6 +343,21 @@ npx gitnexus analyze
 
 Values above **32768 KB (32 MB)** are clamped to the tree-sitter parser ceiling; invalid values fall back to the 512 KB default with a one-time warning. When an override is active, `analyze` prints the effective threshold in its startup banner (e.g. `GITNEXUS_MAX_FILE_SIZE: effective threshold 2048KB (default 512KB)`).
 
+### Analyze reports a worker timeout
+
+Worker parse timeouts are recoverable. GitNexus retries stalled worker jobs with backoff, splits large jobs to isolate slow files, and falls back to the sequential parser when needed. If a large repository needs more time per worker job, use either:
+
+```bash
+# CLI flag, in seconds
+npx gitnexus analyze --worker-timeout 60
+
+# Environment variable, in milliseconds
+export GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000
+npx gitnexus analyze
+```
+
+For repositories with very large source files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget. The default is **8388608 bytes (8 MB)**.
+
 ## Privacy
 
 - All processing happens locally on your machine

package/dist/_shared/index.d.ts

@@ -48,6 +48,14 @@ export { buildScopeTree, canParentScope, ScopeTreeInvariantError, } from './scop
 export type { ScopeTree } from './scope-resolution/scope-tree.js';
 export { buildPositionIndex } from './scope-resolution/position-index.js';
 export type { PositionIndex } from './scope-resolution/position-index.js';
+export { withRetry, computeBackoffMs } from './integrations/retry.js';
+export type { RetryOptions, RetryDecision } from './integrations/retry.js';
+export { CircuitBreaker, CircuitOpenError, getBreaker } from './integrations/circuit-breaker.js';
+export type { CircuitBreakerOptions } from './integrations/circuit-breaker.js';
+export { resilientFetch, ResilientFetchExhaustedError, RETRY_AFTER_CAP_MS, parseRetryAfter, } from './integrations/resilient-fetch.js';
+export type { ResilientFetchOptions } from './integrations/resilient-fetch.js';
+export { UNDERSTAND_QUICKLY_DISPATCH_URL, UNDERSTAND_QUICKLY_EVENT_TYPE, UNDERSTAND_QUICKLY_TOKEN_ENV, buildUqDispatchPayload, isValidOwnerRepo, parseOwnerRepoFromRemote, stripGitSuffix, } from './integrations/understand-quickly.js';
+export type { UqDispatchPayload } from './integrations/understand-quickly.js';
 export { diffResolutions } from './scope-resolution/shadow/diff.js';
 export type { ShadowAgreement, ShadowCallsite, ShadowDiff, } from './scope-resolution/shadow/diff.js';
 export { aggregateDiffs } from './scope-resolution/shadow/aggregate.js';

package/dist/_shared/index.d.ts.map

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

package/dist/_shared/index.js

@@ -33,6 +33,15 @@ export { CLASS_KINDS, METHOD_KINDS, FIELD_KINDS } from './scope-resolution/regis
 export { makeScopeId, clearScopeIdInternPool } from './scope-resolution/scope-id.js';
 export { buildScopeTree, canParentScope, ScopeTreeInvariantError, } from './scope-resolution/scope-tree.js';
 export { buildPositionIndex } from './scope-resolution/position-index.js';
+// Resilient fetch primitives — bounded retries + per-process circuit breaker.
+// Test-only helpers (`__resetBreakerRegistry__`, `classifyOutcome`) are
+// reachable via the separate `gitnexus-shared/test-helpers` subpath; do
+// NOT add them here. Production consumers must not call them.
+export { withRetry, computeBackoffMs } from './integrations/retry.js';
+export { CircuitBreaker, CircuitOpenError, getBreaker } from './integrations/circuit-breaker.js';
+export { resilientFetch, ResilientFetchExhaustedError, RETRY_AFTER_CAP_MS, parseRetryAfter, } from './integrations/resilient-fetch.js';
+// Understand-Quickly registry integration (opt-in)
+export { UNDERSTAND_QUICKLY_DISPATCH_URL, UNDERSTAND_QUICKLY_EVENT_TYPE, UNDERSTAND_QUICKLY_TOKEN_ENV, buildUqDispatchPayload, isValidOwnerRepo, parseOwnerRepoFromRemote, stripGitSuffix, } from './integrations/understand-quickly.js';
 // Shadow-mode diff + aggregation (RFC §6.3; Ring 2 SHARED #918)
 export { diffResolutions } from './scope-resolution/shadow/diff.js';
 export { aggregateDiffs } from './scope-resolution/shadow/aggregate.js';

package/dist/_shared/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAiCjG,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAGxE,yDAAyD;AACzD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AAGvD,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAGrF,gEAAgE;AAChE,yEAAyE;AACzE,2DAA2D;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAOxE,oFAAoF;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAMvF,uEAAuE;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,0CAA0C,CAAC;AAUpE,sEAAsE;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AAErF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAKvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AAKrF,OAAO,EAAE,UAAU,EAAE,MAAM,8CAA8C,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,MAAM,mDAAmD,CAAC;AAEpF,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAEpG,OAAO,EACL,gCAAgC,EAChC,kBAAkB,GACnB,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AAQlG,2EAA2E;AAC3E,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAErF,OAAO,EACL,cAAc,EACd,cAAc,EACd,uBAAuB,GACxB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAG1E,gEAAgE;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMpE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAiCjG,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAGxE,yDAAyD;AACzD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AAGvD,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAGrF,gEAAgE;AAChE,yEAAyE;AACzE,2DAA2D;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAOxE,oFAAoF;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAMvF,uEAAuE;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,0CAA0C,CAAC;AAUpE,sEAAsE;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AAErF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAKvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AAKrF,OAAO,EAAE,UAAU,EAAE,MAAM,8CAA8C,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,MAAM,mDAAmD,CAAC;AAEpF,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAEpG,OAAO,EACL,gCAAgC,EAChC,kBAAkB,GACnB,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AAQlG,2EAA2E;AAC3E,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAErF,OAAO,EACL,cAAc,EACd,cAAc,EACd,uBAAuB,GACxB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAG1E,8EAA8E;AAC9E,wEAAwE;AACxE,wEAAwE;AACxE,8DAA8D;AAC9D,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEtE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAEjG,OAAO,EACL,cAAc,EACd,4BAA4B,EAC5B,kBAAkB,EAClB,eAAe,GAChB,MAAM,mCAAmC,CAAC;AAG3C,mDAAmD;AACnD,OAAO,EACL,+BAA+B,EAC/B,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,GACf,MAAM,sCAAsC,CAAC;AAG9C,gEAAgE;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMpE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC"}

package/dist/_shared/integrations/circuit-breaker.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Per-process circuit breaker.
+ *
+ * Closed -> Open transition fires after `failureThreshold` consecutive
+ * failures. While Open, `check` throws `CircuitOpenError` until
+ * `cooldownMs` has elapsed since the breaker tripped. The first call
+ * after the cooldown enters Half-Open and consumes the *probe permit*:
+ * a recorded success returns to Closed; a recorded failure flips back
+ * to Open with a fresh timestamp.
+ *
+ * Half-open admits exactly one in-flight probe at a time. Concurrent
+ * callers attempting `check()` while a probe is outstanding receive
+ * `CircuitOpenError` with `retryAfterMs = halfOpenRetryAfterMs` (default
+ * 1000ms; configurable). This prevents the recovery-time thundering
+ * herd that defeats the breaker's "fail fast" promise.
+ *
+ * Outcome reporting splits permit-release from state-resolution:
+ *   - `recordSuccess` — releases the probe permit, resets the failure
+ *     counter, transitions to Closed. Reserved for true 2xx/3xx outcomes.
+ *   - `recordFailure` — releases the probe permit, increments the
+ *     consecutive-failure counter, transitions to Open with a fresh
+ *     `openedAt` (when called from Half-Open or when the threshold
+ *     trips from Closed).
+ *   - `recordNeutral` — releases the probe permit, BUT leaves state and
+ *     counter untouched. Used for outcomes that are neither evidence of
+ *     backend health nor evidence of backend failure (caller-driven
+ *     cancellation, local timeout, terminal 4xx client errors). Critical
+ *     design point: if `recordNeutral` did not release the permit, a
+ *     single `TimeoutError` from per-attempt `AbortSignal.timeout` would
+ *     route through `recordNeutral` and permanently park the breaker in
+ *     half-open until process restart. Releasing the permit while leaving
+ *     state half-open keeps the "neutral doesn't claim health" semantic
+ *     without creating that wedge.
+ *
+ * Pairing invariant: every successful `check()` MUST be paired with
+ * exactly one `record*()` on every code path including throws. Direct
+ * consumers should wrap the protected operation in `try/finally`:
+ *
+ *   breaker.check();
+ *   try {
+ *     const result = await operation();
+ *     breaker.recordSuccess();
+ *     return result;
+ *   } catch (err) {
+ *     // classify err and call recordFailure / recordNeutral / etc.
+ *     throw err;
+ *   }
+ *
+ * `resilientFetch`'s catch-all on `fetchImpl` already satisfies this
+ * for that consumer.
+ *
+ * Atomicity model: the half-open gate relies on JavaScript event-loop
+ * single-threadedness within a synchronous `check()` body. There is no
+ * `await` inside `check()`; concurrent callers serialize on microtask
+ * order, and exactly one observes `probeInFlight === false`. Do not
+ * introduce `await` inside `check()` without revisiting the gate. If
+ * this code is ever ported to a runtime with shared-memory threads
+ * (Node `worker_threads` with `SharedArrayBuffer`, Web Workers with
+ * shared registries), the boolean must become an atomic CAS — Resilience4j
+ * and Hystrix use atomic permits *because* they run in JVM thread pools.
+ *
+ * Runtime-agnostic: depends only on a `now()` clock and standard JS —
+ * no Node-only imports. Tests inject `now` to advance the clock
+ * deterministically without `vi.useFakeTimers()`.
+ */
+export declare class CircuitOpenError extends Error {
+    readonly name = "CircuitOpenError";
+    /** Approximate wait time before the breaker may transition to Half-Open
+     *  (or before the in-flight probe is expected to resolve). */
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number, key?: string);
+}
+export interface CircuitBreakerOptions {
+    /** Consecutive failures required to trip Closed -> Open. */
+    failureThreshold?: number;
+    /** Milliseconds Open before the next call may probe (Half-Open). */
+    cooldownMs?: number;
+    /**
+     * Milliseconds to suggest in `CircuitOpenError.retryAfterMs` when the
+     * breaker is Half-Open with the probe permit consumed. Default 1000ms.
+     * Consumers with long-running protected ops (LLM streaming, large
+     * uploads) should raise this — the cooldown clock is no longer the
+     * right answer because cooldown has elapsed. Returning 0 invites
+     * retry storms; returning the full cooldown misleads about wait.
+     */
+    halfOpenRetryAfterMs?: number;
+    /** Optional key for error messages and registry lookups. */
+    key?: string;
+    /** Clock override — defaults to `Date.now`. Tests inject deterministic time. */
+    now?: () => number;
+}
+type State = 'closed' | 'open' | 'half-open';
+export declare class CircuitBreaker {
+    private readonly failureThreshold;
+    private readonly cooldownMs;
+    private readonly halfOpenRetryAfterMs;
+    private readonly key;
+    private readonly now;
+    private state;
+    private consecutiveFailures;
+    private openedAt;
+    /**
+     * True between a successful `check()` and the next `record*()` call
+     * during Half-Open. Gates concurrent callers from stampeding a still-
+     * recovering dependency. Boolean rather than counter — single-permit
+     * is the conservative end of the Hystrix/Resilience4j spectrum.
+     */
+    private probeInFlight;
+    constructor(opts?: CircuitBreakerOptions);
+    /**
+     * Throw `CircuitOpenError` if the breaker won't admit this call.
+     * Otherwise consume the half-open probe permit (if applicable) and
+     * return so the caller can attempt the protected work.
+     *
+     * Three rejection paths:
+     *   1. Open and still in cooldown → throws with `retryAfterMs` =
+     *      remaining cooldown.
+     *   2. Open with cooldown elapsed AND a probe is already in flight
+     *      (race: another caller transitioned to half-open and grabbed
+     *      the permit on a microtask before us) → throws with
+     *      `halfOpenRetryAfterMs`.
+     *   3. Half-Open with probe in flight → throws with `halfOpenRetryAfterMs`.
+     *
+     * **Pairing invariant**: every successful return from `check()` MUST
+     * be paired with exactly one `recordSuccess` / `recordFailure` /
+     * `recordNeutral` on every code path including thrown exceptions.
+     * Failing to pair leaves the probe permit consumed forever and
+     * wedges the breaker. See file-header JSDoc for the canonical
+     * try/finally pattern.
+     */
+    check(): void;
+    recordSuccess(): void;
+    recordFailure(): void;
+    /**
+     * Releases the probe permit BUT leaves state and counter untouched.
+     * Use when an attempt produced a response or error that should not
+     * influence breaker health in either direction — caller-driven aborts,
+     * local AbortSignal timeouts, terminal 4xx client errors.
+     *
+     * Why permit-release-without-state-resolution: if `recordNeutral` did
+     * not clear `probeInFlight`, a single `TimeoutError` from per-attempt
+     * `AbortSignal.timeout` (which routes through neutral classification)
+     * would permanently park the breaker in half-open. Since timeouts are
+     * an *expected* outcome under flaky-dependency conditions, the cited
+     * "per-attempt timeout bounds the stuck state" mitigation would itself
+     * be the trigger for a permanent wedge. Releasing the permit closes
+     * that loop while keeping the "neutral doesn't claim dependency
+     * health" semantic.
+     *
+     * Calling `recordSuccess` for these would erase legitimate prior
+     * failure signal; calling `recordFailure` would trip the breaker for
+     * outcomes the backend isn't responsible for.
+     */
+    recordNeutral(): void;
+    /**
+     * Pure read — no state mutation, no permit accounting. Returns the
+     * *would-be* state at the current instant: 'half-open' if the breaker
+     * is open with cooldown elapsed (regardless of whether a probe is in
+     * flight), 'open' if open and still in cooldown, 'closed' otherwise.
+     *
+     * Inspection-only; safe to call from tests without consuming a probe
+     * permit. The implicit Open -> Half-Open transition that mutates
+     * `state` lives in `check()` only.
+     */
+    getState(): State;
+    getConsecutiveFailures(): number;
+    /** Inspection-only test accessor for the half-open probe permit. */
+    isProbeInFlight(): boolean;
+    /** Timestamp (ms since epoch) when the breaker last transitioned to Open,
+     *  or `null` if it's currently Closed. Useful for computing remaining
+     *  cooldown without consuming a probe permit via `check()`. */
+    getOpenedAt(): number | null;
+    /** Configured cooldown duration in milliseconds. */
+    getCooldownMs(): number;
+}
+export declare function getBreaker(key: string, opts?: CircuitBreakerOptions): CircuitBreaker;
+/**
+ * Test-only: clear all registered breakers. Tests must call this in
+ * `beforeEach` to prevent breaker state from leaking across test cases.
+ */
+export declare function __resetBreakerRegistry__(): void;
+export {};
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/_shared/integrations/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/integrations/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAsB;IAC5C;kEAC8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,YAAY,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;CAQ/C;AAED,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,KAAK,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE7C,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,QAAQ,CAAuB;IACvC;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAAS;gBAElB,IAAI,GAAE,qBAA0B;IAQ5C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,IAAI,IAAI;IAqBb,aAAa,IAAI,IAAI;IAOrB,aAAa,IAAI,IAAI;IASrB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,aAAa,IAAI,IAAI;IAKrB;;;;;;;;;OASG;IACH,QAAQ,IAAI,KAAK;IAOjB,sBAAsB,IAAI,MAAM;IAGhC,oEAAoE;IACpE,eAAe,IAAI,OAAO;IAG1B;;mEAE+D;IAC/D,WAAW,IAAI,MAAM,GAAG,IAAI;IAG5B,oDAAoD;IACpD,aAAa,IAAI,MAAM;CAGxB;AAUD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,cAAc,CAOpF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/_shared/integrations/circuit-breaker.js

@@ -0,0 +1,236 @@
+/**
+ * Per-process circuit breaker.
+ *
+ * Closed -> Open transition fires after `failureThreshold` consecutive
+ * failures. While Open, `check` throws `CircuitOpenError` until
+ * `cooldownMs` has elapsed since the breaker tripped. The first call
+ * after the cooldown enters Half-Open and consumes the *probe permit*:
+ * a recorded success returns to Closed; a recorded failure flips back
+ * to Open with a fresh timestamp.
+ *
+ * Half-open admits exactly one in-flight probe at a time. Concurrent
+ * callers attempting `check()` while a probe is outstanding receive
+ * `CircuitOpenError` with `retryAfterMs = halfOpenRetryAfterMs` (default
+ * 1000ms; configurable). This prevents the recovery-time thundering
+ * herd that defeats the breaker's "fail fast" promise.
+ *
+ * Outcome reporting splits permit-release from state-resolution:
+ *   - `recordSuccess` — releases the probe permit, resets the failure
+ *     counter, transitions to Closed. Reserved for true 2xx/3xx outcomes.
+ *   - `recordFailure` — releases the probe permit, increments the
+ *     consecutive-failure counter, transitions to Open with a fresh
+ *     `openedAt` (when called from Half-Open or when the threshold
+ *     trips from Closed).
+ *   - `recordNeutral` — releases the probe permit, BUT leaves state and
+ *     counter untouched. Used for outcomes that are neither evidence of
+ *     backend health nor evidence of backend failure (caller-driven
+ *     cancellation, local timeout, terminal 4xx client errors). Critical
+ *     design point: if `recordNeutral` did not release the permit, a
+ *     single `TimeoutError` from per-attempt `AbortSignal.timeout` would
+ *     route through `recordNeutral` and permanently park the breaker in
+ *     half-open until process restart. Releasing the permit while leaving
+ *     state half-open keeps the "neutral doesn't claim health" semantic
+ *     without creating that wedge.
+ *
+ * Pairing invariant: every successful `check()` MUST be paired with
+ * exactly one `record*()` on every code path including throws. Direct
+ * consumers should wrap the protected operation in `try/finally`:
+ *
+ *   breaker.check();
+ *   try {
+ *     const result = await operation();
+ *     breaker.recordSuccess();
+ *     return result;
+ *   } catch (err) {
+ *     // classify err and call recordFailure / recordNeutral / etc.
+ *     throw err;
+ *   }
+ *
+ * `resilientFetch`'s catch-all on `fetchImpl` already satisfies this
+ * for that consumer.
+ *
+ * Atomicity model: the half-open gate relies on JavaScript event-loop
+ * single-threadedness within a synchronous `check()` body. There is no
+ * `await` inside `check()`; concurrent callers serialize on microtask
+ * order, and exactly one observes `probeInFlight === false`. Do not
+ * introduce `await` inside `check()` without revisiting the gate. If
+ * this code is ever ported to a runtime with shared-memory threads
+ * (Node `worker_threads` with `SharedArrayBuffer`, Web Workers with
+ * shared registries), the boolean must become an atomic CAS — Resilience4j
+ * and Hystrix use atomic permits *because* they run in JVM thread pools.
+ *
+ * Runtime-agnostic: depends only on a `now()` clock and standard JS —
+ * no Node-only imports. Tests inject `now` to advance the clock
+ * deterministically without `vi.useFakeTimers()`.
+ */
+export class CircuitOpenError extends Error {
+    name = 'CircuitOpenError';
+    /** Approximate wait time before the breaker may transition to Half-Open
+     *  (or before the in-flight probe is expected to resolve). */
+    retryAfterMs;
+    constructor(retryAfterMs, key) {
+        super(key
+            ? `Circuit '${key}' is open; retry in ${Math.ceil(retryAfterMs / 1000)}s`
+            : `Circuit is open; retry in ${Math.ceil(retryAfterMs / 1000)}s`);
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class CircuitBreaker {
+    failureThreshold;
+    cooldownMs;
+    halfOpenRetryAfterMs;
+    key;
+    now;
+    state = 'closed';
+    consecutiveFailures = 0;
+    openedAt = null;
+    /**
+     * True between a successful `check()` and the next `record*()` call
+     * during Half-Open. Gates concurrent callers from stampeding a still-
+     * recovering dependency. Boolean rather than counter — single-permit
+     * is the conservative end of the Hystrix/Resilience4j spectrum.
+     */
+    probeInFlight = false;
+    constructor(opts = {}) {
+        this.failureThreshold = opts.failureThreshold ?? 3;
+        this.cooldownMs = opts.cooldownMs ?? 30_000;
+        this.halfOpenRetryAfterMs = opts.halfOpenRetryAfterMs ?? 1_000;
+        this.key = opts.key;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /**
+     * Throw `CircuitOpenError` if the breaker won't admit this call.
+     * Otherwise consume the half-open probe permit (if applicable) and
+     * return so the caller can attempt the protected work.
+     *
+     * Three rejection paths:
+     *   1. Open and still in cooldown → throws with `retryAfterMs` =
+     *      remaining cooldown.
+     *   2. Open with cooldown elapsed AND a probe is already in flight
+     *      (race: another caller transitioned to half-open and grabbed
+     *      the permit on a microtask before us) → throws with
+     *      `halfOpenRetryAfterMs`.
+     *   3. Half-Open with probe in flight → throws with `halfOpenRetryAfterMs`.
+     *
+     * **Pairing invariant**: every successful return from `check()` MUST
+     * be paired with exactly one `recordSuccess` / `recordFailure` /
+     * `recordNeutral` on every code path including thrown exceptions.
+     * Failing to pair leaves the probe permit consumed forever and
+     * wedges the breaker. See file-header JSDoc for the canonical
+     * try/finally pattern.
+     */
+    check() {
+        if (this.state === 'open' && this.openedAt !== null) {
+            const elapsed = this.now() - this.openedAt;
+            if (elapsed < this.cooldownMs) {
+                throw new CircuitOpenError(this.cooldownMs - elapsed, this.key);
+            }
+            // Cooldown elapsed — transition to Half-Open. The very next
+            // `probeInFlight` check below decides whether THIS caller gets
+            // the permit or hits the gate.
+            this.state = 'half-open';
+        }
+        if (this.state === 'half-open') {
+            if (this.probeInFlight) {
+                throw new CircuitOpenError(this.halfOpenRetryAfterMs, this.key);
+            }
+            this.probeInFlight = true;
+        }
+        // Closed state falls through silently.
+    }
+    recordSuccess() {
+        this.probeInFlight = false;
+        this.consecutiveFailures = 0;
+        this.state = 'closed';
+        this.openedAt = null;
+    }
+    recordFailure() {
+        this.probeInFlight = false;
+        this.consecutiveFailures += 1;
+        if (this.state === 'half-open' || this.consecutiveFailures >= this.failureThreshold) {
+            this.state = 'open';
+            this.openedAt = this.now();
+        }
+    }
+    /**
+     * Releases the probe permit BUT leaves state and counter untouched.
+     * Use when an attempt produced a response or error that should not
+     * influence breaker health in either direction — caller-driven aborts,
+     * local AbortSignal timeouts, terminal 4xx client errors.
+     *
+     * Why permit-release-without-state-resolution: if `recordNeutral` did
+     * not clear `probeInFlight`, a single `TimeoutError` from per-attempt
+     * `AbortSignal.timeout` (which routes through neutral classification)
+     * would permanently park the breaker in half-open. Since timeouts are
+     * an *expected* outcome under flaky-dependency conditions, the cited
+     * "per-attempt timeout bounds the stuck state" mitigation would itself
+     * be the trigger for a permanent wedge. Releasing the permit closes
+     * that loop while keeping the "neutral doesn't claim dependency
+     * health" semantic.
+     *
+     * Calling `recordSuccess` for these would erase legitimate prior
+     * failure signal; calling `recordFailure` would trip the breaker for
+     * outcomes the backend isn't responsible for.
+     */
+    recordNeutral() {
+        this.probeInFlight = false;
+        // State and consecutiveFailures are preserved by design.
+    }
+    /**
+     * Pure read — no state mutation, no permit accounting. Returns the
+     * *would-be* state at the current instant: 'half-open' if the breaker
+     * is open with cooldown elapsed (regardless of whether a probe is in
+     * flight), 'open' if open and still in cooldown, 'closed' otherwise.
+     *
+     * Inspection-only; safe to call from tests without consuming a probe
+     * permit. The implicit Open -> Half-Open transition that mutates
+     * `state` lives in `check()` only.
+     */
+    getState() {
+        if (this.state === 'open' && this.openedAt !== null) {
+            const elapsed = this.now() - this.openedAt;
+            if (elapsed >= this.cooldownMs)
+                return 'half-open';
+        }
+        return this.state;
+    }
+    getConsecutiveFailures() {
+        return this.consecutiveFailures;
+    }
+    /** Inspection-only test accessor for the half-open probe permit. */
+    isProbeInFlight() {
+        return this.probeInFlight;
+    }
+    /** Timestamp (ms since epoch) when the breaker last transitioned to Open,
+     *  or `null` if it's currently Closed. Useful for computing remaining
+     *  cooldown without consuming a probe permit via `check()`. */
+    getOpenedAt() {
+        return this.openedAt;
+    }
+    /** Configured cooldown duration in milliseconds. */
+    getCooldownMs() {
+        return this.cooldownMs;
+    }
+}
+// ─── Per-process registry ────────────────────────────────────────────
+//
+// Single shared map keyed on caller-chosen strings. Used by
+// `resilient-fetch.ts` so multiple call sites targeting the same logical
+// endpoint share breaker state. Per-process only — not persisted.
+const registry = new Map();
+export function getBreaker(key, opts) {
+    let breaker = registry.get(key);
+    if (!breaker) {
+        breaker = new CircuitBreaker({ ...opts, key });
+        registry.set(key, breaker);
+    }
+    return breaker;
+}
+/**
+ * Test-only: clear all registered breakers. Tests must call this in
+ * `beforeEach` to prevent breaker state from leaking across test cases.
+ */
+export function __resetBreakerRegistry__() {
+    registry.clear();
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/_shared/integrations/circuit-breaker.js.map

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

package/dist/_shared/integrations/resilient-fetch.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `resilientFetch` — fetch wrapped in retry + circuit breaker, with
+ * GitHub-flavoured retry classification baked in (Retry-After parsing,
+ * 401/403/404/422 treated as terminal client errors).
+ *
+ * Designed for the `gitnexus publish` GitHub `repository_dispatch`
+ * call, but the classification rules apply to any GitHub REST endpoint.
+ * Runtime-agnostic — no Node-only imports.
+ */
+import { CircuitBreaker, CircuitOpenError, type CircuitBreakerOptions } from './circuit-breaker.js';
+import { type RetryOptions } from './retry.js';
+export { CircuitOpenError };
+export interface ResilientFetchOptions {
+    /** Optional fetch implementation override. Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Logical key for the breaker. Defaults to `<host><pathname>` of the
+     * request URL — call sites targeting the same endpoint share breaker
+     * state regardless of query-string differences.
+     */
+    breakerKey?: string;
+    /** Per-call breaker override. Used for tests and one-off configuration. */
+    breaker?: CircuitBreaker;
+    /** Tuning knobs for the breaker registered under `breakerKey`. */
+    breakerOptions?: CircuitBreakerOptions;
+    /** Tuning knobs for the retry helper. */
+    retry?: Partial<Pick<RetryOptions, 'maxAttempts' | 'baseDelayMs' | 'capDelayMs'>> & {
+        sleep?: RetryOptions['sleep'];
+        random?: RetryOptions['random'];
+    };
+    /** Clock override propagated into Retry-After HTTP-date math and breaker. */
+    now?: () => number;
+}
+/** Cap on any single Retry-After wait — protects CLI from a buggy registry. */
+export declare const RETRY_AFTER_CAP_MS = 30000;
+/**
+ * Parse a `Retry-After` header value into milliseconds.
+ * Accepts either a delta-seconds integer (`"30"`) or an HTTP-date.
+ * Returns null on parse failure or negative deltas.
+ */
+export declare function parseRetryAfter(value: string | null, now?: () => number): number | null;
+/** Internal: outcome classification used by the resilientFetch loop. */
+type Outcome = {
+    kind: 'success';
+    resp: Response;
+} | {
+    kind: 'terminal-client';
+    resp: Response;
+} | {
+    kind: 'retryable-status';
+    resp: Response;
+    afterMs: number | undefined;
+} | {
+    kind: 'terminal-network';
+    err: unknown;
+} | {
+    kind: 'retryable-network';
+    err: unknown;
+};
+/** Exported for unit tests. */
+export declare function classifyOutcome(result: {
+    kind: 'error';
+    err: unknown;
+} | {
+    kind: 'response';
+    resp: Response;
+}, now: () => number): Outcome;
+/** Final error thrown when retries are exhausted on a 5xx / 429. */
+export declare class ResilientFetchExhaustedError extends Error {
+    readonly response: Response;
+    readonly name = "ResilientFetchExhaustedError";
+    constructor(response: Response);
+}
+/**
+ * Wrap `fetch` with bounded retries and a per-process circuit breaker.
+ *
+ * Semantics:
+ * - 5xx and 429 responses are retried; 429 honors `Retry-After` (capped).
+ * - Network throws are retried unless they are `TimeoutError` DOMExceptions.
+ * - Timeouts and 4xx (other than 429) are returned/thrown without retry
+ *   AND without incrementing the breaker — they reflect caller config
+ *   or local network state, not registry health.
+ * - Each `fetch` call carries the caller-supplied `signal` (e.g. an
+ *   `AbortSignal.timeout()`) — that timeout bounds each individual
+ *   attempt, not the whole retry sequence.
+ * - When the breaker is open, throws `CircuitOpenError` synchronously
+ *   without invoking `fetch`.
+ * - When retries are exhausted on a 5xx / 429, throws
+ *   `ResilientFetchExhaustedError` carrying the last response.
+ *
+ * Cumulative wall-clock budget:
+ *   maxAttempts × (per-attempt-timeout + capDelayMs)
+ *   With defaults (3, 500ms base, 5000ms cap) and a typical 15s per-attempt
+ *   timeout from the caller's signal, worst case is ~3 × (15s + 5s) = 60s.
+ *   Callers that want a tighter total bound should reduce `maxAttempts` or
+ *   wrap `resilientFetch` in their own outer `AbortSignal.timeout()`.
+ */
+export declare function resilientFetch(input: string | URL, init: RequestInit | undefined, opts?: ResilientFetchOptions): Promise<Response>;
+//# sourceMappingURL=resilient-fetch.d.ts.map

package/dist/_shared/integrations/resilient-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilient-fetch.d.ts","sourceRoot":"","sources":["../../src/integrations/resilient-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,cAAc,EACd,gBAAgB,EAEhB,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,kEAAkE;IAClE,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,aAAa,GAAG,aAAa,GAAG,YAAY,CAAC,CAAC,GAAG;QAClF,KAAK,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;QAC9B,MAAM,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;KACjC,CAAC;IACF,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAQzC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,GAAE,MAAM,MAAiB,GAAG,MAAM,GAAG,IAAI,CAejG;AAED,wEAAwE;AACxE,KAAK,OAAO,GACR;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhD,+BAA+B;AAC/B,wBAAgB,eAAe,CAC7B,MAAM,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,EAC9E,GAAG,EAAE,MAAM,MAAM,GAChB,OAAO,CAiCT;AAcD,oEAAoE;AACpE,qBAAa,4BAA6B,SAAQ,KAAK;aAEzB,QAAQ,EAAE,QAAQ;IAD9C,SAAkB,IAAI,kCAAkC;gBAC5B,QAAQ,EAAE,QAAQ;CAG/C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,MAAM,GAAG,GAAG,EACnB,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,QAAQ,CAAC,CA8GnB"}